Jakarta EE 11.0.0 · jakarta.enterprise.concurrent.ManagedExecutorDefinition

Defines a ManagedExecutorService to be injected into ManagedExecutorService injection points including any required Qualifier annotations specified by qualifiers() and 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,

@ManagedExecutorDefinition(
    name = "java:module/concurrent/MyExecutor",
    qualifiers = MyQualifier.class,
    context = "java:module/concurrent/MyExecutorContext",
    hungTaskThreshold = 120000,
    maxAsync = 5)
@ContextServiceDefinition(
    name = "java:module/concurrent/MyExecutorContext",
    propagated = { SECURITY, APPLICATION })
public class MyServlet extends HttpServlet {
    @Inject
    @MyQualifier
    ManagedExecutorService myExecutor1;

    @Resource(lookup = "java:module/concurrent/MyExecutor",
              name = "java:module/concurrent/env/MyExecutorRef")
    ManagedExecutorService myExecutor2;
    ...

@Qualifier
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE })
public @interface MyQualifier {}

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

<resource-env-ref>
   <resource-env-ref-name>java:module/env/concurrent/MyExecutorRef</resource-env-ref-name>
   <resource-env-ref-type>jakarta.enterprise.concurrent.ManagedExecutorService</resource-env-ref-type>
   <lookup-name>java:module/concurrent/MyExecutor</lookup-name>
</resource-env-ref>

You can also define a ManagedExecutorService with the <managed-executor> deployment descriptor element. For example,

<managed-executor>
   <name>java:module/concurrent/MyExecutor</name>
   <context-service-ref>java:module/concurrent/MyExecutorContext</context-service-ref>
   <hung-task-threshold>120000</hung-task-threshold>
   <max-async>5</max-async>
</managed-executor>

If a managed-executor and ManagedExecutorDefinition have the same name, their attributes are merged to define a single ManagedExecutorService definition, with each attribute that is specified in the managed-executor deployment descriptor entry taking precedence over the corresponding attribute of the annotation. If any qualifier elements are specified, the set of qualifier elements replaces the qualifiers attribute of the annotation.

Nested and Inner Type Summary

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

Method Summary

Modifier and Type	Method and Description
public String	Returns: name of the `ContextService` for capturing and propagating or clearing context. context() The name of a `ContextService` instance which determines how context is applied to tasks and actions that run on this executor.
public long	Returns: number of milliseconds after which a task or action is considered hung. hungTaskThreshold() The amount of time in milliseconds that a task or action can execute before it is considered hung.
public int	Returns: upper limit on asynchronous execution. maxAsync() Upper bound on contextual tasks and actions that this executor will simultaneously execute asynchronously.
public String	Returns: `ManagedExecutorService` JNDI name. name() JNDI name of the `ManagedExecutorService` instance.
public Class<?>[]	Returns: list of qualifiers. qualifiers() List of required `qualifier annotations`.
public boolean	Returns: `true` if the executor can create virtual threads, otherwise `false`. virtual() Indicates whether this executor is requested to create virtual `threads` for tasks that do not run inline.

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

Method Detail

context back to summary

context	back to summary
public String context() The name of a `ContextService` instance which determines how context is applied to tasks and actions that run on this executor. The name can be the name of a `ContextServiceDefinition` or the name of a `context-service` deployment descriptor element or the JNDI name of the Jakarta EE default `ContextService` instance, `java:comp/DefaultContextService`. The name of the `ContextService` must be no more granular than the name of this `ManagedExecutorDefinition`. For example, if this `ManagedExecutorDefinition` has a name in `java:app`, the `ContextService` can be in `java:app` or `java:global`, but not in `java:module` which would be ambiguous as to which module's `ContextService` definition should be used. The default value, `java:comp/DefaultContextService`, is the JNDI name of the Jakarta EE default `ContextService`. Returns:String name of the `ContextService` for capturing and propagating or clearing context.

public String context()

The name of a ContextService instance which determines how context is applied to tasks and actions that run on this executor.

The name can be the name of a ContextServiceDefinition or the name of a context-service deployment descriptor element or the JNDI name of the Jakarta EE default ContextService instance, java:comp/DefaultContextService.

The name of the ContextService must be no more granular than the name of this ManagedExecutorDefinition. For example, if this ManagedExecutorDefinition has a name in java:app, the ContextService can be in java:app or java:global, but not in java:module which would be ambiguous as to which module's ContextService definition should be used.

The default value, java:comp/DefaultContextService, is the JNDI name of the Jakarta EE default ContextService.

Returns:String: name of the ContextService for capturing and propagating or clearing context.

hungTaskThreshold back to summary

hungTaskThreshold	back to summary
public long hungTaskThreshold() The amount of time in milliseconds that a task or action can execute before it is considered hung. The default value of `-1` indicates unlimited. Returns:long number of milliseconds after which a task or action is considered hung.

public long hungTaskThreshold()

The amount of time in milliseconds that a task or action can execute before it is considered hung.

