org.apache.tinkerpop.gremlin.process.traversal

## Interface TraversalSideEffects

- All Superinterfaces:
    AutoCloseable, Cloneable, Serializable

      public interface TraversalSideEffects
      extends Cloneable, Serializable, AutoCloseable

  A `Traversal` can maintain global sideEffects. Unlike `Traverser` "sacks" which are local sideEffects, TraversalSideEffects are accessible by all `Traverser` instances within the `Traversal`.
  Author:
    Marko A. Rodriguez (http://markorodriguez.com)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `TraversalSideEffects.Exceptions`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and 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 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.
    `default boolean` | `isEmpty()` Determines if there are any side-effects to be retrieved.
    `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.

- - ### 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 registered `Supplier` 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, use `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.
      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.

    - #### remove

          void remove(String key)

      Remove both the value and registered `Supplier` 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 registered `Supplier` keys. In essence, that which is possible to `get(String)`.
      Returns:
        the keys of the sideEffect

    - #### close

          default void close()
                      throws Exception

      Invalidate the side effect cache for traversal.
      Specified by:
        `close` in interface `AutoCloseable`
      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 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.
      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

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

          <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.
      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, then `ConstantSupplier` 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 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.
      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

          <S> Supplier<S> getSackInitialValue()

      If sacks are enabled, get the initial value of the `Traverser` sack. If its not enabled, then `null` 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 get `null`). The split operator is used to split a sack when a bifurcation in a `Traverser` 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 get `null`). The merge function is used to merge two sacks when two `Traverser`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 current `TraversalSideEffects` values, suppliers, and reducers to the provided `TraversalSideEffects`. The implementation should (under the hood), use `registerIfAbsent(String, Supplier, BinaryOperator)` so that if the argument `TraversalSideEffects` 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.

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