JBoss.org Community Documentation

Chapter 1. Session EJB and MDB Configuration

Both Stateless Session beans and Message Driven Beans have an instance pool. The basic configuration of JBoss uses a thread local pool to avoid Java synchronization (org.jboss.ejb3.pool.ThreadLocalPool). These EJB types can be configured to use an alternative pooling mechanism. For example, JBoss has a strict pool size implementation that will only allow a fixed number of concurrent requests to run at one time. If there are more requests running than the pool's strict size, those requests will block until an instance becomes available. This is configured via the @org.jboss.ejb3.annotation.Pool annotation.

public @interface Pool {
   String value() default PoolDefaults.POOL_IMPLEMENTATION_THREADLOCAL;

   int maxSize() default PoolDefaults.DEFAULT_POOL_SIZE;

   long timeout() default Long.MAX_VALUE;


The value() parameter defines the pool factory name you want to plug in. maxSize() defines the size of the pool while timeout() is a time in milliseconds you want to block when waiting for an instance to be ready. This annotation can be applied to a stateless or message driven bean class. Here's an example of using it:

import org.jboss.ejb3.annotation.Pool;
import org.jboss.ejb3.annotation.defaults.PoolDefaults;

@Pool (value=PoolDefaults.POOL_IMPLEMENTATION_STRICTMAX,maxSize=5,timeout=1000)
public class StrictlyPooledSessionBean implements StrictlyPooledSession

There is no nice way of applying the same configuration through XML. To do it through XML you must define a new aspect domain (an EJB container configuration template) and define an annotation override within that domain and then apply the domain through jboss.xml. Here's an example:

First create the aspect domain. Create a file called mydomain-aop.xml and put this in the META-INF directory of your EJB jar. Might seem a little cryptic but what this is doing is declaring an annotation that will be created by the EJB container. Our EJB3 implementation is based on JBoss AOP. See the JBoss AOP documentation for more info on annotation overrides.

<?xml version="1.0" encoding="UTF-8"?>
<aop xmlns="urn:jboss:aop-beans:1.0">
   <domain name="Strictly Pooled Stateless Bean" extends="Stateless Bean" inheritBindings="true">
      <annotation expr="!class(@org.jboss.ejb3.annotation.Pool)">
          @org.jboss.ejb3.annotation.Pool (value="StrictMaxPool", maxSize=5, timeout=10000)
   <domain name="Strictly Pooled Message Driven Bean" extends="Message Driven Bean" inheritBindings="true">
      <annotation expr="!class(@org.jboss.ejb3.annotation.Pool)">
          @org.jboss.ejb3.annotation.Pool (value="StrictMaxPool", maxSize=5, timeout=10000)


The next thing you have to do is apply this custom aspect domain to your EJB within a jboss.xml file in the META-INF directory.

<?xml version="1.0" encoding="utf-8"?>
<jboss xmlns:xs="http://www.jboss.org/j2ee/schema"
       xs:schemaLocation="http://www.jboss.org/j2ee/schema jboss_5_0.xsd"

         <aop-domain-name>Strictly Pooled Message Driven Bean</aop-domain-name>


Stateful Session Bean Cache

Stateful beans are stored in a cache. This cache is responsible for passivating stateful sessions when the cache becomes too full or a bean is too old. You may want to set things like the max size of this cache, and when beans should become idle. Cache can be configured using the org.jboss.ejb3.annotation.CacheConfig annotation.

@CacheConfig(maxSize = 1000, idleTimeoutSeconds = 1)
public class MyStatefulBean implements MyBean


If you want an XML version of configuring this, you must do a similar pattern as shown in the pooling section above. You must create an aspect domain through XML and apply that domain through XML.

Disable Passivation of SFSB :

Sometimes it is useful to turn off passivation entirely. This can be done by specifying the maxSize=0 and idleTimeoutSeconds=0 through the @CacheConfig :

@CacheConfig(maxSize = 0, idleTimeoutSeconds = 0)
public class NonPassivatedStatefulBean implements MyBean