org.apache.tinkerpop.gremlin.process.traversal.util

Class DefaultTraversalSideEffects

java.lang.Object

org.apache.tinkerpop.gremlin.process.traversal.util.DefaultTraversalSideEffects

All Implemented Interfaces:

Serializable, AutoCloseable, Cloneable, TraversalSideEffects

public class DefaultTraversalSideEffects
extends Object
implements TraversalSideEffects

Author:

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

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.tinkerpop.gremlin.process.traversal.TraversalSideEffects

TraversalSideEffects.Exceptions

Field Summary

Fields

Modifier and Type	Field and Description
protected Set<String>	keys
protected Map<String,Object>	objectMap
protected Map<String,BinaryOperator>	reducerMap
protected Supplier	sackInitialValue
protected BinaryOperator	sackMergeOperator
protected UnaryOperator	sackSplitOperator
protected Map<String,Supplier>	supplierMap

Constructor Summary

Constructors

Constructor and Description
DefaultTraversalSideEffects()

Method Summary

Modifier and Type	Method and Description
void	add(String key, Object value) Add a value to the global side-effect value.
DefaultTraversalSideEffects	clone() Cloning is used to duplicate the sideEffects typically in distributed execution environments.
boolean	exists(String key) Return true if the key is a registered side-effect.
<V> V	get(String key) Get the sideEffect associated with the provided key.
<V> V	getOrCreate(String key, Supplier<V> orCreate) Deprecated.
<V> BinaryOperator<V>	getReducer(String key) Get the reducer associated with the side-effect key.
<V> Optional<Supplier<V>>	getRegisteredSupplier(String key) Deprecated.
<S> Supplier<S>	getSackInitialValue() If sacks are enabled, get the initial value of the Traverser sack.
<S> BinaryOperator<S>	getSackMerger() If sacks are enabled and a merge function has been specified, then get it (else get null).
<S> UnaryOperator<S>	getSackSplitter() If sacks are enabled and a split operator has been specified, then get it (else get null).
<V> Supplier<V>	getSupplier(String key) Get the supplier associated with the side-effect key.
Set<String>	keys() The keys of the sideEffect which includes registered Supplier keys.
void	mergeInto(TraversalSideEffects sideEffects) Add the current TraversalSideEffects values, suppliers, and reducers to the provided TraversalSideEffects.
<V> void	register(String key, Supplier<V> initialValue, BinaryOperator<V> reducer) Register a side-effect with the TraversalSideEffects providing a Supplier and a BinaryOperator.
<V> void	registerIfAbsent(String key, Supplier<V> initialValue, BinaryOperator<V> reducer) Register a side-effect with the TraversalSideEffects providing a Supplier and a BinaryOperator.
void	registerSupplier(String key, Supplier supplier) Deprecated.
void	registerSupplierIfAbsent(String key, Supplier supplier) Deprecated.
void	remove(String key) Remove both the value and registered Supplier associated with provided key.
void	set(String key, Object value) Set the specified key to the specified value.
<S> void	setSack(Supplier<S> initialValue, UnaryOperator<S> splitOperator, BinaryOperator<S> mergeOperator) Set the initial value of each Traverser "sack" along with the operators for splitting and merging sacks.
String	toString()

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.tinkerpop.gremlin.process.traversal.TraversalSideEffects

close, forEach, isEmpty

Field Detail

keys

protected Set<String> keys

objectMap

protected Map<String,Object> objectMap

supplierMap

protected Map<String,Supplier> supplierMap

reducerMap

protected Map<String,BinaryOperator> reducerMap

sackSplitOperator

protected UnaryOperator sackSplitOperator

sackMergeOperator

protected BinaryOperator sackMergeOperator

sackInitialValue

protected Supplier sackInitialValue

Constructor Detail

DefaultTraversalSideEffects

public DefaultTraversalSideEffects()

Method Detail

exists

public boolean exists(String key)

Return true if the key is a registered side-effect.

Specified by:

exists in interface TraversalSideEffects

Parameters:

key - the key to check for existence

Returns:

whether the key exists or not

get

public <V> V get(String key)
          throws IllegalArgumentException

