org.eclipse.microprofile.context

## Interface ThreadContext.Builder

Enclosing interface:
  ThreadContext

    public static interface ThreadContext.Builder

Builder for `ThreadContext` instances.

Example usage:

     ThreadContext threadContext = ThreadContext.builder()
                                                       .propagated(ThreadContext.APPLICATION, ThreadContext.SECURITY)
                                                       .unchanged(ThreadContext.TRANSACTION)
                                                       .build();
     ...

### Method Summary

All Methods Instance Methods Abstract Methods
`ThreadContext` `build()` Builds a new `ThreadContext` instance with the configuration that this builder represents as of the point in time when this method is invoked.
`ThreadContext.Builder` `cleared(String... types)` Defines the set of thread context types to clear from the thread where the action or task executes.
`ThreadContext.Builder` `propagated(String... types)` Defines the set of thread context types to capture from the thread that contextualizes an action or task.
`ThreadContext.Builder` `unchanged(String... types)` Defines a set of thread context types that are essentially ignored, in that they are neither captured nor are they propagated or cleared from thread(s) that execute the action or task.

### Method Detail

#### build

    ThreadContext build()

Builds a new `ThreadContext` instance with the configuration that this builder represents as of the point in time when this method is invoked.

After `build()` is invoked, the builder instance retains its configuration and may be further updated to represent different configurations and build additional `ThreadContext` instances.

All created instances of `ThreadContext` are destroyed when the application is stopped. The container automatically shuts down these `ThreadContext` instances and raises `IllegalStateException` to reject subsequent attempts to apply previously captured thread context.

Returns:
  new instance of `ThreadContext`.
Throws:
  `IllegalStateException` - for any of the following error conditions
  - if one or more of the same context types appear in multiple of the following sets: (`cleared(java.lang.String...)`, `propagated(java.lang.String...)`, `unchanged(java.lang.String...)`)
  - if a thread context type that is configured to be `cleared(java.lang.String...)` or `propagated(java.lang.String...)` is unavailable
  - if context configuration is neither specified on the builder nor via MicroProfile Config, and the builder implementation lacks vendor-specific defaults of its own.
  - if more than one `ThreadContextProvider` has the same thread context `type`

#### cleared

    ThreadContext.Builder cleared(String... types)

Defines the set of thread context types to clear from the thread where the action or task executes. The previous context is resumed on the thread after the action or task ends.

This set replaces the `cleared` set that was previously specified on the builder instance, if any.

For example, if the user specifies `ThreadContext.TRANSACTION` in this set, then a transaction is not active on the thread when the action or task runs, such that each action or task is able to independently start and end its own transactional work.

`ThreadContext.ALL_REMAINING` is automatically appended to the set of cleared context if neither the `propagated(java.lang.String...)` set nor the `unchanged(java.lang.String...)` set include `ThreadContext.ALL_REMAINING`.

Constants for specifying some of the core context types are provided on `ThreadContext`. Other thread context types must be defined by the specification that defines the context type or by a related MicroProfile specification.

The MicroProfile Config property, `mp.context.ThreadContext.cleared`, establishes a default that is used if no value is otherwise specified. The value of the MicroProfile Config property can be the empty string or a comma separated list of context type constant values.

Parameters:
  `types` - types of thread context to clear from threads that run actions and tasks.
Returns:
  the same builder instance upon which this method is invoked.

#### propagated

    ThreadContext.Builder propagated(String... types)

Defines the set of thread context types to capture from the thread that contextualizes an action or task. This context is later re-established on the thread(s) where the action or task executes.

This set replaces the `propagated` set that was previously specified on the builder instance, if any.

Constants for specifying some of the core context types are provided on `ThreadContext`. Other thread context types must be defined by the specification that defines the context type or by a related MicroProfile specification.

The MicroProfile Config property, `mp.context.ThreadContext.propagated`, establishes a default that is used if no value is otherwise specified. The value of the MicroProfile Config property can be the empty string or a comma separated list of context type constant values.

Thread context types which are not otherwise included in this set or in the `unchanged(java.lang.String...)` set are cleared from the thread of execution for the duration of the action or task.

Parameters:
  `types` - types of thread context to capture and propagate.
Returns:
  the same builder instance upon which this method is invoked.

#### unchanged

    ThreadContext.Builder unchanged(String... types)

Defines a set of thread context types that are essentially ignored, in that they are neither captured nor are they propagated or cleared from thread(s) that execute the action or task.

This set replaces the `unchanged` set that was previously specified on the builder instance.

Constants for specifying some of the core context types are provided on `ThreadContext`. Other thread context types must be defined by the specification that defines the context type or by a related MicroProfile specification.

The MicroProfile Config property, `mp.context.ThreadContext.unchanged`, establishes a default that is used if no value is otherwise specified. The value of the MicroProfile Config property can be the empty string or a comma separated list of context type constant values. If a default value is not specified by MicroProfile Config, then the default value is an empty set.

The configuration of `unchanged` context is provided for advanced patterns where it is desirable to leave certain context types on the executing thread.

For example, to run under the transaction of the thread of execution, with security context cleared and all other thread contexts propagated:

     ThreadContext threadContext = ThreadContext.builder()
                                                       .unchanged(ThreadContext.TRANSACTION)
                                                       .cleared(ThreadContext.SECURITY)
                                                       .propagated(ThreadContext.ALL_REMAINING)
                                                       .build();
     ...
     task = threadContext.contextualRunnable(new MyTransactionlTask());
     ...
     // on another thread,
     tx.begin();
     ...
     task.run(); // runs under the transaction due to 'unchanged'
     tx.commit();

Parameters:
  `types` - types of thread context to leave unchanged on the thread.
Returns:
  the same builder instance upon which this method is invoked.