ThreadContext.Builder (MicroProfile Context Propagation 1.0 API)

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

Interface ThreadContext.Builder

Method Summary

Method Detail

build

cleared

propagated

unchanged