Chapter 9. Jakarta Concurrency

Jakarta Concurrency is an API that accommodates Java SE concurrency utilities into the Jakarta EE application environment specifications. It is defined in Jakarta Concurrency specification. JBoss EAP allows you to create, edit, and delete instances of Jakarta Concurrency, thus making these instances readily available for applications to use.

Jakarta Concurrency help to extend the invocation context by pulling in the existing context’s application threads and using these in its own threads. This extending of invocation context includes class loading, JNDI, and security contexts, by default.

Types of Jakarta Concurrency include:

  • Context Service
  • Managed Thread Factory
  • Managed Executor Service
  • Managed Scheduled Executor Service

Example: Jakarta Concurrency in standalone.xml

<subsystem xmlns="urn:jboss:domain:ee:4.0">
            <spec-descriptor-property-replacement>false</spec-descriptor-property-replacement>
            <concurrent>
                <context-services>
                    <context-service name="default" jndi-name="java:jboss/ee/concurrency/context/default" use-transaction-setup-provider="true"/>
                </context-services>
                <managed-thread-factories>
                    <managed-thread-factory name="default" jndi-name="java:jboss/ee/concurrency/factory/default" context-service="default"/>
                </managed-thread-factories>
                <managed-executor-services>
                    <managed-executor-service name="default" jndi-name="java:jboss/ee/concurrency/executor/default" context-service="default" hung-task-threshold="60000" keepalive-time="5000"/>
                </managed-executor-services>
                <managed-scheduled-executor-services>
                    <managed-scheduled-executor-service name="default" jndi-name="java:jboss/ee/concurrency/scheduler/default" context-service="default" hung-task-threshold="60000" keepalive-time="3000"/>
                </managed-scheduled-executor-services>
            </concurrent>
            <default-bindings context-service="java:jboss/ee/concurrency/context/default" datasource="java:jboss/datasources/ExampleDS" managed-executor-service="java:jboss/ee/concurrency/executor/default" managed-scheduled-executor-service="java:jboss/ee/concurrency/scheduler/default" managed-thread-factory="java:jboss/ee/concurrency/factory/default"/>
</subsystem>

9.1. Context Service

The context service (javax.enterprise.concurrent.ContextService) allows you to build contextual proxies from existing objects. Contextual proxy prepares the invocation context, which is used by other Jakarta Concurrency utilities when the context is created or invoked, before transferring the invocation to the original object.

Attributes of the context service concurrency utility include:

  • name: A unique name within all the context services.
  • jndi-name: Defines where the context service should be placed in JNDI.
  • use-transaction-setup-provider: Optional. Indicates if the contextual proxies built by the context service should suspend transactions in context when invoking the proxy objects. Its value defaults to false, but the default context service has the value true.

See the example above for the usage of the context service concurrency utility.

Example: Add a New Context Service

/subsystem=ee/context-service=newContextService:add(jndi-name=java:jboss/ee/concurrency/contextservice/newContextService)

Example: Change a Context Service

/subsystem=ee/context-service=newContextService:write-attribute(name=jndi-name, value=java:jboss/ee/concurrency/contextservice/changedContextService)

This operation requires reload.

Example: Remove a Context Service

/subsystem=ee/context-service=newContextService:remove()

This operation requires reload.

9.2. Managed Thread Factory

The managed thread factory (javax.enterprise.concurrent.ManagedThreadFactory) concurrency utility allows Jakarta EE applications to create Java threads. JBoss EAP handles the managed thread factory instances, hence Jakarta EE applications cannot invoke any lifecycle related method.

Attributes of managed thread factory concurrency utility include:

  • context-service: A unique name within all managed thread factories.
  • jndi-name: Defines where in JNDI the managed thread factory should be placed.
  • priority: Optional. Indicates the priority for new threads created by the factory, and defaults to 5.

Example: Add a New Managed Thread Factory

/subsystem=ee/managed-thread-factory=newManagedTF:add(context-service=newContextService, jndi-name=java:jboss/ee/concurrency/threadfactory/newManagedTF, priority=2)

Example: Change a Managed Thread Factory

/subsystem=ee/managed-thread-factory=newManagedTF:write-attribute(name=jndi-name, value=java:jboss/ee/concurrency/threadfactory/changedManagedTF)

This operation requires reload. Similarly, you can change other attributes as well.

Example: Remove a Managed Thread Factory

/subsystem=ee/managed-thread-factory=newManagedTF:remove()

This operation requires reload.

9.3. Managed Executor Service

Managed executor service (javax.enterprise.concurrent.ManagedExecutorService) allows Jakarta EE applications to submit tasks for asynchronous execution. JBoss EAP handles managed executor service instances, hence Jakarta EE applications cannot invoke any lifecycle related method.

