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 and 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 and 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(Pop pop, String stepLabel)`
    `default <A> A` | `path(String stepLabel)` Get the object associated with the specified step-label in the traverser's path history.
    `<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<Traverser<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.

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