Get the sideEffect associated with the provided key. If the sideEffect contains an object for the key, return it. Else if the sideEffect has a registered Supplier for that key, generate the object, store the object in the sideEffects, and return it.

Specified by:

get in interface TraversalSideEffects

Type Parameters:

V - the type of the value to retrieve

Parameters:

key - the key to get the value for

Returns:

the value associated with key

Throws:

IllegalArgumentException - if the key does not reference an object or a registered supplier.

set

public void set(String key,
                Object value)
         throws IllegalArgumentException

Set the specified key to the specified value. This method should not be used in a distributed environment. Instead, use TraversalSideEffects.add(String, Object). This method is only safe when there is only one representation of the side-effect and thus, not distributed across threads or machines.

Specified by:

set in interface TraversalSideEffects

Parameters:

key - the key they key of the side-effect

value - the value the new value for the side-effect

Throws:

IllegalArgumentException - if the key does not reference a registered side-effect.

add

public void add(String key,
                Object value)
         throws IllegalArgumentException

Add a value to the global side-effect value. This should be used by steps to ensure that side-effects are merged properly in a distributed environment. TraversalSideEffects.set(String, Object) should only be used in single-threaded systems or by a master traversal in a distributed environment.

Specified by:

add in interface TraversalSideEffects

Parameters:

key - the key of the side-effect.

value - the partital value (to be merged) of the side-effect.

Throws:

IllegalArgumentException - if no side-effect exists for the provided key

register

public <V> void register(String key,
                         Supplier<V> initialValue,
                         BinaryOperator<V> reducer)

Register a side-effect with the TraversalSideEffects providing a Supplier and a BinaryOperator. If a null value is provided for the supplier or reducer, then it no supplier or reducer is registered.

Specified by:

register in interface TraversalSideEffects

Type Parameters:

V - the type of the side-effect value

Parameters:

key - the key of the side-effect value

initialValue - the initial value supplier

reducer - the reducer to use for merging a distributed side-effect value into a single value

registerIfAbsent

public <V> void registerIfAbsent(String key,
                                 Supplier<V> initialValue,
                                 BinaryOperator<V> reducer)

Register a side-effect with the TraversalSideEffects providing a Supplier and a BinaryOperator. The registration will only overwrite a supplier or reducer if no supplier or reducer existed prior. If a null value is provided for the supplier or reducer, then it no supplier or reducer is registered.

Specified by:

registerIfAbsent in interface TraversalSideEffects

Type Parameters:

V - the type of the side-effect value

Parameters:

key - the key of the side-effect value

initialValue - the initial value supplier

reducer - the reducer to use for merging a distributed side-effect value into a single value

getReducer

public <V> BinaryOperator<V> getReducer(String key)
                                 throws IllegalArgumentException

Get the reducer associated with the side-effect key. If no reducer was registered, then Operator.assign is provided.

Specified by:

getReducer in interface TraversalSideEffects

Type Parameters:

V - the type of the side-effect value

Parameters:

key - the key of the side-effect

Returns:

the registered reducer

Throws:

IllegalArgumentException - if no side-effect exists for the provided key

getSupplier

public <V> Supplier<V> getSupplier(String key)
                            throws IllegalArgumentException

Get the supplier associated with the side-effect key. If no supplier was registered, then ConstantSupplier is provided.

Specified by:

getSupplier in interface TraversalSideEffects

Type Parameters:

V - the type of the side-effect value

Parameters:

key - the key of the side-effect

Returns:

the registered supplier

Throws:

IllegalArgumentException - if no side-effect exists for the provided key

setSack

public <S> void setSack(Supplier<S> initialValue,
                        UnaryOperator<S> splitOperator,
                        BinaryOperator<S> mergeOperator)

Set the initial value of each Traverser "sack" along with the operators for splitting and merging sacks. If no split operator is provided, then a direct memory copy is assumed (this is typically good for primitive types and strings). If no merge operator is provided, then traversers with sacks will not be merged.

Specified by:

setSack in interface TraversalSideEffects

Type Parameters:

S - the sack type

Parameters:

initialValue - the initial value supplier of the traverser sack

splitOperator - the split operator for splitting traverser sacks

mergeOperator - the merge operator for merging traverser sacks

getSackInitialValue

public <S> Supplier<S> getSackInitialValue()

