org.apache.tinkerpop.gremlin.process.traversal

Interface Traversal<S,E>

All Superinterfaces:

AutoCloseable, Cloneable, Iterator<E>, Serializable

All Known Subinterfaces:

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, DefaultGraphTraversal, DefaultTraversal, DriverRemoteTraversal, ElementValueTraversal, EmbeddedRemoteTraversal, EmptyTraversal, HaltedTraversersCountTraversal, IdentityTraversal, LoopTraversal, PredicateTraversal, ScriptTraversal, TokenTraversal, TrueTraversal

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

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 TraversalSource.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.