org.apache.tinkerpop.gremlin.process.traversal

## Interface Traversal<S,E>

- All Superinterfaces:
    AutoCloseable, Cloneable, Iterator<E>, Serializable
  All Known Subinterfaces:
    CredentialTraversal<S,E>, CredentialTraversalDsl<S,E>, GraphTraversal<S,E>, GraphTraversal.Admin<S,E>, RemoteTraversal<S,E>, Traversal.Admin<S,E>
  All Known Implementing Classes:
    AbstractLambdaTraversal, AbstractRemoteTraversal, ColumnTraversal, ConstantTraversal, DefaultCredentialTraversal, DefaultGraphTraversal, DefaultTraversal, DriverRemoteTraversal, EmbeddedRemoteTraversal, EmptyTraversal, HaltedTraversersCountTraversal, IdentityTraversal, LoopTraversal, PredicateTraversal, ScriptTraversal, TokenTraversal, TrueTraversal, ValueTraversal

      public interface Traversal<S,E>
      extends Iterator<E>, Serializable, Cloneable, AutoCloseable

  A `Traversal` represents a directed walk over a `Graph`. This is the base interface for all traversal's, where each extending interface is seen as a domain specific language. For example, `GraphTraversal` is a domain specific language for traversing a graph using "graph concepts" (e.g. vertices, edges). Another example may represent the graph using "social concepts" (e.g. people, cities, artifacts). A `Traversal` is evaluated in one of two ways: iterator-based OLTP or `GraphComputer`-based OLAP. OLTP traversals leverage an iterator and are executed within a single JVM (with data access allowed to be remote). OLAP traversals leverage `GraphComputer` and are executed between multiple JVMs (and/or cores).
  Author:
    Marko A. Rodriguez (http://markorodriguez.com)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Traversal.Admin<S,E>`
    `static class` | `Traversal.Exceptions` A collection of `Exception` types associated with Traversal execution.
    `static class` | `Traversal.Symbols`

  - ### Method Summary

    All Methods Instance Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default Traversal.Admin<S,E>` | `asAdmin()` Get access to administrative methods of the traversal via its accompanying `Traversal.Admin`.
    `default void` | `close()` Releases resources opened in any steps that implement `AutoCloseable`.
    `default TraversalExplanation` | `explain()` Return a `TraversalExplanation` that shows how this traversal will mutate with each applied `TraversalStrategy`.
    `default <C extends Collection<E>> C` | `fill(C collection)` Add all the results of the traversal to the provided collection.
    `default <E2> void` | `forEachRemaining(Class<E2> endType, Consumer<E2> consumer)` A traversal can be rewritten such that its defined end type E may yield objects of a different type.
    `default void` | `forEachRemaining(Consumer<? super E> action)`
    `default <A,B> Traversal<A,B>` | `iterate()` Iterate all the `Traverser` instances in the traversal.
    `default List<E>` | `next(int amount)` Get the next n-number of results from the traversal.
    `default Traversal<S,E>` | `none()` Filter all traversers in the traversal.
    `default void` | `notifyClose()` Gets a callback from `close()` for additional operations specific to the `Traversal` implementation.
    `default Traversal<S,TraversalMetrics>` | `profile()` Profile the traversal.
    `default <T> CompletableFuture<T>` | `promise(Function<Traversal<S,E>,T> traversalFunction)` Starts a promise to execute a function on the current `Traversal` that will be completed in the future.
    `default BulkSet<E>` | `toBulkSet()` Put all the results into a `BulkSet`.
    `default List<E>` | `toList()` Put all the results into an `ArrayList`.
    `default Set<E>` | `toSet()` Put all the results into a `HashSet`.
    `default Stream<E>` | `toStream()` Return the traversal as a `Stream`.
    `default Optional<E>` | `tryNext()` Return an `Optional` of the next E object in the traversal.

    - ### Methods inherited from interface java.util.Iterator

      `hasNext, next, remove`

- - ### Method Detail

    - #### asAdmin

          default Traversal.Admin<S,E> asAdmin()

      Get access to administrative methods of the traversal via its accompanying `Traversal.Admin`.
      Returns:
        the admin of this traversal

    - #### tryNext

          default Optional<E> tryNext()

      Return an `Optional` of the next E object in the traversal. If the traversal is empty, then an `Optional.empty()` is returned.
      Returns:
        an optional of the next object in the traversal

    - #### next

          default List<E> next(int amount)

      Get the next n-number of results from the traversal. If the traversal has less than n-results, then only that number of results are returned.
      Parameters:
        `amount` - the number of results to get
      Returns:
        the n-results in a `List`

    - #### toList

          default List<E> toList()

      Put all the results into an `ArrayList`.
      Returns:
        the results in a list

    - #### toSet

          default Set<E> toSet()

      Put all the results into a `HashSet`.
      Returns:
        the results in a set

    - #### toBulkSet

          default BulkSet<E> toBulkSet()

      Put all the results into a `BulkSet`. This can reduce both time and space when aggregating results by ensuring a weighted set.
      Returns:
        the results in a bulk set

    - #### toStream

          default Stream<E> toStream()

      Return the traversal as a `Stream`.
      Returns:
        the traversal as a stream.

    - #### promise

          default <T> CompletableFuture<T> promise(Function<Traversal<S,E>,T> traversalFunction)

      Starts a promise to execute a function on the current `Traversal` that will be completed in the future. Note that this method can only be used if the `Traversal` is constructed using `AnonymousTraversalSource.withRemote(Configuration)`. Calling this method otherwise will yield an `IllegalStateException`.

    - #### fill

          default <C extends Collection<E>> C fill(C collection)

      Add all the results of the traversal to the provided collection.
      Parameters:
        `collection` - the collection to fill
      Returns:
        the collection now filled

    - #### iterate

          default <A,B> Traversal<A,B> iterate()

      Iterate all the `Traverser` instances in the traversal. What is returned is the empty traversal. It is assumed that what is desired from the computation is are the sideEffects yielded by the traversal.
      Returns:
        the fully drained traversal

    - #### none

          default Traversal<S,E> none()

      Filter all traversers in the traversal. This step has narrow use cases and is primarily intended for use as a signal to remote servers that `iterate()` was called. While it may be directly used, it is often a sign that a traversal should be re-written in another form.
      Returns:
        the updated traversal with respective `NoneStep`.

    - #### profile

          default Traversal<S,TraversalMetrics> profile()

      Profile the traversal.
      Returns:
        the updated traversal with respective `ProfileSideEffectStep`.

    - #### explain

          default TraversalExplanation explain()

      Return a `TraversalExplanation` that shows how this traversal will mutate with each applied `TraversalStrategy`.
      Returns:
        a traversal explanation

    - #### forEachRemaining

          default <E2> void forEachRemaining(Class<E2> endType,
                                             Consumer<E2> consumer)

      A traversal can be rewritten such that its defined end type E may yield objects of a different type. This helper method allows for the casting of the output to the known the type.
      Type Parameters:
        `E2` - the known output type of the traversal
      Parameters:
        `endType` - the true output type of the traversal
        `consumer` - a `Consumer` to process each output

    - #### forEachRemaining

          default void forEachRemaining(Consumer<? super E> action)

      Specified by:
        `forEachRemaining` in interface `Iterator<E>`

    - #### close

          default void close()
                      throws Exception

      Releases resources opened in any steps that implement `AutoCloseable`. If this method is overridden,the implementer should invoke `notifyClose()`.
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `Exception`

    - #### notifyClose

          default void notifyClose()

      Gets a callback from `close()` for additional operations specific to the `Traversal` implementation. A good implementation will use `close()` to release resources in steps and this method to release resources specific to the `Traversal` implementations.

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