EE4J Web API 10.0.0 · jakarta.enterprise.concurrent.spi.ThreadContextProvider

Third party providers of thread context implement this interface to participate in thread context capture and propagation.

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.

Method Summary

Modifier and Type	Method and Description
public ThreadContextSnapshot	Returns: immutable empty/default context of the provided type. clearedContext(Map<String, String> 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. props) Returns empty/cleared context of the provided type.
public ThreadContextSnapshot	Returns: immutable snapshot of the provided type of context, captured from the current thread. currentContext(Map<String, String> 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. props) Captures from the current thread a snapshot of the provided thread context type.
public String	Returns: identifier for the provided type of thread context. getThreadContextType() Returns a human readable identifier for the type of thread context that is captured by this `ThreadContextProvider` implementation.

Method Detail

clearedContext	back to summary
public 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. Parameters props:Map<String, String> 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. Returns:ThreadContextSnapshot immutable empty/default context of the provided type.

clearedContext

back to summary

public 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.

Parameters

props:Map<String, String>: 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.

Returns:ThreadContextSnapshot

immutable empty/default context of the provided type.

currentContext	back to summary
public ThreadContextSnapshot currentContext(Map<String, String> props) Captures from the current thread a snapshot of the provided thread context type. Parameters props:Map<String, String> 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. Returns:ThreadContextSnapshot immutable snapshot of the provided type of context, captured from the current thread.

currentContext

back to summary

public ThreadContextSnapshot currentContext(Map<String, String> props)

Captures from the current thread a snapshot of the provided thread context type.

Parameters

props:Map<String, String>: 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.

Returns:ThreadContextSnapshot

immutable snapshot of the provided type of context, captured from the current thread.

getThreadContextType back to summary

getThreadContextType	back to summary
public 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 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. Returns:String identifier for the provided type of thread context.

public 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 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.

Returns:String: identifier for the provided type of thread context.

public Interface ThreadContextProvider

Method Summary

Method Detail