org.apache.tinkerpop.gremlin.process.traversal

Interface TraversalSource

All Superinterfaces:

AutoCloseable, Cloneable

All Known Implementing Classes:

GraphTraversalSource

public interface TraversalSource
extends Cloneable, AutoCloseable

A TraversalSource is used to create Traversal instances. A traversal source can generate any number of Traversal instances. A traversal source is primarily composed of a Graph and a TraversalStrategies. Various withXXX-based methods are used to configure the traversal strategies (called "configurations"). Various other methods (dependent on the traversal source type) will then generate a traversal given the graph and configured strategies (called "spawns"). A traversal source is immutable in that fluent chaining of configurations create new traversal sources. This is unlike Traversal and GraphComputer, where chained methods configure the same instance. Every traversal source implementation must maintain two constructors to enable proper reflection-based construction.

TraversalSource(Graph) and TraversalSource(Graph,TraversalStrategies)

Author:

Marko A. Rodriguez (http://markorodriguez.com), Stephen Mallette (http://stephen.genoprime.com)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	TraversalSource.Symbols

Method Summary

Modifier and Type	Method and Description
TraversalSource	clone() The clone-method should be used to create immutable traversal sources with each call to a configuration "withXXX"-method.
default void	close()
default Optional<Class>	getAnonymousTraversalClass()
Bytecode	getBytecode() Get the Bytecode associated with the current state of this traversal source.
Graph	getGraph() Get the Graph associated with this traversal source.
TraversalStrategies	getStrategies() Get the TraversalStrategies associated with this traversal source.
default TraversalSource	with(String key) Provides a configuration to a traversal in the form of a key which is the same as with(key, true).
default TraversalSource	with(String key, Object value) Provides a configuration to a traversal in the form of a key value pair.
default TraversalSource	withComputer() Add the standard GraphComputer of the graph that will be used to execute the traversal.
default TraversalSource	withComputer(Class<? extends GraphComputer> graphComputerClass) Add a GraphComputer class used to execute the traversal.
default TraversalSource	withComputer(Computer computer) Add a Computer that will generate a GraphComputer from the Graph that will be used to execute the traversal.
default TraversalSource	withoutStrategies(Class<? extends TraversalStrategy>... traversalStrategyClasses) Remove an arbitrary collection of TraversalStrategy classes from the traversal source.
default TraversalSource	withRemote(org.apache.commons.configuration.Configuration conf) Deprecated. As of release 3.3.5, replaced by AnonymousTraversalSource.withRemote(Configuration).
TraversalSource	withRemote(org.apache.tinkerpop.gremlin.process.remote.RemoteConnection connection) Deprecated. As of release 3.3.5, replaced by AnonymousTraversalSource.withRemote(RemoteConnection).
default TraversalSource	withRemote(String configFile) Deprecated. As of release 3.3.5, replaced by AnonymousTraversalSource.withRemote(String).
default <A> TraversalSource	withSack(A initialValue) Add a sack to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSack(A initialValue, BinaryOperator<A> mergeOperator) Add a sack to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSack(A initialValue, UnaryOperator<A> splitOperator) Add a sack to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSack(A initialValue, UnaryOperator<A> splitOperator, BinaryOperator<A> mergeOperator) Add a sack to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSack(Supplier<A> initialValue) Add a sack to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSack(Supplier<A> initialValue, BinaryOperator<A> mergeOperator) Add a sack to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSack(Supplier<A> initialValue, UnaryOperator<A> splitOperator) Add a sack to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSack(Supplier<A> initialValue, UnaryOperator<A> splitOperator, BinaryOperator<A> mergeOperator) Add a sack to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSideEffect(String key, A initialValue) Add a sideEffect to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSideEffect(String key, A initialValue, BinaryOperator<A> reducer) Add a sideEffect to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSideEffect(String key, Supplier<A> initialValue) Add a sideEffect to be used throughout the life of a spawned Traversal.
default <A> TraversalSource	withSideEffect(String key, Supplier<A> initialValue, BinaryOperator<A> reducer) Add a sideEffect to be used throughout the life of a spawned Traversal.
default TraversalSource	withStrategies(TraversalStrategy... traversalStrategies) Add an arbitrary collection of TraversalStrategy instances to the traversal source.

Method Detail

getStrategies

TraversalStrategies getStrategies()

Get the TraversalStrategies associated with this traversal source.

Returns:

the traversal strategies of the traversal source

getGraph

Graph getGraph()

Get the Graph associated with this traversal source.

Returns:

the graph of the traversal source

getBytecode

Bytecode getBytecode()

Get the Bytecode associated with the current state of this traversal source.

Returns:

the traversal source byte code

with

default TraversalSource with(String key)

Provides a configuration to a traversal in the form of a key which is the same as with(key, true). The key of the configuration must be graph provider specific and therefore a configuration could be supplied that is not known to be valid until execution.

Parameters:

key - the key of the configuration to apply to a traversal

Returns:

a new traversal source with the included configuration

Since:

3.4.0

with

default TraversalSource with(String key,
                             Object value)

Provides a configuration to a traversal in the form of a key value pair. The key of the configuration must be graph provider specific and therefore a configuration could be supplied that is not known to be valid until execution. This is a handy shortcut for building an OptionsStrategy manually and then add with withStrategies(TraversalStrategy[]).

Parameters:

key - the key of the configuration to apply to a traversal

value - the value of the configuration to apply to a traversal

Returns:

a new traversal source with the included configuration

Since:

3.4.0

withStrategies

default TraversalSource withStrategies(TraversalStrategy... traversalStrategies)

Add an arbitrary collection of TraversalStrategy instances to the traversal source.

Parameters:

traversalStrategies - a collection of traversal strategies to add

Returns:

a new traversal source with updated strategies

withoutStrategies

default TraversalSource withoutStrategies(Class<? extends TraversalStrategy>... traversalStrategyClasses)

Remove an arbitrary collection of TraversalStrategy classes from the traversal source.

Parameters:

traversalStrategyClasses - a collection of traversal strategy classes to remove

Returns:

a new traversal source with updated strategies

withComputer

default TraversalSource withComputer(Computer computer)

Add a Computer that will generate a GraphComputer from the Graph that will be used to execute the traversal. This adds a VertexProgramStrategy to the strategies.

Parameters:

computer - a builder to generate a graph computer from the graph

Returns:

a new traversal source with updated strategies

withComputer

default TraversalSource withComputer(Class<? extends GraphComputer> graphComputerClass)

Add a GraphComputer class used to execute the traversal. This adds a VertexProgramStrategy to the strategies.

Parameters:

graphComputerClass - the graph computer class

Returns:

a new traversal source with updated strategies

withComputer

default TraversalSource withComputer()

Add the standard GraphComputer of the graph that will be used to execute the traversal. This adds a VertexProgramStrategy to the strategies.

Returns:

a new traversal source with updated strategies

withSideEffect

default <A> TraversalSource withSideEffect(String key,
                                           Supplier<A> initialValue,
                                           BinaryOperator<A> reducer)

Add a sideEffect to be used throughout the life of a spawned Traversal. This adds a SideEffectStrategy to the strategies.

Parameters:

key - the key of the sideEffect

initialValue - a supplier that produces the initial value of the sideEffect

reducer - a reducer to merge sideEffect mutations into a single result

Returns:

a new traversal source with updated strategies

withSideEffect

default <A> TraversalSource withSideEffect(String key,
                                           A initialValue,
                                           BinaryOperator<A> reducer)

Add a sideEffect to be used throughout the life of a spawned Traversal. This adds a SideEffectStrategy to the strategies.

Parameters:

key - the key of the sideEffect

initialValue - the initial value of the sideEffect

reducer - a reducer to merge sideEffect mutations into a single result

Returns:

a new traversal source with updated strategies

withSideEffect

default <A> TraversalSource withSideEffect(String key,
                                           Supplier<A> initialValue)

Add a sideEffect to be used throughout the life of a spawned Traversal. This adds a SideEffectStrategy to the strategies.

Parameters:

key - the key of the sideEffect

initialValue - a supplier that produces the initial value of the sideEffect

Returns:

a new traversal source with updated strategies

withSideEffect

default <A> TraversalSource withSideEffect(String key,
                                           A initialValue)

Add a sideEffect to be used throughout the life of a spawned Traversal. This adds a SideEffectStrategy to the strategies.

Parameters:

key - the key of the sideEffect

initialValue - the initial value of the sideEffect

Returns:

a new traversal source with updated strategies

withSack

default <A> TraversalSource withSack(Supplier<A> initialValue,
                                     UnaryOperator<A> splitOperator,
                                     BinaryOperator<A> mergeOperator)

Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.

Parameters:

initialValue - a supplier that produces the initial value of the sideEffect

splitOperator - the sack split operator

mergeOperator - the sack merge operator

Returns:

a new traversal source with updated strategies

withSack

default <A> TraversalSource withSack(A initialValue,
                                     UnaryOperator<A> splitOperator,
                                     BinaryOperator<A> mergeOperator)

Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.

Parameters:

initialValue - the initial value of the sideEffect

splitOperator - the sack split operator

mergeOperator - the sack merge operator

Returns:

a new traversal source with updated strategies

withSack

default <A> TraversalSource withSack(A initialValue)

Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.

Parameters:

initialValue - the initial value of the sideEffect

Returns:

a new traversal source with updated strategies

withSack

default <A> TraversalSource withSack(Supplier<A> initialValue)

Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.

Parameters:

initialValue - a supplier that produces the initial value of the sideEffect

Returns:

a new traversal source with updated strategies

withSack

default <A> TraversalSource withSack(Supplier<A> initialValue,
                                     UnaryOperator<A> splitOperator)

Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.

Parameters:

initialValue - a supplier that produces the initial value of the sideEffect

splitOperator - the sack split operator

Returns:

a new traversal source with updated strategies

withSack

default <A> TraversalSource withSack(A initialValue,
                                     UnaryOperator<A> splitOperator)

Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.

Parameters:

initialValue - the initial value of the sideEffect

splitOperator - the sack split operator

Returns:

a new traversal source with updated strategies

withSack

default <A> TraversalSource withSack(Supplier<A> initialValue,
                                     BinaryOperator<A> mergeOperator)

Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.

Parameters:

initialValue - a supplier that produces the initial value of the sideEffect

mergeOperator - the sack merge operator

Returns:

a new traversal source with updated strategies

withSack

default <A> TraversalSource withSack(A initialValue,
                                     BinaryOperator<A> mergeOperator)

Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.

Parameters:

initialValue - the initial value of the sideEffect

mergeOperator - the sack merge operator

Returns:

a new traversal source with updated strategies

withRemote

@Deprecated
default TraversalSource withRemote(org.apache.commons.configuration.Configuration conf)

Deprecated. As of release 3.3.5, replaced by AnonymousTraversalSource.withRemote(Configuration).

Configures the TraversalSource as a "remote" to issue the Traversal for execution elsewhere. Expects key for RemoteConnection.GREMLIN_REMOTE_CONNECTION_CLASS as well as any configuration required by the underlying RemoteConnection which will be instantiated. Note that the Configuration object is passed down without change to the creation of the RemoteConnection instance.

See Also:

TINKERPOP-2078

withRemote

@Deprecated
default TraversalSource withRemote(String configFile)
                                        throws Exception

Deprecated. As of release 3.3.5, replaced by AnonymousTraversalSource.withRemote(String).

Configures the TraversalSource as a "remote" to issue the Traversal for execution elsewhere. Calls withRemote(Configuration) after reading the properties file specified.

Throws:

Exception

See Also:

TINKERPOP-2078

withRemote

@Deprecated
TraversalSource withRemote(org.apache.tinkerpop.gremlin.process.remote.RemoteConnection connection)

Deprecated. As of release 3.3.5, replaced by AnonymousTraversalSource.withRemote(RemoteConnection).

Configures the TraversalSource as a "remote" to issue the Traversal for execution elsewhere. Implementations should track RemoteConnection instances that are created and call AutoCloseable.close() on them when the TraversalSource itself is closed.

Parameters:

connection - the RemoteConnection instance to use to submit the Traversal.

See Also:

TINKERPOP-2078

getAnonymousTraversalClass

default Optional<Class> getAnonymousTraversalClass()

clone

TraversalSource clone()

The clone-method should be used to create immutable traversal sources with each call to a configuration "withXXX"-method. The clone-method should clone the Bytecode, TraversalStrategies, mutate the cloned strategies accordingly, and then return the cloned traversal source leaving the original unaltered.

Returns:

the cloned traversal source

close

default void close()
            throws Exception

Specified by:

close in interface AutoCloseable

Throws:

Exception