public interface ThreadContextProvider
Application code must never access the classes within this spi
package. Instead, application code uses the various interfaces that are defined
by the Jakarta Concurrency specification, such as
ManagedExecutorService
and ContextService.
The ThreadContextProvider implementation and related classes are
packaged within the third party provider's JAR file. The implementation is made
discoverable via the ServiceLoader mechanism. The JAR file
that packages it must include a file with the following name and location,
META-INF/services/jakarta.enterprise.concurrent.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.
The Jakarta EE Product Provider 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
ContextServiceDefinition,
or vendor-specific configuration, and execution properties such as
ManagedTask.TRANSACTION
that override context propagation configuration.
| Modifier and Type | Method and Description |
|---|---|
ThreadContextSnapshot |
clearedContext(java.util.Map<java.lang.String,java.lang.String> props)
Returns empty/cleared context of the provided type.
|
ThreadContextSnapshot |
currentContext(java.util.Map<java.lang.String,java.lang.String> props)
Captures from the current thread a snapshot of the provided thread context type.
|
java.lang.String |
getThreadContextType()
Returns a human readable identifier for the type of thread context that is
captured by this
ThreadContextProvider implementation. |
ThreadContextSnapshot currentContext(java.util.Map<java.lang.String,java.lang.String> props)
props - execution properties, which are optionally provided
by some types of tasks and contextual proxies.
Thread context providers that do not supply or use execution properties
can ignore this parameter.ThreadContextSnapshot clearedContext(java.util.Map<java.lang.String,java.lang.String> props)
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 - execution properties, which are optionally provided
by some types of tasks and contextual proxies.
Thread context providers that do not supply or use execution properties
can ignore this parameter.java.lang.String getThreadContextType()
ThreadContextProvider implementation.
To ensure portability of applications, this is typically be a keyword that is defined by the same specification that defines the thread context type.
ContextServiceDefinition
defines identifiers for built-in thread context types, including
Application,
Security, and
Transaction,
as well as the
Remaining
identifer which covers all remaining context.
These identifiers must not be returned from this method.
Applications use a combination of built-in identifiers and those that are
defined by other specifications and third-party context
types when configuring a ContextServiceDefinition
to capture and propagate only specific types of thread context.
For example:
@ContextServiceDefinition(
name = "java:module/concurrent/MyCustomContext",
propagated = MyCustomContextProvider.CONTEXT_NAME,
cleared = { ContextServiceDefinition.SECURITY, ContextServiceDefinition.TRANSACTION },
unchanged = ContextServiceDefinition.ALL_REMAINING)
It is an error for multiple thread context providers of an identical type to be simultaneously available.