org.eclipse.microprofile.context

## Interface ThreadContext

    public interface ThreadContext

This interface offers various methods for capturing the context of the current thread and applying it to various interfaces that are commonly used with completion stages and executor services. This allows you to contextualize specific actions that need access to the context of the creator/submitter of the stage/task.

Example usage:

     ThreadContext threadContext = ThreadContext.builder()
         .propagated(ThreadContext.SECURITY, ThreadContext.APPLICATION)
         .cleared(ThreadContext.TRANSACTION)
         .unchanged(ThreadContext.ALL_REMAINING)
         .build();
     ...
     CompletableFuture<Integer> stage2 = stage1.thenApply(threadContext.contextualFunction(function));
     ...
     Future<Integer> future = executor.submit(threadContext.contextualCallable(callable));

This interface is intentionally kept compatible with ContextService, with the hope that its methods might one day be contributed to that specification.

### Nested Class Summary

Nested Classes
`static interface` `ThreadContext.Builder` Builder for `ThreadContext` instances.

### Field Summary

Fields
`static String` `ALL_REMAINING` Identifier for all available thread context types which are not specified individually under `cleared`, `propagated`, or `unchanged`.
`static String` `APPLICATION` Identifier for application context.
`static String` `CDI` Identifier for CDI context.
`static String[]` `NONE` An empty array of thread context.
`static String` `SECURITY` Identifier for security context.
`static String` `TRANSACTION` Identifier for transaction context.

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
`static ThreadContext.Builder` `builder()` Creates a new `ThreadContext.Builder` instance.
`<R> Callable<R>` `contextualCallable(Callable<R> callable)` Wraps a `Callable` with context that is captured from the thread that invokes `contextualCallable`.
`<T,U> BiConsumer<T,U>` `contextualConsumer(BiConsumer<T,U> consumer)` Wraps a `BiConsumer` with context that is captured from the thread that invokes `contextualConsumer`.
`<T> Consumer<T>` `contextualConsumer(Consumer<T> consumer)` Wraps a `Consumer` with context that is captured from the thread that invokes `contextualConsumer`.
`<T,U,R> BiFunction<T,U,R>` `contextualFunction(BiFunction<T,U,R> function)` Wraps a `BiFunction` with context that is captured from the thread that invokes `contextualFunction`.
`<T,R> Function<T,R>` `contextualFunction(Function<T,R> function)` Wraps a `Function` with context that is captured from the thread that invokes `contextualFunction`.
`Runnable` `contextualRunnable(Runnable runnable)` Wraps a `Runnable` with context that is captured from the thread that invokes `ContextualRunnable`.
`<R> Supplier<R>` `contextualSupplier(Supplier<R> supplier)` Wraps a `Supplier` with context captured from the thread that invokes `contextualSupplier`.
`Executor` `currentContextExecutor()` Creates an `Executor`that runs tasks on the same thread from which `execute`is invoked but with context that is captured from the thread that invokes `currentContextExecutor`.
`<T> CompletableFuture<T>` `withContextCapture(CompletableFuture<T> stage)` Returns a new `CompletableFuture` that is completed by the completion of the specified stage.
`<T> CompletionStage<T>` `withContextCapture(CompletionStage<T> stage)` Returns a new `CompletionStage` that is completed by the completion of the specified stage.

### Field Detail

#### ALL_REMAINING

    static final String ALL_REMAINING

Identifier for all available thread context types which are not specified individually under `cleared`, `propagated`, or `unchanged`.

When using this constant, be aware that bringing in a new context provider or updating levels of an existing context provider might change the set of available thread context types.

See Also:
  `ManagedExecutor.Builder.cleared(java.lang.String...)`, `ManagedExecutor.Builder.propagated(java.lang.String...)`, `ThreadContext.Builder`, Constant Field Values

#### APPLICATION

    static final String APPLICATION

Identifier for application context. Application context controls the application component that is associated with a thread. For Jakarta/Java EE applications, application context includes the thread context class loader as well as the java:comp, java:module, and java:app name spaces of the application. An empty/default application context means that the thread is not associated with any application.

