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 Deprecated 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> 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 `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

    - #### 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

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