Chapter 9. Concurrency Utilities

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

Concurrency Utilities 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 Concurrency Utilities include:

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

Example: Concurrency Utilities 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 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 Java EE applications to create Java threads. JBoss EAP handles the managed thread factory instances, hence Java 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 Java EE applications to submit tasks for asynchronous execution. JBoss EAP handles managed executor service instances, hence Java 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 Java EE applications to schedule tasks for asynchronous execution. JBoss EAP handles managed scheduled executor service instances, hence Java 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.