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

    All Methods Instance Methods Concrete Methods
    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> 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 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` | `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 `Traverser`s 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

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