JBoss.org Community Documentation

18.4. Stateful Session Beans in EJB 3.0

To cluster stateful session beans in EJB 3.0, you need to tag the bean implementation class with the @Cluster annotation, just as we did with the EJB 3.0 stateless session bean earlier. The @org.jboss.ejb3.annotation.cache.tree.CacheConfig annotation can also be applied to the bean to specify caching behavior. Below is the definition of the @CacheConfig annotation:

public @interface CacheConfig
String name() default "jboss.cache:service=EJB3SFSBClusteredCache";
int maxSize() default 10000;
long idleTimeoutSeconds() default 300;   
boolean replicationIsPassivation() default true;   
long removalTimeoutSeconds() default 0;
  • name specifies the object name of the JBoss Cache Mbean that should be used for caching the bean (see below for more on this Mbean).

  • maxSize specifies the maximum number of beans that can cached before the cache should start passivating beans, using an LRU algorithm.

  • idleTimeoutSeconds specifies the max period of time a bean can go unused before the cache should passivate it (irregardless of whether maxSize beans are cached.)

  • removalTimeoutSeconds specifies the max period of time a bean can go unused before the cache should remove it altogether.

  • replicationIsPassivation specifies whether the cache should consider a replication as being equivalent to a passivation, and invoke any @PrePassivate and @PostActivate callbacks on the bean. By default true, since replication involves serializing the bean, and preparing for and recovering from serialization is a common reason for implementing the callback methods.

Here is an example of a clustered EJB 3.0 stateful session bean implementation.

public class MyBean implements MySessionInt {
   private int state = 0;

   public void increment() {
      System.out.println("counter: " + (state++));

As with stateless beans, the @Clustered annotation can also be omitted and the clustering configuration applied in jboss.xml; see the example above.

As with EJB 2.0 clustered SFSBs, JBoss provides a mechanism whereby a bean implementation can expose a method the container can invoke to check whether the bean's state is not dirty after a request and doesn't need to be replicated. With EJB3, the mechanism is a little more formal; instead of just exposing a method with a known signature, an EJB3 SFSB must implement the org.jboss.ejb3.cache.Optimized interface:

public interface Optimized {
boolean isModified();

JBoss Cache provides the session state replication service for EJB 3.0 stateful session beans. The related MBean service is defined in the ejb3-clustered-sfsbcache-service.xml file in the deploy directory. The contents of the file are as follows.

	<mbean code="org.jboss..cache.TreeCache"
		<attribute name="ClusterName">
			<attribute name="IsolationLevel">REPEATABLE_READ</attribute>
			<attribute name="CacheMode">REPL_ASYNC</attribute> 
			<!-- We want to activate/inactivate regions as beans are deployed --> 
			 <attribute name="UseRegionBasedMarshalling">true</attribute> 
			<!-- Must match the value of "useRegionBasedMarshalling" --> 
			<attribute name="InactiveOnStartup">true</attribute>
			<attribute name="ClusterConfig">
			... ...
			<!-- The max amount of time (in milliseconds) we wait until the 
			initial state (ie. the contents of the cache) are retrieved from 
			existing members.  --> 
			<attribute name="InitialStateRetrievalTimeout">17500</attribute>
			<!--  Number of milliseconds to wait until all responses for a
				synchronous call have been received.
			<attribute name="SyncReplTimeout">17500</attribute>
			<!--  Max number of milliseconds to wait for a lock acquisition -->
			<attribute name="LockAcquisitionTimeout">15000</attribute>
			 <!--  Name of the eviction policy class. -->
			<attribute name="EvictionPolicyClass">
			<!--  Specific eviction policy configurations. This is LRU -->
			<attribute name="EvictionPolicyConfig">
				<attribute name="wakeUpIntervalSeconds">5</attribute>
				<!-- So default region would never timeout -->
				<region name="/_default_">
				<attribute name="maxNodes">0</attribute>
				 <attribute name="timeToIdleSeconds">0</attribute>
	<!-- Store passivated sessions to the file system --> 
	 <attribute name="CacheLoaderConfiguration"> 
		<!-- Passivate to the server data dir --> 

The configuration attributes in this MBean are essentially the same as the attributes in the standard JBoss Cache TreeCache MBean discussed in Chapter 22, JBossCache and JGroups Services . Again, we omitted the JGroups configurations in the ClusterConfig attribute (see more in Section 22.1, “JGroups Configuration”). Two noteworthy items: