org.eclipse.microprofile.context

## Interface ManagedExecutor.Builder

Enclosing interface:
  ManagedExecutor

    public static interface ManagedExecutor.Builder

Builder for `ManagedExecutor` instances.

Example usage:

     ManagedExecutor executor = ManagedExecutor.builder()
                                                      .maxAsync(5)
                                                      .maxQueued(20)
                                                      .propagated(ThreadContext.SECURITY)
                                                      .build();
     ...

### Method Summary

All Methods Instance Methods Abstract Methods
`ManagedExecutor` `build()` Builds a new `ManagedExecutor` with the configuration that this builder represents as of the point in time when this method is invoked.
`ManagedExecutor.Builder` `cleared(String... types)` Defines the set of thread context types to clear from the thread where the action or task executes.
`ManagedExecutor.Builder` `maxAsync(int max)` Establishes an upper bound on the number of async completion stage actions and async executor tasks that can be running at any given point in time.
`ManagedExecutor.Builder` `maxQueued(int max)` Establishes an upper bound on the number of async actions and async tasks that can be queued up for execution.
`ManagedExecutor.Builder` `propagated(String... types)` Defines the set of thread context types to capture from the thread that creates a dependent stage (or that submits a task) and which to propagate to the thread where the action or task executes.

### Method Detail

#### build

    ManagedExecutor build()

Builds a new `ManagedExecutor` 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 `ManagedExecutor` instances.

All created instances of `ManagedExecutor` are destroyed when the application is stopped. The container automatically shuts down these managed executors.

Returns:
  new instance of `ManagedExecutor`.
Throws:
  `IllegalStateException` - for any of the following error conditions
  - if one or more of the same context types appear in both the `cleared(java.lang.String...)` set and the `propagated(java.lang.String...)` set
  - 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 provider provides the same thread context `type`

#### cleared

    ManagedExecutor.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 the `propagated(java.lang.String...)` set does not 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.ManagedExecutor.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

    ManagedExecutor.Builder propagated(String... types)

Defines the set of thread context types to capture from the thread that creates a dependent stage (or that submits a task) and which to propagate to the thread 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.ManagedExecutor.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 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.

#### maxAsync

    ManagedExecutor.Builder maxAsync(int max)

Establishes an upper bound on the number of async completion stage actions and async executor tasks that can be running at any given point in time. There is no guarantee that async actions or tasks will start running immediately, even when the `maxAsync` constraint has not get been reached. Async actions and tasks remain queued until the `ManagedExecutor` starts executing them.

The default value of `-1` indicates no upper bound, although practically, resource constraints of the system will apply. You can switch the default by specifying the MicroProfile Config property, `mp.context.ManagedExecutor.maxAsync`.

Parameters:
  `max` - upper bound on async completion stage actions and executor tasks.
Returns:
  the same builder instance upon which this method is invoked.
Throws:
  `IllegalArgumentException` - if max is 0 or less than -1.

#### maxQueued

    ManagedExecutor.Builder maxQueued(int max)

Establishes an upper bound on the number of async actions and async tasks that can be queued up for execution. Async actions and tasks are rejected if no space in the queue is available to accept them.

The default value of `-1` indicates no upper bound, although practically, resource constraints of the system will apply. You can switch the default by specifying the MicroProfile Config property, `mp.context.ManagedExecutor.maxQueued`.

Parameters:
  `max` - upper bound on async actions and tasks that can be queued.
Returns:
  the same builder instance upon which this method is invoked.
Throws:
  `IllegalArgumentException` - if max is 0 or less than -1.