org.apache.tinkerpop.gremlin.process.traversal

## Interface TraversalSideEffects

- All Superinterfaces:
    AutoCloseable, Cloneable, Serializable
  All Known Subinterfaces:
    RemoteTraversalSideEffects
  All Known Implementing Classes:
    AbstractRemoteTraversalSideEffects, DefaultTraversalSideEffects, DriverRemoteTraversalSideEffects, EmbeddedRemoteTraversalSideEffects, EmptyTraversalSideEffects, MemoryTraversalSideEffects

      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 Deprecated 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.
    `default <V> V` | `getOrCreate(String key, Supplier<V> orCreate)` Deprecated. As of release 3.2.0, replaced by `register(String, Supplier, BinaryOperator)` to register side-effects.
    `<V> BinaryOperator<V>` | `getReducer(String key)` Get the reducer associated with the side-effect key.
    `<V> Optional<Supplier<V>>` | `getRegisteredSupplier(String key)` Deprecated. As of release 3.2.0, replaced by `getSupplier(String)`.
    `<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` | `registerSupplier(String key, Supplier supplier)` Deprecated. As of release 3.2.0, replaced by `register(String, Supplier, BinaryOperator)`.
    `default void` | `registerSupplierIfAbsent(String key, Supplier supplier)` Deprecated. As of release 3.2.0, replaced by `registerIfAbsent(String, Supplier, 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().
      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.

    - #### registerSupplier

          @Deprecated
          void registerSupplier(String key,
                                            Supplier supplier)

      Deprecated. As of release 3.2.0, replaced by `register(String, Supplier, BinaryOperator)`.
      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.
      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
          default void registerSupplierIfAbsent(String key,
                                                            Supplier supplier)

      Deprecated. As of release 3.2.0, replaced by `registerIfAbsent(String, Supplier, BinaryOperator)`.
      A helper method to register a `Supplier` if it has not already been registered.
      Parameters:
        `key` - the key of the supplier to register
        `supplier` - the supplier to register if the key has not already been registered

    - #### getRegisteredSupplier

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

      Deprecated. As of release 3.2.0, replaced by `getSupplier(String)`.
      Get the registered `Supplier` associated with the specified key.
      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
          default <V> V getOrCreate(String key,
                                                Supplier<V> orCreate)

      Deprecated. As of release 3.2.0, replaced by `register(String, Supplier, BinaryOperator)` to register side-effects.
      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`.
      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–2019 Apache Software Foundation. All rights reserved.