Interface TraversalSideEffects
-
- All Superinterfaces:
AutoCloseable
,Cloneable
,Serializable
public interface TraversalSideEffects extends Cloneable, Serializable, AutoCloseable
ATraversal
can maintain global sideEffects. UnlikeTraverser
"sacks" which are local sideEffects, TraversalSideEffects are accessible by allTraverser
instances within theTraversal
.- Author:
- Marko A. Rodriguez (http://markorodriguez.com)
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
TraversalSideEffects.Exceptions
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
add(String key, Object value)
Add a value to the global side-effect value.TraversalSideEffects
clone()
Cloning is used to duplicate the sideEffects typically in distributed execution environments.default void
close()
Invalidate the side effect cache for traversal.default boolean
exists(String key)
Return true if the key is a registered side-effect.default <V> void
forEach(BiConsumer<String,V> biConsumer)
<V> V
get(String key)
Get the sideEffect associated with the provided key.<V> BinaryOperator<V>
getReducer(String key)
Get the reducer associated with the side-effect key.<S> Supplier<S>
getSackInitialValue()
If sacks are enabled, get the initial value of theTraverser
sack.<S> BinaryOperator<S>
getSackMerger()
If sacks are enabled and a merge function has been specified, then get it (else getnull
).<S> UnaryOperator<S>
getSackSplitter()
If sacks are enabled and a split operator has been specified, then get it (else getnull
).<V> Supplier<V>
getSupplier(String key)
Get the supplier associated with the side-effect key.default boolean
isEmpty()
Determines if there are any side-effects to be retrieved.Set<String>
keys()
The keys of the sideEffect which includes registeredSupplier
keys.void
mergeInto(TraversalSideEffects sideEffects)
Add the currentTraversalSideEffects
values, suppliers, and reducers to the providedTraversalSideEffects
.<V> void
register(String key, Supplier<V> initialValue, BinaryOperator<V> reducer)
<V> void
registerIfAbsent(String key, Supplier<V> initialValue, BinaryOperator<V> reducer)
void
remove(String key)
Remove both the value and registeredSupplier
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 eachTraverser
"sack" along with the operators for splitting and merging sacks.
-
-
-
Method Detail
-
exists
default boolean exists(String key)
Return true if the key is a registered side-effect.- Parameters:
key
- the key to check for existence- Returns:
- whether the key exists or not
-
get
<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 registeredSupplier
for that key, generate the object, store the object in the sideEffects, and return it.- 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
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, useadd(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.- Parameters:
key
- the key they key of the side-effectvalue
- the value the new value for the side-effect- Throws:
IllegalArgumentException
- if the key does not reference a registered side-effect.
-
remove
void remove(String key)
Remove both the value and registeredSupplier
associated with provided key.- Parameters:
key
- the key of the value and registered supplier to remove
-
keys
Set<String> keys()
The keys of the sideEffect which includes registeredSupplier
keys. In essence, that which is possible toget(String)
.- Returns:
- the keys of the sideEffect
-
close
default void close() throws Exception
Invalidate the side effect cache for traversal.- Specified by:
close
in interfaceAutoCloseable
- Throws:
Exception
-
isEmpty
default boolean isEmpty()
Determines if there are any side-effects to be retrieved.
-
register
<V> void register(String key, Supplier<V> initialValue, BinaryOperator<V> reducer)
Register a side-effect with theTraversalSideEffects
providing aSupplier
and aBinaryOperator
. If a null value is provided for the supplier or reducer, then it no supplier or reducer is registered.- Type Parameters:
V
- the type of the side-effect value- Parameters:
key
- the key of the side-effect valueinitialValue
- the initial value supplierreducer
- the reducer to use for merging a distributed side-effect value into a single value
-
registerIfAbsent
<V> void registerIfAbsent(String key, Supplier<V> initialValue, BinaryOperator<V> reducer)
Register a side-effect with theTraversalSideEffects
providing aSupplier
and aBinaryOperator
. 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.- Type Parameters:
V
- the type of the side-effect value- Parameters:
key
- the key of the side-effect valueinitialValue
- the initial value supplierreducer
- the reducer to use for merging a distributed side-effect value into a single value
-
getReducer
<V> BinaryOperator<V> getReducer(String key) throws IllegalArgumentException
Get the reducer associated with the side-effect key. If no reducer was registered, thenOperator.assign
is provided.- 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
<V> Supplier<V> getSupplier(String key) throws IllegalArgumentException
Get the supplier associated with the side-effect key. If no supplier was registered, thenConstantSupplier
is provided.- 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
-
add
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.set(String, Object)
should only be used in single-threaded systems or by a master traversal in a distributed environment.- 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
-
setSack
<S> void setSack(Supplier<S> initialValue, UnaryOperator<S> splitOperator, BinaryOperator<S> mergeOperator)
Set the initial value of eachTraverser
"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.- Type Parameters:
S
- the sack type- Parameters:
initialValue
- the initial value supplier of the traverser sacksplitOperator
- the split operator for splitting traverser sacksmergeOperator
- the merge operator for merging traverser sacks
-
getSackInitialValue
<S> Supplier<S> getSackInitialValue()
If sacks are enabled, get the initial value of theTraverser
sack. If its not enabled, thennull
is returned.- Type Parameters:
S
- the sack type- Returns:
- the supplier of the initial value of the traverser sack
-
getSackSplitter
<S> UnaryOperator<S> getSackSplitter()
If sacks are enabled and a split operator has been specified, then get it (else getnull
). The split operator is used to split a sack when a bifurcation in aTraverser
happens.- Type Parameters:
S
- the sack type- Returns:
- the operator for splitting a traverser sack
-
getSackMerger
<S> BinaryOperator<S> getSackMerger()
If sacks are enabled and a merge function has been specified, then get it (else getnull
). The merge function is used to merge two sacks when twoTraverser
s converge.- Type Parameters:
S
- the sack type- Returns:
- the operator for merging two traverser sacks
-
forEach
default <V> void forEach(BiConsumer<String,V> biConsumer)
-
clone
TraversalSideEffects clone()
Cloning is used to duplicate the sideEffects typically in distributed execution environments.- Returns:
- The cloned sideEffects
-
mergeInto
void mergeInto(TraversalSideEffects sideEffects)
Add the currentTraversalSideEffects
values, suppliers, and reducers to the providedTraversalSideEffects
. The implementation should (under the hood), useregisterIfAbsent(String, Supplier, BinaryOperator)
so that if the argumentTraversalSideEffects
already has a registered supplier or binary operator, then don't overwrite it.- Parameters:
sideEffects
- the sideEffects to add this traversal's sideEffect data to.
-
-