ManagedExecutor.Builder (MicroProfile Context Propagation 1.0 API)

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
Modifier and Type	Method and Description
`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.

Interface ManagedExecutor.Builder

Method Summary

Method Detail

build

cleared

propagated

maxAsync

maxQueued