See Also:
  `ManagedExecutor.Builder.cleared(java.lang.String...)`, `ManagedExecutor.Builder.propagated(java.lang.String...)`, `ThreadContext.Builder`, Constant Field Values

#### CDI

    static final String CDI

Identifier for CDI context. CDI context controls the availability of CDI scopes. An empty/default CDI context means that the thread does not have access to the scope of the session, request, and so forth that created the contextualized action. For example, consider the following `@RequestScoped` resource:

        @RequestScoped
        public class MyRequestScopedBean {
            public String getState() {
              // returns some request-specific information to the caller
            }
        }

CDI context propagation includes request, session and conversation contexts. When CDI context is propagated, all of the above mentioned contexts that are currently active will be available to the contextualized task with preserved state.

        ManagedExecutor exec = ManagedExecutor.builder()
            .propagated(ThreadContext.CDI, ThreadContext.APPLICATION)
            .build();

        @Inject
        MyRequestScopedBean requestBean;

        @GET
        public void foo() {
            exec.supplyAsync(() -> {
                String state = reqBean.getState();
                // do some work with the request state
            }).thenApply(more -> {
                // request state also available in future stages
            });
        }

If CDI context is 'cleared', currently active contexts will still be available to the contextualized task, but their state will be erased. If CDI context is 'unchanged', access to CDI bean's contextual state will be non-deterministic. Namely, context may be missing, or context from a different task may be applied instead. This option is discouraged, and only should be used if CDI context is not used in an application.

See Also:
  `ManagedExecutor.Builder.cleared(java.lang.String...)`, `ManagedExecutor.Builder.propagated(java.lang.String...)`, `ThreadContext.Builder`, Constant Field Values

#### NONE

    static final String[] NONE

An empty array of thread context.

This is provided as a convenience for code that wishes to be more explicit. For example, you can specify `builder.propagated(ThreadContext.NONE)` rather than `builder.propagated(new String[0])` or `builder.propagated()`, all of which have the same meaning.

When using MicroProfile Config to specify defaults, the value `None` indicates an empty array. For example,

    mp.context.ThreadContext.unchanged=None

or

    mp.context.ManagedExecutor.propagated=None

#### SECURITY

    static final String SECURITY

Identifier for security context. Security context controls the credentials that are associated with the thread. An empty/default security context means that the thread is unauthenticated.

See Also:
  `ManagedExecutor.Builder.cleared(java.lang.String...)`, `ManagedExecutor.Builder.propagated(java.lang.String...)`, `ThreadContext.Builder`, Constant Field Values

#### TRANSACTION

    static final String TRANSACTION

Identifier for transaction context. Transaction context controls the active transaction scope that is associated with the thread. Implementations are not expected to propagate transaction context across threads. Instead, the concept of transaction context is provided for its cleared context, which means the active transaction on the thread is suspended such that a new transaction can be started if so desired. In most cases, the most desirable behavior will be to leave transaction context defaulted to cleared (suspended), in order to prevent dependent actions and tasks from accidentally enlisting in transactions that are on the threads where they happen to run.

See Also:
  `ManagedExecutor.Builder.cleared(java.lang.String...)`, `ManagedExecutor.Builder.propagated(java.lang.String...)`, `ThreadContext.Builder`, Constant Field Values

### Method Detail

#### builder

    static ThreadContext.Builder builder()

Creates a new `ThreadContext.Builder` instance.

Returns:
  a new `ThreadContext.Builder` instance.

#### currentContextExecutor

    Executor currentContextExecutor()

Creates an `Executor`that runs tasks on the same thread from which `execute`is invoked but with context that is captured from the thread that invokes `currentContextExecutor`.

Example usage:

     Executor contextSnapshot = threadContext.currentContextExecutor();
     ...
     // from another thread, or after thread context has changed,
     contextSnapshot.execute(() -> obj.doSomethingThatNeedsContext());
     contextSnapshot.execute(() -> doSomethingElseThatNeedsContext(x, y));