The default value of -1 indicates unlimited.

Returns:long: number of milliseconds after which a task or action is considered hung.

maxAsync back to summary

maxAsync	back to summary
public int maxAsync() Upper bound on contextual tasks and actions that this executor will simultaneously execute asynchronously. This constraint does not apply to tasks and actions that the executor runs inline, such as when a thread requests `java.util.concurrent.CompletableFuture#join()` and the action runs inline if it has not yet started. This constraint does not apply to tasks that are scheduled via `Asynchronous#runAt()`. The default value of `-1` indicates unbounded, although still subject to resource constraints of the system. Returns:int upper limit on asynchronous execution.

public int maxAsync()

Upper bound on contextual tasks and actions that this executor will simultaneously execute asynchronously. This constraint does not apply to tasks and actions that the executor runs inline, such as when a thread requests java.util.concurrent.CompletableFuture#join() and the action runs inline if it has not yet started. This constraint does not apply to tasks that are scheduled via Asynchronous#runAt().

The default value of -1 indicates unbounded, although still subject to resource constraints of the system.

Returns:int: upper limit on asynchronous execution.

name back to summary

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

public String name()

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

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

Returns:String: ManagedExecutorService JNDI name.

qualifiers back to summary

qualifiers	back to summary
public Class<?>[] qualifiers() List of required `qualifier annotations`. A `ManagedExecutorService` injection point with these qualifier annotations injects a bean that is produced by this `ManagedExecutorDefinition`. The default value is an empty list, indicating that this `ManagedExecutorDefinition` does not automatically produce bean instances for any injection points. When the qualifiers list is non-empty, the container creates a `ManagedExecutorService` instance and registers an `ApplicationScoped` bean for it with the specified required qualifiers and required type of `ManagedExecutorService`. The life cycle of the bean aligns with the life cycle of the application and the bean is not accessible from outside of the application. Applications must not configure a `java:global` `name` if also configuring a non-empty list of qualifiers. Applications can define their own `Producers` for `ManagedExecutorService` injection points as long as the qualifier annotations on the producer do not conflict with the non-empty `qualifiers()` list of a `ManagedExecutorDefinition`. Returns:Class<?>[] list of qualifiers. Since 3.1

public Class<?>[] qualifiers()

List of required qualifier annotations.

A ManagedExecutorService injection point with these qualifier annotations injects a bean that is produced by this ManagedExecutorDefinition.

The default value is an empty list, indicating that this ManagedExecutorDefinition does not automatically produce bean instances for any injection points.

When the qualifiers list is non-empty, the container creates a ManagedExecutorService instance and registers an ApplicationScoped bean for it with the specified required qualifiers and required type of ManagedExecutorService. The life cycle of the bean aligns with the life cycle of the application and the bean is not accessible from outside of the application. Applications must not configure a java:global name if also configuring a non-empty list of qualifiers.

Applications can define their own Producers for ManagedExecutorService injection points as long as the qualifier annotations on the producer do not conflict with the non-empty qualifiers() list of a ManagedExecutorDefinition.

Returns:Class<?>[]: list of qualifiers.
Since: 3.1

virtual back to summary

virtual	back to summary
public boolean virtual() Indicates whether this executor is requested to create virtual `threads` for tasks that do not run inline. Virtual threads are discussed in the `Thread` JavaDoc under the section that is titled Virtual threads. When `true`, the executor can create virtual threads if it is capable of doing so and if the request is not overridden by vendor-specific configuration that restricts the use of virtual threads. The default is `false`, indicating that the executor must not create virtual threads. It should be noted that some tasks, such as completion stage actions, can run inline on an existing thread in response to events such as the completion of another stage or a join operation on the completion stage. In situations such as these, the executor does not control the type of thread that is used to run the task. When running on Java SE 17, the `true` value behaves the same as the `false` value and results in platform threads being created rather than virtual threads. Returns:boolean `true` if the executor can create virtual threads, otherwise `false`. Since 3.1

public boolean virtual()

Indicates whether this executor is requested to create virtual threads for tasks that do not run inline. Virtual threads are discussed in the Thread JavaDoc under the section that is titled Virtual threads.

When true, the executor can create virtual threads if it is capable of doing so and if the request is not overridden by vendor-specific configuration that restricts the use of virtual threads.

The default is false, indicating that the executor must not create virtual threads.

It should be noted that some tasks, such as completion stage actions, can run inline on an existing thread in response to events such as the completion of another stage or a join operation on the completion stage. In situations such as these, the executor does not control the type of thread that is used to run the task.

When running on Java SE 17, the true value behaves the same as the false value and results in platform threads being created rather than virtual threads.

Returns:boolean: true if the executor can create virtual threads, otherwise false.
Since: 3.1

public @Interface ManagedExecutorDefinition

Nested and Inner Type Summary

Method Summary

Method Detail

public @Interface ManagedExecutorDefinition.List

Method Summary

Method Detail