Package jakarta.enterprise.concurrent

Annotation Interface ManagedExecutorDefinition

@Repeatable(List.class) @Retention(RUNTIME) @Target(TYPE) public @interface ManagedExecutorDefinition

Defines a ManagedExecutorService to be injected into ManagedExecutorService injection points with the specified 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 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.
Since:
3.0

  • Nested Class Summary

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

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    name
    JNDI name of the ManagedExecutorService instance.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    context
    The name of a ContextService instance which determines how context is applied to tasks and actions that run on this executor.
    long
    hungTaskThreshold
    The amount of time in milliseconds that a task or action can execute before it is considered hung.
    int
    maxAsync
    Upper bound on contextual tasks and actions that this executor will simultaneously execute asynchronously.
    Class<?>[]
    qualifiers
    List of qualifier annotations.
    boolean
    virtual
    Indicates whether this executor is requested to create virtual threads for tasks that do not run inline.

  • Element Details

    • name

      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:
      ManagedExecutorService JNDI name.

    • qualifiers

      Class<?>[] qualifiers

      List of 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.

      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:
      list of qualifiers.
      Since:
      3.1
      Default:
      {}

    • context

      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:
      name of the ContextService for capturing and propagating or clearing context.
      Default:
      "java:comp/DefaultContextService"

    • hungTaskThreshold

      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:
      number of milliseconds after which a task or action is considered hung.
      Default:
      -1L

    • maxAsync

      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 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:
      upper limit on asynchronous execution.
      Default:
      -1

    • virtual

      boolean virtual

      Indicates whether this executor is requested to create virtual threads for tasks that do not run inline.

      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.

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