Package 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 Details

    • 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

    • 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 keys in the list of arguments are String or T 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

    • 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<org.javatuples.Pair<String,Object>> 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

    • getLabelsValue

      public static Optional<Set<String>> getLabelsValue(Object... keyValues)
      Extracts the value of the T.label key from the list of arguments as a Set of labels. Supports both single String values and Collection values for multi-label vertices.
      Parameters:
      keyValues - a list of key/value pairs
      Returns:
      the labels associated with T.label, or empty if not present
      Since:
      4.0.0

    • applyLabelsToVertex

      public static void applyLabelsToVertex(Vertex vertex, Object labelValue)
      Applies label value(s) to a vertex using addLabel semantics. Handles both single String and Collection<String> label values as used in mergeV onMatch maps.
      Parameters:
      vertex - the vertex to add labels to
      labelValue - the label value (String or Collection<String>)
      Since:
      4.0.0

    • 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(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(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)
      Checks if a key exists within a list of provided keys. Returns false if the key is null or if the Graph.Hidden. Returns true if no providedKeys are supplied.
      Parameters:
      key - must not be null

    • idExists

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