public interface ThreadContextProvider
Third party providers of thread context implement this interface to enable the
provided type of context to participate in thread context capture and propagation
when the ManagedExecutor
and ThreadContext
are used to create and contextualize dependent
actions and tasks.
Application code must never access the classes within this spi
package. Instead, application code uses the ManagedExecutor
and
ThreadContext
interfaces.
The ThreadContextProvider
implementation and related classes are
packaged within the third party provider's JAR file. The implementation is made
discoverable via the standard ServiceLoader
mechanism. The JAR file
that packages it must include a file of the following name and location,
META-INF/services/org.eclipse.microprofile.context.spi.ThreadContextProvider
The content of the aforementioned file must be one or more lines, each specifying
the fully qualified name of a ThreadContextProvider
implementation
that is provided within the JAR file.
ManagedExecutor
and ThreadContext
must use the
ServiceLoader
to identify all available implementations of
ThreadContextProvider
that can participate in thread context capture
and propagation and must invoke them either to capture current thread context or establish
default thread context per the configuration of the ManagedExecutor
or
ThreadContext
instance wherever these interfaces are used to create
and contextualize dependent actions and tasks.
Modifier and Type | Method and Description |
---|---|
ThreadContextSnapshot |
clearedContext(Map<String,String> props)
Returns empty/cleared context of the provided type.
|
ThreadContextSnapshot |
currentContext(Map<String,String> props)
Captures from the current thread a snapshot of the provided thread context type.
|
String |
getThreadContextType()
Returns a human readable identifier for the type of thread context that is
captured by this
ThreadContextProvider implementation. |
ThreadContextSnapshot currentContext(Map<String,String> props)
props
- provided for compatibility with EE Concurrency spec, which allows
for specifying a set of 'execution properties' when capturing thread context.
Thread context providers that don't supply or use execution properties
can ignore this parameter.IllegalStateException
- the Transaction
context provider may raise this exception
if it chooses not to support the optional capability of propagating Transaction
context across threads. This exception flows back to the application when the
application invokes an operation that captures context, such as
runAsync
,
withContextCapture
, and
contextualFunction
.ThreadContextSnapshot clearedContext(Map<String,String> props)
Returns empty/cleared context of the provided type. This context is not captured from the current thread, but instead represents the behavior that you get for this context type when no particular context has been applied to the thread.
This is used in cases where the provided type of thread context should not be propagated from the requesting thread or inherited from the thread of execution, in which case it is necessary to establish an empty/cleared context in its place, so that an action does not unintentionally inherit context of the thread that happens to run it.
For example, a security context provider's empty/cleared context ensures there is no authenticated user on the thread. A transaction context provider's empty/cleared context ensures that any active transaction is suspended. And so forth.
props
- provided for compatibility with EE Concurrency spec, which allows
for specifying a set of 'execution properties'. Thread context providers
that don't supply or use execution properties can ignore this parameter.String getThreadContextType()
Returns a human readable identifier for the type of thread context that is
captured by this ThreadContextProvider
implementation.
To ensure portability of applications, this will typically be a keyword that is defined by the same specification that defines the thread context type, or by a related MicroProfile specification.
The ThreadContext
interface defines constants for some commonly
used thread context types, including Application, Security, Transaction,
and CDI.
The application can use the values documented for the various thread context
types when configuring a ManagedExecutor
or ThreadContext
to capture and propagate only specific types of thread context.
For example:
ManagedExecutor executor = ManagedExecutor.builder()
.propagated(ThreadContext.CDI)
.cleared(ThreadContext.ALL_REMAINING)
.build();
It is an error for multiple thread context providers of identical type to be
simultaneously available (for example, two providers of CDI
context
found on the ServiceLoader
). If this is found to be the case,
ManagedExecutor
and ThreadContext
must fail to inject.
Copyright © 2019 Eclipse Foundation. All rights reserved.