com.hazelcast.jet.pipeline

## Class ContextFactory<C>

- java.lang.Object
- - com.hazelcast.jet.pipeline.ContextFactory<C>

- Type Parameters:
    `C` - the user-defined context object type
  All Implemented Interfaces:
    Serializable

      public final class ContextFactory<C>
      extends Object
      implements Serializable

  A holder of functions needed to create and destroy a context object.

  You can use the context factory from these Pipeline API methods:

  - `GeneralStage.mapUsingContext(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.BiFunctionEx<? super C, ? super T, ? extends R>)`
  - `GeneralStage.filterUsingContext(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.BiPredicateEx<? super C, ? super T>)`
  - `GeneralStage.flatMapUsingContext(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.BiFunctionEx<? super C, ? super T, ? extends com.hazelcast.jet.Traverser<R>>)`
  - `GeneralStage.mapUsingContextAsync(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.BiFunctionEx<? super C, ? super T, ? extends java.util.concurrent.CompletableFuture<R>>)`
  - `GeneralStage.filterUsingContextAsync(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.BiFunctionEx<? super C, ? super T, ? extends java.util.concurrent.CompletableFuture<java.lang.Boolean>>)`
  - `GeneralStage.flatMapUsingContextAsync(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.BiFunctionEx<? super C, ? super T, ? extends java.util.concurrent.CompletableFuture<com.hazelcast.jet.Traverser<R>>>)`
  - `GeneralStageWithKey.mapUsingContext(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.TriFunction<? super C, ? super K, ? super T, ? extends R>)`
  - `GeneralStageWithKey.filterUsingContext(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.TriPredicate<? super C, ? super K, ? super T>)`
  - `GeneralStageWithKey.flatMapUsingContext(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.TriFunction<? super C, ? super K, ? super T, ? extends com.hazelcast.jet.Traverser<? extends R>>)`
  - `GeneralStageWithKey.mapUsingContextAsync(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.TriFunction<? super C, ? super K, ? super T, java.util.concurrent.CompletableFuture<R>>)`
  - `GeneralStageWithKey.filterUsingContextAsync(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.TriFunction<? super C, ? super K, ? super T, java.util.concurrent.CompletableFuture<java.lang.Boolean>>)`
  - `GeneralStageWithKey.flatMapUsingContextAsync(com.hazelcast.jet.pipeline.ContextFactory<C>, com.hazelcast.jet.function.TriFunction<? super C, ? super K, ? super T, java.util.concurrent.CompletableFuture<com.hazelcast.jet.Traverser<R>>>)`
  Since:
    3.0
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `COOPERATIVE_DEFAULT` Default value for `isCooperative`.
    `static int` | `MAX_PENDING_CALLS_DEFAULT` Default value for `maxPendingCallsPerProcessor`.
    `static boolean` | `ORDERED_ASYNC_RESPONSES_DEFAULT` Default value for `hasOrderedAsyncResponses()`.
    `static boolean` | `SHARE_LOCALLY_DEFAULT` Default value for `hasLocalSharing`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `FunctionEx<JetInstance,? extends C>` | `createFn()` Returns the create-function.
    `ConsumerEx<? super C>` | `destroyFn()` Returns the destroy-function.
    `boolean` | `hasLocalSharing()` Returns the `hasLocalSharing` flag.
    `boolean` | `hasOrderedAsyncResponses()` Tells whether the async responses are ordered, see `withUnorderedAsyncResponses()`.
    `boolean` | `isCooperative()` Returns the `isCooperative` flag.
    `int` | `maxPendingCallsPerProcessor()` Returns the maximum pending calls per processor, see `withMaxPendingCallsPerProcessor(int)`.
    `ContextFactory<C>` | `toNonCooperative()` Returns a copy of this `ContextFactory` with the isCooperative flag set to `false`.
    `static <C> ContextFactory<C>` | `withCreateFn(FunctionEx<JetInstance,? extends C> createContextFn)` Creates a new `ContextFactory` with the given create-function.
    `ContextFactory<C>` | `withDestroyFn(ConsumerEx<? super C> destroyFn)` Returns a copy of this `ContextFactory` with the destroy-function replaced with the given function.
    `ContextFactory<C>` | `withLocalSharing()` Returns a copy of this `ContextFactory` with the localSharing flag set.
    `ContextFactory<C>` | `withMaxPendingCallsPerProcessor(int maxPendingCallsPerProcessor)` Returns a copy of this `ContextFactory` with the maxPendingCallsPerProcessor property set to the given value.
    `ContextFactory<C>` | `withUnorderedAsyncResponses()` Returns a copy of this `ContextFactory` with the unorderedAsyncResponses flag set to true.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### MAX_PENDING_CALLS_DEFAULT

          public static final int MAX_PENDING_CALLS_DEFAULT

      Default value for `maxPendingCallsPerProcessor`.
      See Also:
        Constant Field Values

    - #### COOPERATIVE_DEFAULT

          public static final boolean COOPERATIVE_DEFAULT

      Default value for `isCooperative`.
      See Also:
        Constant Field Values

    - #### SHARE_LOCALLY_DEFAULT

          public static final boolean SHARE_LOCALLY_DEFAULT

      Default value for `hasLocalSharing`.
      See Also:
        Constant Field Values

    - #### ORDERED_ASYNC_RESPONSES_DEFAULT

          public static final boolean ORDERED_ASYNC_RESPONSES_DEFAULT

      Default value for `hasOrderedAsyncResponses()`.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### withCreateFn

          @Nonnull
          public static <C> ContextFactory<C> withCreateFn(@Nonnull
                                                                    FunctionEx<JetInstance,? extends C> createContextFn)

      Creates a new `ContextFactory` with the given create-function.
      Type Parameters:
        `C` - the user-defined context object type
      Parameters:
        `createContextFn` - the function to create new context object, given a JetInstance
      Returns:
        a new factory instance
      Since:
        3.0

    - #### withDestroyFn

          @Nonnull
          public ContextFactory<C> withDestroyFn(@Nonnull
                                                          ConsumerEx<? super C> destroyFn)

      Returns a copy of this `ContextFactory` with the destroy-function replaced with the given function.

      The destroy function is called at the end of the job to destroy all created context objects.

      Parameters:
        `destroyFn` - the function to destroy user-defined context
      Returns:
        a copy of this factory with the supplied destroy-function

    - #### toNonCooperative

          @Nonnull
          public ContextFactory<C> toNonCooperative()

      Returns a copy of this `ContextFactory` with the isCooperative flag set to `false`. The context factory is cooperative by default. Call this method if your transform function doesn't follow the cooperative processor contract, that is if it waits for IO, blocks for synchronization, takes too long to complete etc. If you intend to use the factory for an async operation, you also typically can use a cooperative processor. Cooperative processors offer higher performance.
      Returns:
        a copy of this factory with the `isCooperative` flag set to `false`.

    - #### withLocalSharing

          @Nonnull
          public ContextFactory<C> withLocalSharing()

      Returns a copy of this `ContextFactory` with the localSharing flag set. If the pipeline doesn't have grouping, there will be:
      - one context object per local processor, if flag is disabled
      - one context object per member, if flag is enabled. Make sure the context object is thread-safe in this case.
      Returns:
        a copy of this factory with the `hasLocalSharing` flag set.

    - #### withMaxPendingCallsPerProcessor

          @Nonnull
          public ContextFactory<C> withMaxPendingCallsPerProcessor(int maxPendingCallsPerProcessor)

      Returns a copy of this `ContextFactory` with the maxPendingCallsPerProcessor property set to the given value. Jet will execute at most this many concurrent async operations per processor and will apply backpressure to the upstream.

      If you use the same context factory on multiple pipeline stages, each stage will count the pending calls independently.

      This value is ignored when the `ContextFactory` is used in a synchronous transformation.

      Default value is 256.

      Returns:
        a copy of this factory with the `maxPendingCallsPerProcessor` property set.

    - #### withUnorderedAsyncResponses

          @Nonnull
          public ContextFactory<C> withUnorderedAsyncResponses()

      Returns a copy of this `ContextFactory` with the unorderedAsyncResponses flag set to true.

      Jet can process asynchronous responses in two modes:

      1. Unordered: results of the async calls are emitted as they arrive. This mode is enabled by this method.
      2. Ordered: results of the async calls are emitted in the submission order. This is the default.
      The unordered mode can be faster:
      - in the ordered mode, one stalling call will block all subsequent items, even though responses for them were already received
      - to preserve the order after a restart, the ordered implementation when saving the state to the snapshot waits for all async calls to complete. This creates a hiccup depending on the async call latency. The unordered one saves in-flight items to the state snapshot.
      The order of watermarks is preserved even in the unordered mode. Jet forwards the watermark after having emitted all the results of the items that came before it. One stalling response will prevent a windowed operation downstream from finishing, but if the operation is configured to emit early results, they will be more correct with the unordered approach.

      This value is ignored when the `ContextFactory` is used in a synchronous transformation: the output is always ordered in this case.

      Returns:
        a copy of this factory with the `unorderedAsyncResponses` flag set.

    - #### createFn

          @Nonnull
          public FunctionEx<JetInstance,? extends C> createFn()

      Returns the create-function.

    - #### destroyFn

          @Nonnull
          public ConsumerEx<? super C> destroyFn()

      Returns the destroy-function.

    - #### isCooperative

          public boolean isCooperative()

      Returns the `isCooperative` flag.

    - #### hasLocalSharing

          public boolean hasLocalSharing()

      Returns the `hasLocalSharing` flag.

    - #### maxPendingCallsPerProcessor

          public int maxPendingCallsPerProcessor()

      Returns the maximum pending calls per processor, see `withMaxPendingCallsPerProcessor(int)`.

    - #### hasOrderedAsyncResponses

          public boolean hasOrderedAsyncResponses()

      Tells whether the async responses are ordered, see `withUnorderedAsyncResponses()`.

Copyright © 2020. All rights reserved.