@Repeatable(value=ContextServiceDefinition.List.class) @Retention(value=RUNTIME) @Target(value=TYPE) public @interface 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
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.
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 | Fields and Description |
---|---|
static java.lang.String |
ALL_REMAINING
All available thread context types that are not specified
elsewhere.
|
static java.lang.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. |
static java.lang.String |
SECURITY
Context that controls the credentials that are associated
with the thread, including the caller subject and
invocation/RunAs subject.
|
static java.lang.String |
TRANSACTION
Context that controls the transaction that is associated
with the thread.
|
Modifier and Type | Required Element and Description |
---|---|
java.lang.String |
name
JNDI name of the
ContextService instance being defined. |
Modifier and Type | Optional Element and Description |
---|---|
java.lang.String[] |
cleared
Types of context to clear whenever a thread runs the
contextual task or action.
|
java.lang.String[] |
propagated
Types of context to capture from the requesting thread
and propagate to a thread that runs the contextual task
or action.
|
java.lang.String[] |
unchanged
Types of context that are left alone when a thread
runs the contextual task or action.
|
public static final java.lang.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 java.lang.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 java.lang.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.
public static final java.lang.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 abstract java.lang.String name
JNDI name of the ContextService
instance being defined.
The JNDI name must be in a valid Jakarta EE namespace,
such as,
ContextService
JNDI name.public abstract java.lang.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.
public abstract java.lang.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.
public abstract java.lang.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.