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

    All Methods Static Methods Concrete Methods
    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<org.javatuples.Pair<String,Object>>` | `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)` Checks if a key exists within a list of provided keys.
    `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 keys in the list of arguments are `String` or `T` 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(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 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`

    - #### 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)

Copyright © 2013–2022 Apache Software Foundation. All rights reserved.