If sacks are enabled, get the initial value of the Traverser sack. If its not enabled, then null is returned.

Specified by:

getSackInitialValue in interface TraversalSideEffects

Type Parameters:

S - the sack type

Returns:

the supplier of the initial value of the traverser sack

getSackSplitter

public <S> UnaryOperator<S> getSackSplitter()

If sacks are enabled and a split operator has been specified, then get it (else get null). The split operator is used to split a sack when a bifurcation in a Traverser happens.

Specified by:

getSackSplitter in interface TraversalSideEffects

Type Parameters:

S - the sack type

Returns:

the operator for splitting a traverser sack

getSackMerger

public <S> BinaryOperator<S> getSackMerger()

If sacks are enabled and a merge function has been specified, then get it (else get null). The merge function is used to merge two sacks when two Traversers converge.

Specified by:

getSackMerger in interface TraversalSideEffects

Type Parameters:

S - the sack type

Returns:

the operator for merging two traverser sacks

remove

public void remove(String key)

Remove both the value and registered Supplier associated with provided key.

Specified by:

remove in interface TraversalSideEffects

Parameters:

key - the key of the value and registered supplier to remove

keys

public Set<String> keys()

The keys of the sideEffect which includes registered Supplier keys. In essence, that which is possible to get().

Specified by:

keys in interface TraversalSideEffects

Returns:

the keys of the sideEffect

mergeInto

public void mergeInto(TraversalSideEffects sideEffects)

Add the current TraversalSideEffects values, suppliers, and reducers to the provided TraversalSideEffects. The implementation should (under the hood), use TraversalSideEffects.registerIfAbsent(String, Supplier, BinaryOperator) so that if the argument TraversalSideEffects already has a registered supplier or binary operator, then don't overwrite it.

Specified by:

mergeInto in interface TraversalSideEffects

Parameters:

sideEffects - the sideEffects to add this traversal's sideEffect data to.

toString

public String toString()

Overrides:

toString in class Object

clone

public DefaultTraversalSideEffects clone()

Cloning is used to duplicate the sideEffects typically in distributed execution environments.

Specified by:

clone in interface TraversalSideEffects

Overrides:

clone in class Object

Returns:

The cloned sideEffects

registerSupplier

@Deprecated
public void registerSupplier(String key,
                                         Supplier supplier)

Deprecated.

Register a Supplier with the provided key. When sideEffects get() are called, if no object exists and there exists a registered supplier for the key, the object is generated. Registered suppliers are used for the lazy generation of sideEffect data.

Specified by:

registerSupplier in interface TraversalSideEffects

Parameters:

key - the key to register the supplier with

supplier - the supplier that will generate an object when get() is called if it hasn't already been created

registerSupplierIfAbsent

@Deprecated
public void registerSupplierIfAbsent(String key,
                                                 Supplier supplier)

Deprecated.

A helper method to register a Supplier if it has not already been registered.

Specified by:

registerSupplierIfAbsent in interface TraversalSideEffects

Parameters:

key - the key of the supplier to register

supplier - the supplier to register if the key has not already been registered

getRegisteredSupplier

@Deprecated
public <V> Optional<Supplier<V>> getRegisteredSupplier(String key)

Deprecated.

Get the registered Supplier associated with the specified key.

Specified by:

getRegisteredSupplier in interface TraversalSideEffects

Type Parameters:

V - The object type of the supplier

Parameters:

key - the key associated with the supplier

Returns:

A non-empty optional if the supplier exists

getOrCreate

@Deprecated
public <V> V getOrCreate(String key,
                                     Supplier<V> orCreate)

Deprecated.

If the sideEffect contains an object associated with the key, return it. Else if a "with" supplier exists for the key, generate the object, store it in the sideEffects and return the object. Else use the provided supplier to generate the object, store it in the sideEffects and return the object. Note that if the orCreate supplier is used, it is NOT registered as a Supplier.

Specified by:

getOrCreate in interface TraversalSideEffects

Type Parameters:

V - the return type of the object

Parameters:

key - the key of the object to get

orCreate - if the object doesn't exist as an object or suppliable object, then generate it with the specified supplier

Returns:

the object that is either retrieved, generated, or supplier via orCreate