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

Interface Traverser<T>

  • All Superinterfaces:
    Cloneable, Comparable<Traverser<T>>, Serializable
    All Known Subinterfaces:
    Traverser.Admin<T>
    public interface Traverser<T>
extends Serializable, Comparable<Traverser<T>>, Cloneable
    A Traverser represents the current state of an object flowing through a Traversal. A traverser maintains a reference to the current object, a traverser-local "sack", a traversal-global sideEffect, a bulk count, and a path history.

    Different types of traversers can exist depending on the semantics of the traversal and the desire for space/time optimizations of the developer.

    Author:
    Marko A. Rodriguez (http://markorodriguez.com)

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static interface  Traverser.Admin<T>
      The methods in System.Traverser are useful to underlying Step and Traversal implementations.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default Traverser.Admin<T> asAdmin()
      Typecast the traverser to a "system traverser" so Traverser.Admin methods can be accessed.
      long bulk()
      A traverser may represent a grouping of traversers to allow for more efficient data propagation.
      Traverser<T> clone()
      Traverser cloning is important when splitting a traverser at a bifurcation point in a traversal.
      default int compareTo​(Traverser<T> other)
      If the underlying object of the traverser is comparable, compare it with the other traverser.
      T get()
      Get the object that the traverser is current at.
      int loops()
      Return the number of times the traverser has gone through a looping section of a traversal.
      int loops​(String loopName)
      Return the number of times the traverser has gone through the named looping section of a traversal.
      Path path()
      Get the current path of the traverser.
      default <A> A path​(String stepLabel)
      Get the object associated with the specified step-label in the traverser's path history.
      default <A> A path​(Pop pop, String stepLabel)  
      <S> S sack()
      Get the sack local sack object of this traverser.
      <S> void sack​(S object)
      Set the traversers sack object to the provided value ("sack the value").
      default <A> A sideEffects​(String sideEffectKey)
      Get a particular value from the side-effects of the traverser (thus, traversal).
      default void sideEffects​(String sideEffectKey, Object sideEffectValue)
      Add a particular value to the respective side-effect of the traverser (thus, traversal).

    • Method Detail

      • get

        T get()
        Get the object that the traverser is current at.
        Returns:
        The current object of the traverser

      • sack

        <S> S sack()
        Get the sack local sack object of this traverser.
        Type Parameters:
        S - the type of the sack object
        Returns:
        the sack object

      • sack

        <S> void sack​(S object)
        Set the traversers sack object to the provided value ("sack the value").
        Type Parameters:
        S - the type of the object
        Parameters:
        object - the new value of the traverser's sack

      • path

        Path path()
        Get the current path of the traverser.
        Returns:
        The path of the traverser

      • path

        default <A> A path​(String stepLabel)
        Get the object associated with the specified step-label in the traverser's path history.
        Type Parameters:
        A - the type of the object
        Parameters:
        stepLabel - the step-label in the path to access
        Returns:
        the object associated with that path label (if more than one object occurs at that step, a list is returned)

      • path

        default <A> A path​(Pop pop,
                   String stepLabel)

      • loops

        int loops()
        Return the number of times the traverser has gone through a looping section of a traversal.
        Returns:
        The number of times the traverser has gone through a loop

      • loops

        int loops​(String loopName)
        Return the number of times the traverser has gone through the named looping section of a traversal.
        Parameters:
        loopName - the name applied to the loop or null for the containing loop
        Returns:
        The number of times the traverser has gone through a loop
        Throws:
        IllegalArgumentException - if the loopName is not defined

      • bulk

        long bulk()
        A traverser may represent a grouping of traversers to allow for more efficient data propagation.
        Returns:
        the number of traversers represented in this traverser.

      • sideEffects

        default <A> A sideEffects​(String sideEffectKey)
                   throws IllegalArgumentException
        Get a particular value from the side-effects of the traverser (thus, traversal).
        Type Parameters:
        A - the type of the returned object
        Parameters:
        sideEffectKey - the key of the value to get from the sideEffects
        Returns:
        the object in the sideEffects of the respective key
        Throws:
        IllegalArgumentException

      • sideEffects

        default void sideEffects​(String sideEffectKey,
                         Object sideEffectValue)
                  throws IllegalArgumentException
        Add a particular value to the respective side-effect of the traverser (thus, traversal).
        Parameters:
        sideEffectKey - the key of the value to set int the sideEffects
        sideEffectValue - the value to set for the sideEffect key
        Throws:
        IllegalArgumentException

      • compareTo

        default int compareTo​(Traverser<T> other)
               throws ClassCastException
        If the underlying object of the traverser is comparable, compare it with the other traverser.
        Specified by:
        compareTo in interface Comparable<T>
        Parameters:
        other - the other traverser that presumably has a comparable internal object
        Returns:
        the comparison of the two objects of the traversers
        Throws:
        ClassCastException - if the object of the traverser is not comparable

      • asAdmin

        default Traverser.Admin<T> asAdmin()
        Typecast the traverser to a "system traverser" so Traverser.Admin methods can be accessed. This is used as a helper method to avoid the awkwardness of ((Traverser.Administrative)traverser). The default implementation simply returns "this" type casted to Traverser.Admin.
        Returns:
        The type-casted traverser

      • clone

        Traverser<T> clone()
        Traverser cloning is important when splitting a traverser at a bifurcation point in a traversal.