org.apache.tinkerpop.gremlin.structure.util

Class ElementHelper

java.lang.Object

org.apache.tinkerpop.gremlin.structure.util.ElementHelper

public final class ElementHelper
extends Object

Utility class supporting common functions for Element.

Author:

Marko A. Rodriguez (http://markorodriguez.com), Stephen Mallette (http://stephen.genoprime.com)

Method Summary

Modifier and Type	Method and Description
static boolean	areEqual(Edge a, Edge b)
static boolean	areEqual(Element a, Object b) A standard method for determining if two Element objects are equal.
static boolean	areEqual(Property a, Object b) A standard method for determining if two Property objects are equal.
static boolean	areEqual(VertexProperty a, Object b) A standard method for determining if two VertexProperty objects are equal.
static boolean	areEqual(VertexProperty a, VertexProperty b)
static boolean	areEqual(Vertex a, Vertex b)
static Map<String,Object>	asMap(Object... keyValues) Converts a set of key values to a Map.
static List<<any>>	asPairs(Object... keyValues) Convert a set of key values to a list of Pair objects.
static void	attachProperties(Element element, Object... propertyKeyValues) Assign key/value pairs as properties to an Element.
static void	attachProperties(Vertex vertex, Object... propertyKeyValues) Assign key/value pairs as properties to an Vertex.
static void	attachProperties(Vertex vertex, VertexProperty.Cardinality cardinality, Object... propertyKeyValues) Assign key/value pairs as properties to a Vertex.
static Optional<Object>	getIdValue(Object... keyValues) Extracts the value of the T.id key from the list of arguments.
static Set<String>	getKeys(Object... keyValues) Gets the list of keys from the key values.
static Optional<String>	getLabelValue(Object... keyValues) Extracts the value of the T.label key from the list of arguments.
static Object[]	getProperties(Element element, boolean includeId, boolean includeLabel, Set<String> propertiesToCopy) Retrieve the properties associated with a particular element.
static int	hashCode(Element element) If two Element instances are equal, then they must have the same hash codes.
static int	hashCode(Property property) If two Property instances are equal, then they must have the same hash codes.
static boolean	haveEqualIds(Element a, Element b) Simply tests if the value returned from Element.id() are equal().
static boolean	idExists(Object id, Object... providedIds)
static boolean	keyExists(String key, String... providedKeys)
static void	legalPropertyKeyValueArray(Object... propertyKeyValues) Determines whether a list of key/values are legal, ensuring that there are an even number of values submitted and that the key values in the list of arguments are String or Element objects.
static Map<String,Property>	propertyMap(Element element, String... propertyKeys)
static Map<String,Object>	propertyValueMap(Element element, String... propertyKeys)
static Optional<Object[]>	remove(String keyToRemove, Object... keyValues) Remove a key from the set of key/value pairs.
static Optional<Object[]>	remove(T accessor, Object... keyValues) Removes an accessor from the set of key/value pairs.
static Object[]	replaceKey(Object[] keyValues, Object oldKey, Object newKey) Replaces one key with a different key.
static <V> Optional<VertexProperty<V>>	stageVertexProperty(Vertex vertex, VertexProperty.Cardinality cardinality, String key, V value, Object... keyValues) This is a helper method for dealing with vertex property cardinality and typically used in Vertex.property(org.apache.tinkerpop.gremlin.structure.VertexProperty.Cardinality, String, Object, Object...).
static Object[]	upsert(Object[] keyValues, Object key, Object val) Append a key/value pair to a list of existing key/values.
static void	validateLabel(String label) Determine whether the Element label can be legally set.
static void	validateMixedElementIds(Class<? extends Element> clazz, Object... ids) Determine whether an array of ids are either all elements or ids of elements.
static void	validateProperty(String key, Object value) Determines whether the property key/value for the specified thing can be legally set.
static Map<String,List<VertexProperty>>	vertexPropertyMap(Vertex vertex, String... propertyKeys)
static Map<String,List>	vertexPropertyValueMap(Vertex vertex, String... propertyKeys)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

validateLabel

public static void validateLabel(String label)
                          throws IllegalArgumentException

Determine whether the Element label can be legally set. This is typically used as a pre-condition check.

Parameters:

label - the element label

Throws:

IllegalArgumentException - whether the label is legal and if not, a clear reason exception is provided

validateMixedElementIds

public static void validateMixedElementIds(Class<? extends Element> clazz,
                                           Object... ids)
                                    throws IllegalArgumentException

Determine whether an array of ids are either all elements or ids of elements. This is typically used as a pre-condition check.

Parameters:

clazz - the class of the element for which the ids will bind

ids - the ids that must be either elements or id objects, else Graph.Exceptions.idArgsMustBeEitherIdOrElement() is thrown.

Throws:

IllegalArgumentException

validateProperty

public static void validateProperty(String key,
                                    Object value)
                             throws IllegalArgumentException

Determines whether the property key/value for the specified thing can be legally set. This is typically used as a pre-condition check prior to setting a property.

Parameters:

key - the key of the property

value - the value of the property

Throws:

IllegalArgumentException - whether the key/value pair is legal and if not, a clear reason exception message is provided

legalPropertyKeyValueArray

public static void legalPropertyKeyValueArray(Object... propertyKeyValues)
                                       throws IllegalArgumentException

Determines whether a list of key/values are legal, ensuring that there are an even number of values submitted and that the key values in the list of arguments are String or Element objects.

Parameters:

propertyKeyValues - a list of key/value pairs

Throws:

IllegalArgumentException - if something in the pairs is illegal

getIdValue

public static Optional<Object> getIdValue(Object... keyValues)

Extracts the value of the T.id key from the list of arguments.

Parameters:

keyValues - a list of key/value pairs

Returns:

the value associated with T.id

Throws:

NullPointerException - if the value for the T.id key is null

remove

public static Optional<Object[]> remove(String keyToRemove,
                                        Object... keyValues)

Remove a key from the set of key/value pairs. Assumes that validations have already taken place to assure that key positions contain strings and that there are an even number of elements. If after removal there are no values left, the key value list is returned as empty.

Parameters:

keyToRemove - the key to remove

keyValues - the list to remove the accessor from

Returns:

the key/values without the specified accessor or an empty array if no values remain after removal

remove

public static Optional<Object[]> remove(T accessor,
                                        Object... keyValues)

Removes an accessor from the set of key/value pairs. Assumes that validations have already taken place to assure that key positions contain strings and that there are an even number of elements. If after removal there are no values left, the key value list is returned as empty.

Parameters:

accessor - to remove

keyValues - the list to remove the accessor from

Returns:

the key/values without the specified accessor or an empty array if no values remain after removal

upsert

public static Object[] upsert(Object[] keyValues,
                              Object key,
                              Object val)

Append a key/value pair to a list of existing key/values. If the key already exists in the keyValues then that value is overwritten with the provided value.

replaceKey

public static Object[] replaceKey(Object[] keyValues,
                                  Object oldKey,
                                  Object newKey)

Replaces one key with a different key.

Parameters:

keyValues - the list of key/values to alter

oldKey - the key to replace

newKey - the new key

asMap

public static Map<String,Object> asMap(Object... keyValues)

Converts a set of key values to a Map. Assumes that validations have already taken place to assure that key positions contain strings and that there are an even number of elements.

asPairs

public static List<<any>> asPairs(Object... keyValues)

Convert a set of key values to a list of Pair objects. Assumes that validations have already taken place to assure that key positions contain strings and that there are an even number of elements.

getKeys

public static Set<String> getKeys(Object... keyValues)

Gets the list of keys from the key values.

Parameters:

keyValues - a list of key/values pairs

getLabelValue

public static Optional<String> getLabelValue(Object... keyValues)

Extracts the value of the T.label key from the list of arguments.

Parameters:

keyValues - a list of key/value pairs

Returns:

the value associated with T.label

Throws:

ClassCastException - if the value of the label is not a String

NullPointerException - if the value for the T.label key is null

attachProperties

public static void attachProperties(Element element,
                                    Object... propertyKeyValues)

Assign key/value pairs as properties to an Element. If the value of T.id or T.label is in the set of pairs, then they are ignored.

Parameters:

element - the graph element to assign the propertyKeyValues

propertyKeyValues - the key/value pairs to assign to the element

Throws:

ClassCastException - if the value of the key is not a String

IllegalArgumentException - if the value of element is null

attachProperties

public static void attachProperties(Vertex vertex,
                                    Object... propertyKeyValues)

Assign key/value pairs as properties to an Vertex. If the value of T.id or T.label is in the set of pairs, then they are ignored. The VertexProperty.Cardinality of the key is determined from the Graph.Features.VertexFeatures.

Parameters:

vertex - the graph vertex to assign the propertyKeyValues

propertyKeyValues - the key/value pairs to assign to the element

Throws:

ClassCastException - if the value of the key is not a String

IllegalArgumentException - if the value of element is null

attachProperties

public static void attachProperties(Vertex vertex,
                                    VertexProperty.Cardinality cardinality,
                                    Object... propertyKeyValues)

Assign key/value pairs as properties to a Vertex. If the value of T.id or T.label is in the set of pairs, then they are ignored.

Parameters:

vertex - the vertex to attach the properties to

cardinality - the cardinality of the key value pair settings

propertyKeyValues - the key/value pairs to assign to the element

Throws:

ClassCastException - if the value of the key is not a String

IllegalArgumentException - if the value of element is null

stageVertexProperty

public static <V> Optional<VertexProperty<V>> stageVertexProperty(Vertex vertex,
                                                                  VertexProperty.Cardinality cardinality,
                                                                  String key,
                                                                  V value,
                                                                  Object... keyValues)

This is a helper method for dealing with vertex property cardinality and typically used in Vertex.property(org.apache.tinkerpop.gremlin.structure.VertexProperty.Cardinality, String, Object, Object...). If the cardinality is list, simply return Optional.empty(). If the cardinality is single, delete all existing properties of the provided key and return Optional.empty(). If the cardinality is set, find one that has the same key/value and attached the properties to it and return it. Else, if no equal value is found, return Optional.empty().

Type Parameters:

V - the type of the vertex property value

Parameters:

vertex - the vertex to stage a vertex property for

cardinality - the cardinality of the vertex property

key - the key of the vertex property

value - the value of the vertex property

keyValues - the properties of vertex property

Returns:

a vertex property if it has been found in set with equal value

getProperties

public static Object[] getProperties(Element element,
                                     boolean includeId,
                                     boolean includeLabel,
                                     Set<String> propertiesToCopy)

Retrieve the properties associated with a particular element. The result is a Object[] where odd indices are String keys and even indices are the values.

Parameters:

element - the element to retrieve properties from

includeId - include Element.ID in the key/value list

includeLabel - include Element.LABEL in the key/value list

propertiesToCopy - the properties to include with an empty list meaning copy all properties

Returns:

a key/value array of properties where odd indices are String keys and even indices are the values.

areEqual

public static boolean areEqual(Element a,
                               Object b)

A standard method for determining if two Element objects are equal. This method should be used by any Object.equals(Object) implementation to ensure consistent behavior. This method is used for Vertex, Edge, and VertexProperty.

Parameters:

a - The first Element

b - The second Element (as an Object)

Returns:

true if elements and equal and false otherwise

areEqual

public static boolean areEqual(Vertex a,
                               Vertex b)

areEqual

public static boolean areEqual(Edge a,
                               Edge b)

areEqual

public static boolean areEqual(VertexProperty a,
                               VertexProperty b)

areEqual

public static boolean areEqual(VertexProperty a,
                               Object b)

A standard method for determining if two VertexProperty objects are equal. This method should be used by any Object.equals(Object) implementation to ensure consistent behavior.

Parameters:

a - the first VertexProperty

b - the second VertexProperty

Returns:

true if equal and false otherwise

haveEqualIds

public static boolean haveEqualIds(Element a,
                                   Element b)

Simply tests if the value returned from Element.id() are equal().

Parameters:

a - the first Element

b - the second Element

Returns:

true if ids are equal and false otherwise

hashCode

public static int hashCode(Element element)

If two Element instances are equal, then they must have the same hash codes. This methods ensures consistent hashCode values.

Parameters:

element - the element to get the hashCode for

Returns:

the hash code of the element

hashCode

public static int hashCode(Property property)

If two Property instances are equal, then they must have the same hash codes. This methods ensures consistent hashCode values. For VertexProperty use hashCode(org.apache.tinkerpop.gremlin.structure.Element).

Parameters:

property - the property to get the hashCode for

Returns:

the hash code of the property

areEqual

public static boolean areEqual(Property a,
                               Object b)

A standard method for determining if two Property objects are equal. This method should be used by any Object.equals(Object) implementation to ensure consistent behavior.

Parameters:

a - the first Property

b - the second Property

Returns:

true if equal and false otherwise

propertyValueMap

public static Map<String,Object> propertyValueMap(Element element,
                                                  String... propertyKeys)

propertyMap

public static Map<String,Property> propertyMap(Element element,
                                               String... propertyKeys)

vertexPropertyValueMap

public static Map<String,List> vertexPropertyValueMap(Vertex vertex,
                                                      String... propertyKeys)

vertexPropertyMap

public static Map<String,List<VertexProperty>> vertexPropertyMap(Vertex vertex,
                                                                 String... propertyKeys)

keyExists

public static boolean keyExists(String key,
                                String... providedKeys)

idExists

public static boolean idExists(Object id,
                               Object... providedIds)