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

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 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 the 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 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 the 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 the JNDI.
  • max-threads: Defines the maximum number of threads used by the executor, which defaults to Integer.MAX_VALUE.
  • 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: Provides the number of threads to keep in the executor’s pool, even if they are idle. A value of 0 means there is no limit.
  • keepalive-time: Defines the time, in milliseconds, that an internal thread may be idle. The attribute default value is 60000.
  • queue-length: Indicates the number of tasks that can be stored in the input queue. The default value is 0, which means the queue capacity is unlimited.
  • 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 may 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 may 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 may 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: Provides the number of threads to keep in the executor’s pool, even if they are idle. A value of 0 means there is no limit.
  • jndi-name: Defines where the managed scheduled executor service should be placed in the 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.