Package org.apache.tinkerpop.gremlin.structure.util

Class 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 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

      • 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

      • 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,
                                    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)

      • 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

      • vertexPropertyValueMap

        public static Map<String,​List> vertexPropertyValueMap​(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)