The returned `Executor` must raise `IllegalArgumentException` if an already-contextualized `Runnable` is supplied to its `execute` method.

Returns:
  an executor that wraps the `execute` method with context.

#### contextualCallable

    <R> Callable<R> contextualCallable(Callable<R> callable)

Wraps a `Callable` with context that is captured from the thread that invokes `contextualCallable`.

When `call` is invoked on the proxy instance, context is first established on the thread that will run the `call` method, then the `call` method of the provided `Callable` is invoked. Finally, the previous context is restored on the thread, and the result of the `Callable` is returned to the invoker.

Type Parameters:
  `R` - callable result type.
Parameters:
  `callable` - instance to contextualize.
Returns:
  contextualized proxy instance that wraps execution of the `call` method with context.
Throws:
  `IllegalArgumentException` - if an already-contextualized `Callable` is supplied to this method.

#### contextualConsumer

    <T,U> BiConsumer<T,U> contextualConsumer(BiConsumer<T,U> consumer)

Wraps a `BiConsumer` with context that is captured from the thread that invokes `contextualConsumer`.

When `accept` is invoked on the proxy instance, context is first established on the thread that will run the `accept` method, then the `accept` method of the provided `BiConsumer` is invoked. Finally, the previous context is restored on the thread, and control is returned to the invoker.

Type Parameters:
  `T` - type of first parameter to consumer.
  `U` - type of second parameter to consumer.
Parameters:
  `consumer` - instance to contextualize.
Returns:
  contextualized proxy instance that wraps execution of the `accept` method with context.
Throws:
  `IllegalArgumentException` - if an already-contextualized `BiConsumer` is supplied to this method.

#### contextualConsumer

    <T> Consumer<T> contextualConsumer(Consumer<T> consumer)

Wraps a `Consumer` with context that is captured from the thread that invokes `contextualConsumer`.

When `accept` is invoked on the proxy instance, context is first established on the thread that will run the `accept` method, then the `accept` method of the provided `Consumer` is invoked. Finally, the previous context is restored on the thread, and control is returned to the invoker.

Type Parameters:
  `T` - type of parameter to consumer.
Parameters:
  `consumer` - instance to contextualize.
Returns:
  contextualized proxy instance that wraps execution of the `accept` method with context.
Throws:
  `IllegalArgumentException` - if an already-contextualized `Consumer` is supplied to this method.

#### contextualFunction

    <T,U,R> BiFunction<T,U,R> contextualFunction(BiFunction<T,U,R> function)

Wraps a `BiFunction` with context that is captured from the thread that invokes `contextualFunction`.

When `apply` is invoked on the proxy instance, context is first established on the thread that will run the `apply` method, then the `apply` method of the provided `BiFunction` is invoked. Finally, the previous context is restored on the thread, and the result of the `BiFunction` is returned to the invoker.

Type Parameters:
  `T` - type of first parameter to function.
  `U` - type of second parameter to function.
  `R` - function result type.
Parameters:
  `function` - instance to contextualize.
Returns:
  contextualized proxy instance that wraps execution of the `apply` method with context.
Throws:
  `IllegalArgumentException` - if an already-contextualized `BiFunction` is supplied to this method.

#### contextualFunction

    <T,R> Function<T,R> contextualFunction(Function<T,R> function)

Wraps a `Function` with context that is captured from the thread that invokes `contextualFunction`.

When `apply` is invoked on the proxy instance, context is first established on the thread that will run the `apply` method, then the `apply` method of the provided `Function` is invoked. Finally, the previous context is restored on the thread, and the result of the `Function` is returned to the invoker.

Type Parameters:
  `T` - type of parameter to function.
  `R` - function result type.
Parameters:
  `function` - instance to contextualize.
Returns:
  contextualized proxy instance that wraps execution of the `apply` method with context.
Throws:
  `IllegalArgumentException` - if an already-contextualized `Function` is supplied to this method.

#### contextualRunnable

    Runnable contextualRunnable(Runnable runnable)

Wraps a `Runnable` with context that is captured from the thread that invokes `ContextualRunnable`.

