Chapter 5. EJB Subsystem Tuning

JBoss EAP can cache Enterprise Java Beans (EJBs) to save initialization time. This is accomplished using bean pools.

There are two different bean pools that can be tuned in JBoss EAP: bean instance pools and bean thread pools.

Appropriate bean pool sizes depend on your environment and applications. It is recommended that you experiment with different bean pool sizes and perform stress testing in a development environment that emulates your expected real-world conditions.

5.1. Bean Instance Pools

Bean instance pools are used for Stateless Session Beans (SLSBs) and Message Driven Beans (MDBs). By default, SLSBs use the instance pool default-slsb-instance-pool, and MDBs use the instance pool default-mdb-instance-pool.

The size of a bean instance pool limits the number of instances of a particular EJB that can be created at one time. If the pool for a particular EJB is full, the client will block and wait for an instance to become available. If a client does not get an instance within the time set in the pool’s timeout attributes, an exception is thrown.

The size of a bean instance pool is configured using either derive-size or max-pool-size. The derive-size attribute allows you to configure the pool size using one of the following values:

  • from-worker-pools, which indicates that the maximum pool size is derived from the size of the total threads for all worker pools configured on the system.
  • from-cpu-count, which indicates that the maximum pool size is derived from the total number of processors available on the system. Note that this is not necessarily a 1:1 mapping, and might be augmented by other factors.

If derive-size is undefined, then the value of max-pool-size is used for the size of the bean instance pool.

Note

The derive-size attribute overrides any value specified in max-pool-size. derive-size must be undefined for the max-pool-size value to take effect.

You can configure an EJB to use a specific instance pool. This allows for finer control of the instances available to each EJB type.

5.1.1. Creating a Bean Instance Pool

This section shows you how to create a new bean instance pool using the management CLI. You can also configure bean instance pools using the management console by navigating to the EJB 3 subsystem from the Configuration tab, and then selecting the Bean Pools tab.

To create a new instance pool, use one of the following commands:

  • To create a bean instance pool with a derived maximum pool size:

    /subsystem=ejb3/strict-max-bean-instance-pool=POOL_NAME:add(derive-size=DERIVE_OPTION,timeout-unit=TIMEOUT_UNIT,timeout=TIMEOUT_VALUE)

    The following example creates a bean instance pool named my_derived_pool with a maximum size derived from the CPU count, and a timeout of 2 minutes:

    /subsystem=ejb3/strict-max-bean-instance-pool=my_derived_pool:add(derive-size=from-cpu-count,timeout-unit=MINUTES,timeout=2)
  • To create a bean instance pool with an explicit maximum pool size:

    /subsystem=ejb3/strict-max-bean-instance-pool=POOL_NAME:add(max-pool-size=POOL_SIZE,timeout-unit=TIMEOUT_UNIT,timeout=TIMEOUT_VALUE)

    The following example creates a bean instance pool named my_pool with a maximum of 30 instances and a timeout of 30 seconds:

    /subsystem=ejb3/strict-max-bean-instance-pool=my_pool:add(max-pool-size=30,timeout-unit=SECONDS,timeout=30)

5.1.2. Specifying the Instance Pool a Bean Should Use

You can set a specific instance pool that a particular bean will use either by using the @org.jboss.ejb3.annotation.Pool annotation, or by modifying the jboss-ejb3.xml deployment descriptor of the bean. See the jboss-ejb3.xml Deployment Descriptor Reference in Developing EJB Applications for more information.

5.1.3. Disabling the Default Bean Instance Pool

The default bean instance pool can be disabled, which results in EJBs not using any instance pool by default. Instead, a new EJB instance is created when a thread needs to invoke a method on an EJB. This might be useful if you do not want any limit on the number of EJB instances that are created.

To disable the default bean instance pool, use the following management CLI command:

/subsystem=ejb3:undefine-attribute(name=default-slsb-instance-pool)
Note

If a bean is configured to use a particular bean instance pool, disabling the default instance pool does not affect the pool that the bean uses.

5.2. Bean Thread Pools

By default, a bean thread pool named default is used for asynchronous EJB calls and EJB timers.

Note

From JBoss EAP 7 onward, remote EJB requests are handled in the worker defined in the io subsystem by default.

If required, you can configure each of these EJB services to use a different bean thread pool. This can be useful if you want finer control of each service’s access to a bean thread pool.

When determining an appropriate thread pool size, consider how many concurrent requests you expect will be processed at once.

5.2.1. Creating a Bean Thread Pool

This section shows you how to create a new bean thread pool using the management CLI. You can also configure bean thread pools using the management console by navigating to the EJB 3 subsystem from the Configuration tab and selecting Thread Pools in the left menu.

To create a new thread pool, use the following command:

/subsystem=ejb3/thread-pool=POOL_NAME:add(max-threads=MAX_THREADS)

The following example creates a bean thread pool named my_thread_pool with a maximum of 30 threads:

/subsystem=ejb3/thread-pool=my_thread_pool:add(max-threads=30)

5.2.2. Configuring EJB Services to Use a Specific Bean Thread Pool

The EJB3 asynchronous invocation service and timer service can each be configured to use a specific bean thread pool. By default, both these services use the default bean thread pool.

This section shows you how to configure the above EJB services to use a specific bean thread pool using the management CLI. You can also configure these services using the management console by navigating to the EJB 3 subsystem from the Configuration tab, and then selecting the Services tab.

To configure an EJB service to use a specific bean thread pool, use the following command:

/subsystem=ejb3/service=SERVICE_NAME:write-attribute(name=thread-pool-name,value=THREAD_POOL_NAME)

Replace SERVICE_NAME with the EJB service you want to configure:

  • async for the EJB3 asynchronous invocation service
  • timer-service for the EJB3 timer service

The following example sets the EJB3 async service to use the bean thread pool named my_thread_pool:

/subsystem=ejb3/service=async:write-attribute(name=thread-pool-name,value=my_thread_pool)

5.3. Exceptions That Indicate EJB Subsystem Tuning Might Be Required

  • The Stateless EJB instance pool is not large enough or the timeout is too low

    javax.ejb.EJBException: JBAS014516: Failed to acquire a permit within 20 SECONDS
         at org.jboss.as.ejb3.pool.strictmax.StrictMaxPool.get(StrictMaxPool.java:109)

    See Bean Instance Pools.

  • The EJB thread pool is not large enough, or an EJB is taking longer to process than the invocation timeout

    java.util.concurrent.TimeoutException: No invocation response received in 300000 milliseconds

    See Bean Thread Pools.