HTTP session replication is used to replicate the state associated with your web clients on other nodes of a cluster. Thus, in the event one of your node crashes, another node in the cluster will be able to recover.

Mod_JK is used to configure the default load balancing behaviour:

# Load-balancing behaviour

In this sample sticky session are enabled : mod_jk forwards requests in the same web session to the same JBoss AS node. The sticky session ensures that the user is always served by the JBoss AS instance that has the correct session state. Sticky session can be used for a simple cluster setup.

However if a node goes down, all its session data is lost. A better and more reliable solution is to replicate session data across the nodes in the cluster. This way, the client can hit any server node and obtain the same session state.

The jboss.cache:service=TomcatClusteringCache MBean makes use of JBoss Cache to provide HTTP session replication services to the JBoss Tomcat cluster. 

Where is the HTTP Session configuration file ?

This deserves a small table, since the configuration file is different among JBoss releases:

Before AS 4.0.4

Before AS 4.2.0 deploy/tc5-cluster.sar/META-INF/jboss-service.xml
From   AS 4.2.0 deploy/jboss-web-cluster.sar/META-INF/jboss-service.xml

A typical configuration:

<mbean code="org.jboss.cache.TreeCache"


 <attribute name="TransactionManagerLookupClass">
 <attribute name="IsolationLevel">REPEATABLE_READ</attribute>
 <attribute name="CacheMode">REPL_ASYNC</attribute>
 <attribute name="ClusterName">Tomcat-Cluster</attribute>
 <attribute name="ClusterConfig">
 ... ...
 <attribute name="LockAcquisitionTimeout">15000</attribute>

This is a sample configuration for Jboss Cache HTTP Session replication : the critical attributes for configuring HttpSession replication are:

IsolationLevel sets the isolation level for updates to the transactional distributed cache. The valid values are SERIALIZABLE, REPEATABLE_READ, READ_COMMITTED, READ_UNCOMMITTED, and NONE. These isolation levels mean the same thing as isolation levels on the database. The default isolation of REPEATABLE_READ makes sense for most web applications.

CacheMode controls how the cache is replicated. The valid values are REPL_SYNC and REPL_ASYNC. With either setting the client request thread updates the local cache with the current sesssion contents and then sends a message to the caches on the other members of the cluster, telling them to make the same change. With REPL_ASYNC (the default) the request thread returns as soon as the update message has been put on the network. With REPL_SYNC, the request thread blocks until it gets a reply message from all cluster members, informing it that the update was successfully applied. Using synchronous replication makes sure changes are applied aroundthe cluster before the web request completes. However, synchronous replication is much slower.

ClusterName specifies the name of the cluster that the cache works within. The default cluster name is Tomcat-Cluster.

ClusterConfig configures the underlying JGroups stack. The most import configuration elements are the muliticast adress and port, mcast_addr and mcast_port respectively, to use for clustered communication.

LockAcquisitionTimeout sets the maximum number of milliseconds to wait for a lock acquisition. The default value is 15000.

UseReplQueue determines whether to enable the replication queue when using asynchronous replication. This allows multiple cache updates to be bundled together to improve performance. The replication queue properties are controlled by the ReplQueueInterval and ReplQueueMaxElements properties.

ReplQueueInterval specifies the time in milliseconds JBoss Cache will wait before sending items in the replication queue.

ReplQueueMaxElements: specifies the maximum number of elements allowed in the replication queue before JBoss Cache will send an update.

How to enable HTTP Session replication for my application ?

Enabling Session replication for your web application is trivial: simply add the tag <distributable /> to your web.xml :

<?xml version="1.0"?> 
<web-app  xmlns=""

How can I fine-tune HTTP Session replication ?

You can add the replication-config tag in your jboss-web.xml file.


Where is jboss-web.xml file ? It sits in the WEB-INF folder of your web application. (At the same level of web.xml)

Configuring the replication trigger: there are 4 possible levels of replication of your session data: each one triggers the session replication between nodes in a different way: 

Level Description Speed
SET This is the best option for performance. The session is replicated only if an attributed is explicity modified with setAttribute method. good
SET_AND_GET With this option any attributed that is get/set is marked as dirty even if it's not written back to the session. This leads to a significant performance degradation. slow
This is the default option. It works the same as SET_AND_GET except for primitive system types (String, Integer, Long). Since they are immutable objects they are not replicated when a get is issued. average
ACCESS This is the most conservative option. It causes the session to be marked as dirty whenever it is accessed. Since a the session is accessed during each HTTP request, it will be replicated with each request. Note that use of this option can have a significant performance impact, so use it with caution v.slow

In the following table you can see a set of commands and whether they make the session dirty.

HttpSession session; NO NO NO YES
String s = (String)session.getAttribute("x"); NO NO YES YES
Person p = (String)session.getAttribute("p"); NO YES YES YES
Person p = (String)session.getAttribute("p");

Configuring the replication granularity

The replication-granularity element controls the size of the replication units. The supported values are:

attribute: Replication is only for the dirty attributes in the session plus some session data, like the last-accessed timestamp. 

session: The entire session object is replicated if any attribute is dirty. The entire session is serialized in one unit, so shared object references are maintained on remote nodes. This is the default setting.

field: Replication is only for individual changed data fields inside session attribute objects. Shared object references will be preserved across the cluster.

If your sessions are generally small, SESSION is the better policy. If your session is larger and some parts are infrequently accessed, ATTRIBUTE replication will be more effective. If your application has very big data objects in session attributes and only fields in those objects are frequently modified, the FIELD policy would be the best

How to use the Field session replication

Field replication can be very useful if you want to replicate only single fields of a Class. This way, you'll boost performance because you are sending only small data around the network.

Subsription subs = (Subscription)session.getAttribute(“subscription”);
// What if list is size of 100K?
List mailingList = (List)subs.getMailingList();
Person joe = findSubsriber(“joe”);
joe.setZip(94086); // Only replicates this field!

You need to do some modification to your code: for this purpose you need to "mark" the classes which are used with field replication with the following annotation (JDK 1.5 is assumed ):

public class Person

You can use as an alternative the following Annotation which automatically extends the annotation to all subclasses:

public class Person

Then once you have added all annotations needed, you need to issue the aopc command which is a post-compilation task :


aopc [classpath] [class files or directories]					


Additional resources on this site:

If you need to monitor Session HTTP Replication take a look at this article
If you want to know how big is the HTTP Session being replicated read this short how to


Related articles available on

JBoss Clustering a Web Application

Please Note: This article cover JBoss AS 4/5/6 releases. If you w

Clustering EJB 3 with JBoss AS

To cluster a stateless session bean in EJB 3 all you need to do i

JBoss monitoring HTTP Session replication

In this article we'll show how to monitor HTTPSession replication

How do I change multicast address of JBoss cluster ?

Since JBoss AS 4.0.3, the jboss.partition.udpGroup property can b

JBoss farming service

What is the farming service ? this article explains about it, als

How do I know the Http Session replication size?

You need to add the <SIZE /> tag into your Cluster configur