EE4J Web API 10.0.0 · jakarta.enterprise.concurrent.ContextServiceDefinition

Defines a ContextService to be registered in JNDI by the container under the JNDI name that is specified in the name() attribute.

Application components can refer to this JNDI name in the lookup attribute of a jakarta.annotation.Resource annotation,

@ContextServiceDefinition(
    name = "java:app/concurrent/MyContext",
    propagated = APPLICATION,
    unchanged = TRANSACTION,
    cleared = ALL_REMAINING)
public class MyServlet extends HttpServlet {
   @Resource(lookup = "java:app/concurrent/MyContext",
              name = "java:app/concurrent/env/MyContextRef")
    ContextService appContextSvc;

Resource environment references in a deployment descriptor can similarly specify the lookup-name,

<resource-env-ref>
   <resource-env-ref-name>java:app/env/concurrent/MyContextRef</resource-env-ref-name>
   <resource-env-ref-type>jakarta.enterprise.concurrent.ContextService</resource-env-ref-type>
   <lookup-name>java:app/concurrent/MyContext</lookup-name>
</resource-env-ref>

The cleared(), propagated(), and unchanged() attributes enable the application to configure how thread context is applied to tasks and actions that are contextualized by the ContextService. Constants are provided on this class for context types that are defined by the Jakarta EE Concurrency specification. In addition to those constants, a Jakarta EE product provider may choose to accept additional vendor-specific context types. Usage of vendor-specific types will make applications non-portable.

Overlap of the same context type across multiple lists is an error and prevents the ContextService instance from being created. If ALL_REMAINING is not present in any of the lists, it is implicitly appended to the cleared() context types.

You can also define a ContextService with the <context-service> deployment descriptor element. For example,

<context-service>
   <name>java:app/concurrent/MyContext</name>
   <cleared>Security</cleared>
   <cleared>Transaction</cleared>
   <propagated>Application</propagated>
   <unchanged>Remaining</unchanged>
</context-service>

If a context-service and ContextServiceDefinition have the same name, their attributes are merged to define a single ContextService definition, with each attribute that is specified in the context-service deployment descriptor entry taking precedence over the corresponding attribute of the annotation.

Modifier and Type	Class and Description
public static @interface	ContextServiceDefinition.List Enables multiple `ContextServiceDefinition` annotations on the same type.

Field Summary

Modifier and Type	Field and Description
public static final String	ALL_REMAINING All available thread context types that are not specified elsewhere.
public static final String	APPLICATION Context pertaining to the application component or module, including its Jakarta EE namespace (such as `java:comp/env/`) and thread context class loader.
public static final String	SECURITY Context that controls the credentials that are associated with the thread, including the caller subject and invocation/RunAs subject.
public static final String	TRANSACTION Context that controls the transaction that is associated with the thread.

Method Summary

Modifier and Type	Method and Description
public String[]	Returns: context types to clear. cleared() Types of context to clear whenever a thread runs the contextual task or action.
public String	Returns: `ContextService` JNDI name. name() JNDI name of the `ContextService` instance being defined.
public String[]	Returns: context types to capture and propagate. propagated() Types of context to capture from the requesting thread and propagate to a thread that runs the contextual task or action.
public String[]	Returns: context types to leave unchanged. unchanged() Types of context that are left alone when a thread runs the contextual task or action.

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Field Detail

ALL_REMAINING back to summary

ALL_REMAINING	back to summary
public static final String ALL_REMAINING All available thread context types that are not specified elsewhere. This includes thread context types from custom `ThreadContextProviders` that are not specified elsewhere. For example, to define a `ContextService` that propagates `SECURITY` context, leaves `TRANSACTION` context alone, and clears every other context type: @ContextServiceDefinition( name = "java:module/concurrent/SecurityContext", propagated = SECURITY, unchanged = TRANSACTION, cleared = ALL_REMAINING) public class MyServlet extends HttpServlet ...

public static final String ALL_REMAINING

All available thread context types that are not specified elsewhere. This includes thread context types from custom ThreadContextProviders that are not specified elsewhere.

For example, to define a ContextService that propagates SECURITY context, leaves TRANSACTION context alone, and clears every other context type:

@ContextServiceDefinition(
    name = "java:module/concurrent/SecurityContext",
    propagated = SECURITY,
    unchanged = TRANSACTION,
    cleared = ALL_REMAINING)
public class MyServlet extends HttpServlet ...

APPLICATION back to summary

APPLICATION	back to summary
public static final String APPLICATION Context pertaining to the application component or module, including its Jakarta EE namespace (such as `java:comp/env/`) and thread context class loader. A cleared application context means that the thread is not associated with any application component and lacks access to the Jakarta EE namespace and thread context class loader of the application.

public static final String APPLICATION

Context pertaining to the application component or module, including its Jakarta EE namespace (such as java:comp/env/) and thread context class loader.

A cleared application context means that the thread is not associated with any application component and lacks access to the Jakarta EE namespace and thread context class loader of the application.

SECURITY	back to summary
public static final String SECURITY Context that controls the credentials that are associated with the thread, including the caller subject and invocation/RunAs subject. A cleared security context gives the thread unauthenticated subjects.

SECURITY

back to summary

public static final String SECURITY

Context that controls the credentials that are associated with the thread, including the caller subject and invocation/RunAs subject.

A cleared security context gives the thread unauthenticated subjects.

TRANSACTION back to summary

TRANSACTION	back to summary
public static final String TRANSACTION Context that controls the transaction that is associated with the thread. When cleared transaction context is applied to a thread, any global transaction that was previously present there is first suspended such that the contextual task or action can begin and manage, as permitted by the container, its own new `jakarta.transaction.UserTransaction`. After the contextual task or action completes, the prior transaction is resumed on the thread. This is equivalent to the execution property, `ManagedTask#TRANSACTION` with a value of `ManagedTask#SUSPEND`. The execution property, `ManagedTask#TRANSACTION`, if specified, takes precedence over the behavior for transaction context that is specified on the resource definition annotations. Jakarta EE providers need not support the propagation of transactions to other threads and can reject resource definition annotations that include transaction as a propagated context.

public static final String TRANSACTION

Context that controls the transaction that is associated with the thread.

When cleared transaction context is applied to a thread, any global transaction that was previously present there is first suspended such that the contextual task or action can begin and manage, as permitted by the container, its own new jakarta.transaction.UserTransaction. After the contextual task or action completes, the prior transaction is resumed on the thread. This is equivalent to the execution property, ManagedTask#TRANSACTION with a value of ManagedTask#SUSPEND.

The execution property, ManagedTask#TRANSACTION, if specified, takes precedence over the behavior for transaction context that is specified on the resource definition annotations.

Jakarta EE providers need not support the propagation of transactions to other threads and can reject resource definition annotations that include transaction as a propagated context.

Method Detail

cleared	back to summary
public String[] cleared() Types of context to clear whenever a thread runs the contextual task or action. The thread's previous context is restored afterward. Constants are provided on this class for the context types that are defined by the Jakarta EE Concurrency specification. Returns:String[] context types to clear.

cleared

back to summary

public String[] cleared()

Types of context to clear whenever a thread runs the contextual task or action. The thread's previous context is restored afterward.

Constants are provided on this class for the context types that are defined by the Jakarta EE Concurrency specification.

Returns:String[]: context types to clear.

name back to summary

name	back to summary
public String name() JNDI name of the `ContextService` instance being defined. The JNDI name must be in a valid Jakarta EE namespace, such as, java:comp java:module java:app java:global Returns:String `ContextService` JNDI name.

public String name()

JNDI name of the ContextService instance being defined. The JNDI name must be in a valid Jakarta EE namespace, such as,

java:comp
java:module
java:app
java:global

Returns:String: ContextService JNDI name.

propagated	back to summary
public String[] propagated() Types of context to capture from the requesting thread and propagate to a thread that runs the contextual task or action. The captured context is re-established when threads run the contextual task or action, with the respective thread's previous context being restored afterward. Constants are provided on this class for the context types that are defined by the Jakarta EE Concurrency specification. Returns:String[] context types to capture and propagate.

propagated

back to summary

public String[] propagated()

Types of context to capture from the requesting thread and propagate to a thread that runs the contextual task or action. The captured context is re-established when threads run the contextual task or action, with the respective thread's previous context being restored afterward.

Constants are provided on this class for the context types that are defined by the Jakarta EE Concurrency specification.

Returns:String[]: context types to capture and propagate.

unchanged back to summary

unchanged	back to summary
public String[] unchanged() Types of context that are left alone when a thread runs the contextual task or action. For example, with `unchanged = TRANSACTION` if a transaction is started after a function is contextualized, but before the function is run on the same thread, the transaction will be active in the contextual function: Consumer<String, Integer> updateDB = contextService.contextualConsumer(fn); // later, on another thread tx.begin(); updateDB.accept("java:comp/env/jdbc/ds1"); //...additional transactional work tx.commit(); Constants are provided on this class for the context types that are defined by the Jakarta EE Concurrency specification. Returns:String[] context types to leave unchanged.

public String[] unchanged()

Types of context that are left alone when a thread runs the contextual task or action.

For example, with unchanged = TRANSACTION if a transaction is started after a function is contextualized, but before the function is run on the same thread, the transaction will be active in the contextual function:

Consumer<String, Integer> updateDB = contextService.contextualConsumer(fn);

// later, on another thread
tx.begin();
updateDB.accept("java:comp/env/jdbc/ds1");
//...additional transactional work
tx.commit();

Constants are provided on this class for the context types that are defined by the Jakarta EE Concurrency specification.

Returns:String[]: context types to leave unchanged.

public @Interface ContextServiceDefinition

Nested and Inner Type Summary

Field Summary

Method Summary

Field Detail

Method Detail

public @Interface ContextServiceDefinition.List

Method Summary

Method Detail