Package org.apache.tinkerpop.gremlin.process.traversal.util

Class TraversalHelper

java.lang.Object
org.apache.tinkerpop.gremlin.process.traversal.util.TraversalHelper
public final class TraversalHelper extends Object
Utility class that provides functions that manipulate Traversal isntances. These functions are helpful when writing TraversalStrategy implementations.
Author:
Marko A. Rodriguez (http://markorodriguez.com), Stephen Mallette (http://stephen.genoprime.com)

  • Method Details

    • isLocalProperties

      public static boolean isLocalProperties(Traversal.Admin<?,?> traversal)
      Determines whether the given traversal only touches local vertex/edge properties (i.e. does not traverse the graph topology). This returns false if a step is encountered that walks the graph (e.g. VertexStep/EdgeVertexStep) or if a repeat's global children contain such steps. TraversalParent children are inspected recursively.

    • isLocalStarGraph

      public static boolean isLocalStarGraph(Traversal.Admin<?,?> traversal)
      Determines whether a traversal is confined to a single-star neighborhood of a starting vertex (i.e., a topologically local traversal over a vertex and its incident edges/adjacent vertices) without expanding further into the graph or pulling arbitrary properties that would require remote access. This method delegates to a state-machine helper and returns true if the traversal remains within the local star graph.

    • insertBeforeStep

      public static <S, E> void insertBeforeStep(Step<S,E> insertStep, Step<E,?> afterStep, Traversal.Admin<?,?> traversal)
      Insert a step before a specified step instance.
      Parameters:
      insertStep - the step to insert
      afterStep - the step to insert the new step before
      traversal - the traversal on which the action should occur

    • insertAfterStep

      public static <S, E> void insertAfterStep(Step<S,E> insertStep, Step<?,S> beforeStep, Traversal.Admin<?,?> traversal)
      Insert a step after a specified step instance.
      Parameters:
      insertStep - the step to insert
      beforeStep - the step to insert the new step after
      traversal - the traversal on which the action should occur

    • replaceStep

      public static <S, E> void replaceStep(Step<S,E> removeStep, Step<S,E> insertStep, Traversal.Admin<?,?> traversal)
      Replace a step with a new step. When a step is replaced, it is also removed from the GValueManager.
      Parameters:
      removeStep - the step to remove
      insertStep - the step to insert
      traversal - the traversal on which the action will occur

    • moveStep

      public static <S, E> void moveStep(Step<S,E> stepToMove, int indexToMoveTo, Traversal.Admin<?,?> traversal)
      Moves a step to a new position.
      Parameters:
      stepToMove - the step to move
      indexToMoveTo - the index in the traversal to move it to
      traversal - the traversal to move the step in which must be the same as the one assigned to the step

    • insertTraversal

      public static <S, E> Step<?,E> insertTraversal(Step<?,S> previousStep, Traversal.Admin<S,E> insertTraversal, Traversal.Admin<?,?> traversal)
      Inserts all steps from the supplied insertTraversal directly after the given previousStep in the specified traversal, preserving their order.
      Parameters:
      previousStep - the step after which to insert the traversal
      insertTraversal - the traversal whose steps will be inserted
      traversal - the traversal to receive the steps
      Returns:
      the last step that was inserted

    • insertTraversal

      public static <S, E> Step<?,E> insertTraversal(int insertIndex, Traversal.Admin<S,E> insertTraversal, Traversal.Admin<?,?> traversal)
      Inserts all steps from the supplied insertTraversal into the specified traversal starting at the given index. Steps are inserted in order.
      Parameters:
      insertIndex - the position at which to start inserting
      insertTraversal - the traversal whose steps will be inserted
      traversal - the traversal to receive the steps
      Returns:
      the last step that was inserted (or the existing step at insertIndex if no steps exist)

    • removeToTraversal

      public static <S, E> void removeToTraversal(Step<S,?> startStep, Step<?,E> endStep, Traversal.Admin<S,E> newTraversal)
      Removes steps from the traversal starting at startStep up to but not including endStep and appends them to newTraversal, preserving order.
      Parameters:
      startStep - the first step to move
      endStep - the terminal step at which to stop (not moved)
      newTraversal - the traversal to receive the moved steps

    • stepIndex

      public static <S, E> int stepIndex(Step<S,E> step, Traversal.Admin<?,?> traversal)
      Gets the index of a particular step in the Traversal.
      Parameters:
      step - the step to retrieve the index for
      traversal - the traversal to perform the action on
      Returns:
      the index of the step or -1 if the step is not present

    • getStepsOfClass

      public static <S> List<S> getStepsOfClass(Class<S> stepClass, Traversal.Admin<?,?> traversal)
      Returns all steps in the given traversal whose concrete class equals the supplied class. If the supplied class is an interface registered as a step contract, the method will match by exact equality to any of the registered concrete implementations for that contract. For example, calling this method with GraphStepContract will not match on the interface but instead will match on its GraphStepContract.CONCRETE_STEPS.
      Parameters:
      stepClass - the concrete step type to match, or a registered contract interface
      traversal - the traversal to scan
      Returns:
      a list of matching steps (preserving traversal order)

    • getStepsOfAssignableClass

      public static <S> List<S> getStepsOfAssignableClass(Class<S> stepClass, Traversal.Admin<?,?> traversal)
      Returns all steps in the given traversal that are instances of (i.e., assignable to) the supplied class.
      Parameters:
      stepClass - the class or interface to test with Class.isAssignableFrom(Class)
      traversal - the traversal to scan
      Returns:
      a list of matching steps (preserving traversal order)

    • getLastStepOfAssignableClass

      public static <S> Optional<S> getLastStepOfAssignableClass(Class<S> stepClass, Traversal.Admin<?,?> traversal)
      Returns the last step in the traversal that is assignable to the supplied class, if present.
      Parameters:
      stepClass - the class or interface to test with Class.isAssignableFrom(Class)
      traversal - the traversal to scan
      Returns:
      the last matching step or Optional.empty() if none found

    • getFirstStepOfAssignableClass

      public static <S> Optional<S> getFirstStepOfAssignableClass(Class<S> stepClass, Traversal.Admin<?,?> traversal)
      Returns the first step in the traversal that is assignable to the supplied class, if present.
      Parameters:
      stepClass - the class or interface to test with Class.isAssignableFrom(Class)
      traversal - the traversal to scan
      Returns:
      the first matching step or Optional.empty() if none found

    • getStepsOfAssignableClassRecursively

      public static <S> List<S> getStepsOfAssignableClassRecursively(Class<S> stepClass, Traversal.Admin<?,?> traversal)
      Recursively collects steps assignable to the supplied class from the traversal and all its child traversals (both local and global).
      Parameters:
      stepClass - the class or interface to test with Class.isAssignableFrom(Class)
      traversal - the root traversal to scan
      Returns:
      a list of matching steps found anywhere in the traversal tree

    • getStepsOfAssignableClassRecursively

      public static <S> List<S> getStepsOfAssignableClassRecursively(Scope scope, Class<S> stepClass, Traversal.Admin<?,?> traversal)
      Recursively collects steps assignable to the supplied class from the traversal and its child traversals scoped by the given Scope.
      Parameters:
      scope - whether to include local, global, or both child traversals (null for both)
      stepClass - the class or interface to test with Class.isAssignableFrom(Class)
      traversal - the root traversal to scan
      Returns:
      a list of matching steps found anywhere within the scoped traversal tree

    • getStepsOfAssignableClassRecursively

      public static List<Step<?,?>> getStepsOfAssignableClassRecursively(Traversal.Admin<?,?> traversal, Class<?>... stepClasses)
      Recursively collects steps that are assignable to any of the supplied classes from the traversal and all its child traversals (both local and global).
      Parameters:
      traversal - the root traversal to scan
      stepClasses - the classes or interfaces to test with Class.isAssignableFrom(Class)
      Returns:
      a list of matching steps found anywhere in the traversal tree

    • getStepsOfAssignableClassRecursivelyFromDepth

      public static List<Step<?,?>> getStepsOfAssignableClassRecursivelyFromDepth(Traversal.Admin<?,?> traversal, Class<?>... stepClasses)
      Recursively collects steps assignable to any of the supplied classes from the traversal and children, then orders the result by depth (deepest child steps first). Depth ordering is determined by DepthComparator.
      Parameters:
      traversal - the root traversal to scan
      stepClasses - the classes or interfaces to test with Class.isAssignableFrom(Class)
      Returns:
      a list of matching steps ordered from deepest to shallowest

    • isGlobalChild

      public static boolean isGlobalChild(Traversal.Admin<?,?> traversal)
      Determines whether the supplied traversal is a global child of its parent (as opposed to a local child). Walks up the parent chain until the root to make this determination.
      Parameters:
      traversal - the traversal to test
      Returns:
      true if the traversal is a global child; false if it is a local child

    • hasStepOfClass

      public static boolean hasStepOfClass(Class stepClass, Traversal.Admin<?,?> traversal)
      Determine if the traversal has a step of a particular class.
      Parameters:
      stepClass - the step class to look for
      traversal - the traversal to perform the action on
      Returns:
      true if the class is found and false otherwise

    • isMultilabelEnabled

      public static boolean isMultilabelEnabled(Traversal.Admin<?,?> traversal)
      Checks whether multi-label output is enabled for the given traversal via source-level g.with("multilabel") configuration.
      Parameters:
      traversal - the traversal to inspect
      Returns:
      true if multi-label output is enabled and false otherwise

    • hasStepOfAssignableClass

      public static boolean hasStepOfAssignableClass(Class superClass, Traversal.Admin<?,?> traversal)
      Determine if the traversal has a step of an assignable class.
      Parameters:
      superClass - the step super class to look for
      traversal - the traversal to perform the action on
      Returns:
      true if the class is found and false otherwise

    • hasStepOfAssignableClassRecursively

      public static boolean hasStepOfAssignableClassRecursively(Class stepClass, Traversal.Admin<?,?> traversal)
      Determine if the traversal has a step of an assignable class in the current Traversal and its local and global child traversals.
      Parameters:
      stepClass - the step class to look for
      traversal - the traversal in which to look for the given step class
      Returns:
      true if any step in the given traversal (and its child traversals) is an instance of the given stepClass, otherwise false.

    • hasStepOfAssignableClassRecursively

      public static boolean hasStepOfAssignableClassRecursively(Scope scope, Class stepClass, Traversal.Admin<?,?> traversal)
      Determine if the traversal has a step of an assignable class in the current Traversal and its Scope child traversals.
      Parameters:
      scope - the child traversal scope to check
      stepClass - the step class to look for
      traversal - the traversal in which to look for the given step class
      Returns:
      true if any step in the given traversal (and its child traversals) is an instance of the given stepClass, otherwise false.

    • hasStepOfAssignableClassRecursively

      public static boolean hasStepOfAssignableClassRecursively(Collection<Class> stepClasses, Traversal.Admin<?,?> traversal)
      Determine if the traversal has any of the supplied steps of an assignable class in the current Traversal and its global or local child traversals.
      Parameters:
      stepClasses - the step classes to look for
      traversal - the traversal in which to look for the given step classes
      Returns:
      true if any step in the given traversal (and its child traversals) is an instance of a class provided in stepClasses, otherwise false.

    • hasStepOfAssignableClassRecursively

      public static boolean hasStepOfAssignableClassRecursively(Scope scope, Collection<Class> stepClasses, Traversal.Admin<?,?> traversal)
      Determine if the traversal has any of the supplied steps of an assignable class in the current Traversal and its Scope child traversals.
      Parameters:
      scope - whether to check global or local children (null for both).
      stepClasses - the step classes to look for
      traversal - the traversal in which to look for the given step classes
      Returns:
      true if any step in the given traversal (and its child traversals) is an instance of a class provided in stepClasses, otherwise false.

    • hasOnlyStepsOfAssignableClassesRecursively

      public static boolean hasOnlyStepsOfAssignableClassesRecursively(Collection<Class> stepClasses, Traversal.Admin<?,?> traversal)
      Checks if the traversal only has steps that are equal to or assignable from the given step classes.
      Parameters:
      stepClasses - the collection of allowed step classes
      traversal - the traversal to check
      Returns:
      true if all steps in the traversal are equal to or assignable from the given classes

    • anyStepRecursively

      public static boolean anyStepRecursively(Predicate<Step> predicate, Traversal.Admin<?,?> traversal)
      Determine if any step in Traversal or its children match the step given the provided Predicate.
      Parameters:
      predicate - the match function
      traversal - the traversal to perform the action on
      Returns:
      true if there is a match and false otherwise

    • anyStepRecursively

      public static boolean anyStepRecursively(Predicate<Step> predicate, TraversalParent step)
      Determine if any child step of a TraversalParent match the step given the provided Predicate.
      Parameters:
      predicate - the match function
      step - the step to perform the action on
      Returns:
      true if there is a match and false otherwise

    • applyTraversalRecursively

      public static void applyTraversalRecursively(Consumer<Traversal.Admin<?,?>> consumer, Traversal.Admin<?,?> traversal)
      Apply the provider Consumer function to the provided Traversal and all of its children.
      Parameters:
      consumer - the function to apply to the each traversal in the tree
      traversal - the root traversal to start application

    • applyTraversalRecursively

      public static void applyTraversalRecursively(Consumer<Traversal.Admin<?,?>> consumer, Traversal.Admin<?,?> traversal, boolean applyToChildrenOnly)
      Apply the provider Consumer function to the provided Traversal and all of its children.
      Parameters:
      consumer - the function to apply
      traversal - the root traversal
      applyToChildrenOnly - if true, only child traversals receive the function (the root is skipped)

    • addToCollection

      public static <S> void addToCollection(Collection<S> collection, S s, long bulk)
      Adds the supplied element to the collection according to the provided bulk count. If the collection is a BulkSet, the element is added with the given bulk. If it is a Set, the element is added once. Otherwise the element is added repeatedly bulk times.
      Parameters:
      collection - the collection to mutate
      s - the element to add
      bulk - the bulk count

    • getShortName

      public static String getShortName(Step step, int maxLength)
      Returns the name of step truncated to maxLength. An ellipses is appended when the name exceeds maxLength.
      Parameters:
      step -
      maxLength - Includes the 3 "..." characters that will be appended when the length of the name exceeds maxLength.
      Returns:
      short step name.

    • reIdSteps

      public static void reIdSteps(StepPosition stepPosition, Traversal.Admin<?,?> traversal)
      Reassigns identifiers for every step in the supplied traversal using the provided StepPosition state object. The StepPosition is mutated to reflect the current parent context (x/y/z/parentId) and each step receives a new id via StepPosition#nextXId().
      Parameters:
      stepPosition - the position tracker to mutate and use to generate ids
      traversal - the traversal whose steps will be re-identified

    • getRootTraversal

      public static Traversal.Admin<?,?> getRootTraversal(Traversal.Admin<?,?> traversal)
      Returns the root traversal by walking up the parent chain until encountering an EmptyStep parent.
      Parameters:
      traversal - a traversal that may be nested
      Returns:
      the root (top-most) traversal

    • hasLabels

      public static boolean hasLabels(Traversal.Admin<?,?> traversal)
      Determines whether any non-hidden labels are present anywhere in the traversal or its children.
      Parameters:
      traversal - the traversal to inspect
      Returns:
      true if at least one non-hidden label exists; false otherwise

    • getLabels

      public static Set<String> getLabels(Traversal.Admin<?,?> traversal)
      Collects all labels (including hidden) present in the traversal and its child traversals.
      Parameters:
      traversal - the traversal to inspect
      Returns:
      a set of labels

    • getVariableLocations

      public static Set<Scoping.Variable> getVariableLocations(Traversal.Admin<?,?> traversal)
      Determines whether labels are referenced at the START and/or END of the traversal by inspecting the first and last steps (and appropriate children for certain step types). Returned variables include START and/or END.
      Parameters:
      traversal - the traversal to inspect
      Returns:
      a set containing zero, one, or both of Scoping.Variable.START and Scoping.Variable.END

    • onGraphComputer

      public static boolean onGraphComputer(Traversal.Admin<?,?> traversal)
      Determines if the traversal is executing on a GraphComputer by walking up the parent chain and checking for a TraversalVertexProgramStep.
      Parameters:
      traversal - the traversal to inspect
      Returns:
      true if the traversal is under a TraversalVertexProgramStep; false otherwise

    • removeStep

      public static Traversal.Admin<?,?> removeStep(Step<?,?> stepToRemove, Traversal.Admin<?,?> traversal)
      Removes the specified step from the traversal and returns the traversal for chaining.
      Parameters:
      stepToRemove - the step to remove
      traversal - the traversal to mutate
      Returns:
      the traversal argument for chaining

    • removeAllSteps

      public static void removeAllSteps(Traversal.Admin<?,?> traversal)
      Removes all steps from the traversal.
      Parameters:
      traversal - the traversal to clear

    • copyLabels

      public static void copyLabels(Step<?,?> fromStep, Step<?,?> toStep, boolean moveLabels)
      Copies labels from one step to another. If moveLabels is true, labels are removed from the source after copying; otherwise labels are left in place and only added to the target.
      Parameters:
      fromStep - the step to copy labels from
      toStep - the step to add labels to
      moveLabels - whether to remove labels from the source after copying

    • hasAllStepsOfClass

      public static boolean hasAllStepsOfClass(Traversal.Admin<?,?> traversal, Class<?>... classesToCheck)
      Tests whether every step in the traversal is an instance of at least one of the supplied classes.
      Parameters:
      traversal - the traversal to test
      classesToCheck - the classes to check with Class.isInstance(Object)
      Returns:
      true if all steps match at least one class; false otherwise

    • hasStepOfClass

      public static boolean hasStepOfClass(Traversal.Admin<?,?> traversal, Class<?>... classesToCheck)
      Tests whether any step in the traversal is an instance of any of the supplied classes.
      Parameters:
      traversal - the traversal to test
      classesToCheck - the classes to check with Class.isInstance(Object)
      Returns:
      true if any step matches at least one class; false otherwise

    • addHasContainer

      public static <T extends Traversal.Admin<?, ?>> T addHasContainer(T traversal, HasContainer hasContainer)
      Used to left-fold a HasContainer to a HasContainerHolder if it exists. Else, append a HasStep.
      Parameters:
      traversal - the traversal to fold or append.
      hasContainer - the container to add left or append.
      Returns:
      the has container folded or appended traversal

    • gatherStepGValues

      public static Map<Step,Collection<GValue<?>>> gatherStepGValues(Traversal.Admin<?,?> traversal)
      Gathers all steps that implement GValueHolder and returns a map from step to the collection of GValue instances they hold.
      Parameters:
      traversal - the traversal to scan recursively
      Returns:
      a map of steps to their GValue collections

    • gatherGValuePlaceholders

      public static Set<Step<?,?>> gatherGValuePlaceholders(Traversal.Admin<?,?> traversal)
      Gathers all steps that implement GValueHolder and returns them as a set. This is useful when only the presence of placeholders is needed and not the values themselves.
      Parameters:
      traversal - the traversal to scan recursively
      Returns:
      the set of steps that are GValueHolders

    • getPopInstructions

      public static <T extends Traversal.Admin<?, ?>> Set<PopContaining.PopInstruction> getPopInstructions(T traversal)
      Used to get PopInstruction of a traversal. Pop Instruction includes the labels it needs, and the pop type for each label.
      Type Parameters:
      T - the traversal type
      Parameters:
      traversal - the traversal to get Scope Context for
      Returns:
      A Set of PopContaining.PopInstruction values which contain the label and Pop value

    • hasRepeatStepParent

      public static boolean hasRepeatStepParent(Traversal.Admin<?,?> traversal)
      Parameters:
      traversal - the Traversal.Admin to check for a RepeatStep parent
      Returns:
      true if a RepeatStep is a direct or indirect parent of the given Traversal.Admin, false otherwise

    • asVarargsList

      public static <T> List<T> asVarargsList(T first, T[] more, String argumentName)
      Combines a required first argument with zero or more additional varargs arguments into a single ordered List, validating that neither the first argument nor any of the additional arguments are null. This is useful for GraphTraversal/GraphTraversalSource spawn methods of the common method(first, more...) shape (e.g. addV(label, additionalLabels), addLabel(labelTraversal, moreLabelTraversals)) that need to treat the arguments as a single ordered collection while still requiring at least one argument to be supplied.
      Type Parameters:
      T - the argument type
      Parameters:
      first - the required first argument
      more - the additional, possibly empty, varargs arguments
      argumentName - the name to use for the argument in the exception message when a null is found
      Returns:
      an unmodifiable list containing first followed by the elements of more, in order
      Throws:
      IllegalArgumentException - if first or any element of more is null