Attributes of managed executor service concurrency utility include:

  • context-service: Optional. References an existing context service by its name. If specified, then the referenced context service will capture the invocation context present when submitting a task to the executor, which will then be used when executing the task.
  • jndi-name: Defines where the managed thread factory should be placed in JNDI.
  • max-threads: Defines the maximum number of threads used by the executor. If undefined, the value from core-threads is used.
  • thread-factory: References an existing managed thread factory by its name, to handle the creation of internal threads. If not specified, then a managed thread factory with default configuration will be created and used internally.
  • core-threads: Defines the minimum number of threads to be used by the executor. If this attribute is undefined, the default is calculated based on the number of processors. A value of 0 is not recommended. See the queue-length attribute for details on how this value is used to determine the queuing strategy.
  • keepalive-time: Defines the time, in milliseconds, that an internal thread can be idle. The attribute default value is 60000.
  • queue-length: Indicates the executor’s task queue capacity. A value of 0 means direct hand-off and possible rejection will occur. If this attribute is undefined or set to Integer.MAX_VALUE, this indicates that an unbounded queue should be used. All other values specify an exact queue size. If an unbounded queue or direct hand-off is used, a core-threads value greater than 0 is required.
  • hung-task-threshold: Defines the time, in milliseconds, after which tasks are considered hung by the managed executor service and forcefully aborted. If the value is 0, which is the default, tasks are never considered hung.
  • long-running-tasks: Suggests optimizing the execution of long running tasks, and defaults to false.
  • reject-policy: Defines the policy to use when a task is rejected by the executor. The attribute value can be the default ABORT, which means an exception should be thrown, or RETRY_ABORT, which means the executor will try to submit it once more, before throwing an exception

Example: Add a New Managed Executor Service

/subsystem=ee/managed-executor-service=newManagedExecutorService:add(jndi-name=java:jboss/ee/concurrency/executor/newManagedExecutorService, core-threads=7, thread-factory=default)

Example: Change a Managed Executor Service

/subsystem=ee/managed-executor-service=newManagedExecutorService:write-attribute(name=core-threads,value=10)

This operation requires reload. Similarly, you can change other attributes too.

Example: Remove a Managed Executor Service

/subsystem=ee/managed-executor-service=newManagedExecutorService:remove()

This operation requires reload.

9.4. Managed Scheduled Executor Service

Managed scheduled executor service (javax.enterprise.concurrent.ManagedScheduledExecutorService) allows Jakarta EE applications to schedule tasks for asynchronous execution. JBoss EAP handles managed scheduled executor service instances, hence Jakarta EE applications cannot invoke any lifecycle related method.

Attributes of managed executor service concurrency utility include:

  • context-service: References an existing context service by its name. If specified then the referenced context service will capture the invocation context present when submitting a task to the executor, which will then be used when executing the task.
  • hung-task-threshold: Defines the time, in milliseconds, after which tasks are considered hung by the managed scheduled executor service and forcefully aborted. If the value is 0, which is the default, tasks are never considered hung.
  • keepalive-time: Defines the time, in milliseconds, that an internal thread can be idle. The attribute default value is 60000.
  • reject-policy: Defines the policy to use when a task is rejected by the executor. The attribute value might be the default ABORT, which means an exception should be thrown, or RETRY_ABORT, which means the executor will try to submit it once more, before throwing an exception.
  • core-threads: Defines the minimum number of threads to be used by the scheduled executor.
  • jndi-name: Defines where the managed scheduled executor service should be placed in JNDI .
  • long-running-tasks: Suggests optimizing the execution of long running tasks, and defaults to false.
  • thread-factory: References an existing managed thread factory by its name, to handle the creation of internal threads. If not specified, then a managed thread factory with default configuration will be created and used internally.

Example: Add a New Managed Scheduled Executor Service

/subsystem=ee/managed-scheduled-executor-service=newManagedScheduledExecutorService:add(jndi-name=java:jboss/ee/concurrency/scheduledexecutor/newManagedScheduledExecutorService, core-threads=7, context-service=default)

This operation requires reload.

Example: Changed a Managed Scheduled Executor Service

/subsystem=ee/managed-scheduled-executor-service=newManagedScheduledExecutorService:write-attribute(name=core-threads, value=10)

This operation requires reload. Similarly, you can change other attributes.

Example: Remove a Managed Scheduled Executor Service

/subsystem=ee/managed-scheduled-executor-service=newManagedScheduledExecutorService:remove()

This operation requires reload.

9.5. Runtime statistics for managed executor services and managed scheduled executor services

You can monitor the performance of managed executor services and managed scheduled executor services by viewing the runtime statistics generated with the management CLI attributes. You can view the runtime statistics for a standalone server or for an individual server mapped to a host.

Important

The domain.xml configuration does not include a resource for the runtime statistic management CLI attributes, so you cannot use the management CLI attributes to view the runtime statistics for a managed domain.

Table 9.1. Displays management CLI attributes for monitoring the performance of managed executor services and of managed scheduled executor services.

AttributeDescription

active-thread-count

The approximate number of threads that are actively executing tasks.

completed-task-count

The approximate total number of tasks that have completed execution.

hung-thread-count

The number of executor threads that are hung.

max-thread-count

The largest number of executor threads.

current-queue-size

The current size of the executor’s task queue.

task-count

The approximate total number of tasks that have been submitted for execution.

thread-count

The current number of executor threads.

Example of viewing the runtime statistics for a managed executor service running on a standalone server.

[standalone@localhost:9990 /] /subsystem=ee/managed-executor-service=default:read-resource(include-runtime=true,recursive=true)

Example of the runtime statistics for a managed scheduled executor service running on a standalone server.

[standalone@localhost:9990 /] /subsystem=ee/managed-scheduled-executor-service=default:read-resource(include-runtime=true,recursive=true)

Example of viewing the runtime statistics for a managed executor service running on a server mapped to a host.

[domain@localhost:9990 /] /host=<host_name>/server=<server_name>/subsystem=ee/managed-executor-service=default:read-resource(include-runtime=true,recursive=true)

Example of the runtime statistics for a managed scheduled executor service running on a server mapped to a host.

[domain@localhost:9990 /] /host=<host_name>/server=<server_name>/subsystem=ee/managed-scheduled-executor-service=default:read-resource(include-runtime=true,recursive=true)

Additional resources