When `run` is invoked on the proxy instance, context is first established on the thread that will run the `run` method, then the `run` method of the provided `Runnable` is invoked. Finally, the previous context is restored on the thread, and control is returned to the invoker.

Parameters:
  `runnable` - instance to contextualize.
Returns:
  contextualized proxy instance that wraps execution of the `run` method with context.
Throws:
  `IllegalArgumentException` - if an already-contextualized `Runnable` is supplied to this method.

#### contextualSupplier

    <R> Supplier<R> contextualSupplier(Supplier<R> supplier)

Wraps a `Supplier` with context captured from the thread that invokes `contextualSupplier`.

When `supply` is invoked on the proxy instance, context is first established on the thread that will run the `supply` method, then the `supply` method of the provided `Supplier` is invoked. Finally, the previous context is restored on the thread, and the result of the `Supplier` is returned to the invoker.

Type Parameters:
  `R` - supplier result type.
Parameters:
  `supplier` - instance to contextualize.
Returns:
  contextualized proxy instance that wraps execution of the `supply` method with context.
Throws:
  `IllegalArgumentException` - if an already-contextualized `Supplier` is supplied to this method.

#### withContextCapture

    <T> CompletableFuture<T> withContextCapture(CompletableFuture<T> stage)

Returns a new `CompletableFuture` that is completed by the completion of the specified stage.

The new completable future will use the same default executor as this ThreadContext, which can be a ManagedExecutor if this ThreadContext was obtained by `ManagedExecutor.getThreadContext()` or the default executor service if provided by the platform (which can be done via `ContextManager.Builder#withDefaultExecutorService(ExecutorService)`), or otherwise have no default executor.

If this thread context has no default executor, the new stage and all dependent stages created from it, and so forth, have no default asynchronous execution facility and must raise `UnsupportedOperationException` for all `*Async` methods that do not specify an executor. For example, `thenRunAsync(Runnable)`.

When dependent stages are created from the new completable future, thread context is captured and/or cleared as described in the documentation of the `ManagedExecutor` class, except that this ThreadContext instance takes the place of the default asynchronous execution facility in supplying the configuration of cleared/propagated context types. This guarantees that the action performed by each stage always runs under the thread context of the code that creates the stage, unless the user explicitly overrides by supplying a pre-contextualized action.

Invocation of this method does not impact thread context propagation for the supplied completable future or any dependent stages created from it, other than the new dependent completable future that is created by this method.

Type Parameters:
  `T` - completable future result type.
Parameters:
  `stage` - a completable future whose completion triggers completion of the new completable future that is created by this method.
Returns:
  the new completable future.

#### withContextCapture

    <T> CompletionStage<T> withContextCapture(CompletionStage<T> stage)

Returns a new `CompletionStage` that is completed by the completion of the specified stage.

The new completion stage will use the same default executor as this ThreadContext, which can be a ManagedExecutor if this ThreadContext was obtained by `ManagedExecutor.getThreadContext()` or the default executor service if provided by the platform (which can be done via `ContextManager.Builder#withDefaultExecutorService(ExecutorService)`), or otherwise have no default executor.

If this thread context has no default executor, the new stage and all dependent stages created from it, and so forth, have no default asynchronous execution facility and must raise `UnsupportedOperationException` for all `*Async` methods that do not specify an executor. For example, `thenRunAsync(Runnable)`.

When dependent stages are created from the new completion stage, thread context is captured and/or cleared as described in the documentation of the `ManagedExecutor` class, except that this ThreadContext instance takes the place of the default asynchronous execution facility in supplying the configuration of cleared/propagated context types. This guarantees that the action performed by each stage always runs under the thread context of the code that creates the stage, unless the user explicitly overrides by supplying a pre-contextualized action.

Invocation of this method does not impact thread context propagation for the supplied stage or any dependent stages created from it, other than the new dependent completion stage that is created by this method.

Type Parameters:
  `T` - completion stage result type.
Parameters:
  `stage` - a completion stage whose completion triggers completion of the new stage that is created by this method.
Returns:
  the new completion stage.