1.5.5. Configure HTTP session state replication

In Section 1.5.3, “Configure worker nodes in mod_jk”, we covered how to use sticky sessions to make sure that a client in a session always hits the same server node in order to maintain the session state. However, that is not an ideal solution. The load might be unevenly distributed over the nodes over time and if a node goes down, all its session data is lost. A better and more reliable solution is to replicate session data across all nodes in the cluster. This way, the client can hit any server node and obtain the same session states.

The jboss.cache:service=TomcatClusteringCache MBean makes use of JBoss Cache to provide HTTP session replication service to the HTTP load balancer in a JBoss Tomcat cluster. This MBean is defined in the deploy/tc5-cluster.sar/META-INF/jboss-service.xml file.

Note

Before AS 4.0.4 CR2, the HTTP session cache configuration file is the deploy/tc5-cluster-service.xml file. Please see AS 4.0.3 documentation for more details.

Below is a typical deploy/tc5-cluster.sar/META-INF/jboss-service.xml file. The configuration attributes in the TomcatClusteringCache MBean is very similar to those in Section 2.2, “JBossCache Configuration”.

<mbean code="org.jboss.cache.aop.TreeCacheAop"
    name="jboss.cache:service=TomcatClusteringCache">

    <depends>jboss:service=Naming</depends>
    <depends>jboss:service=TransactionManager</depends>
    <depends>jboss.aop:service=AspectDeployer</depends>

    <attribute name="TransactionManagerLookupClass">
        org.jboss.cache.BatchModeTransactionManagerLookup
    </attribute>
    
    <attribute name="IsolationLevel">REPEATABLE_READ</attribute>
    
    <attribute name="CacheMode">REPL_ASYNC</attribute>
    
    <attribute name="ClusterName">
      Tomcat-${jboss.partition.name:Cluster}
    </attribute>
    
    <attribute name="UseMarshalling">false</attribute>
    
    <attribute name="InactiveOnStartup">false</attribute>
    
    <attribute name="ClusterConfig">
        ... ...
    </attribute>
    
    <attribute name="LockAcquisitionTimeout">15000</attribute>
</mbean>

The detailed configuration for the TreeCache MBean is covered in Section 2.2, “JBossCache Configuration”. Below, we will just discuss several attributes that are most relevant to the HTTP cluster session replication.

TransactionManagerLookupClass sets the transaction manager factory. The default value is org.jboss.cache.BatchModeTransactionManagerLookup. It tells the cache NOT to participate in JTA-specific transactions. Instead, the cache manages its own transaction to support finely grained replications.
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, which determine whether changes are made synchronously or asynchronously. Using synchronous replication makes sure changes propagated to the cluster before the web request completes. However, synchronous replication is much slower. For asyncrhonous access, you will want to enable and tune the replication queue.
ClusterName specifies the name of the cluster that the cache works within. The default cluster name is the the word "Tomcat-" appended by the current JBoss partition name. All the nodes should use the same cluster name. Although session replication can share the same channel (multicast address and port) with other clustered services in JBoss, replication should have it's own cluster name.
The UseMarshalling and InactiveOnStartup attributes must have the same value. They must be true if FIELD level session replication is needed (see later). Otherwise, they are default to false.
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. These values should make sense for your network. Please refer to Section 2.1, “JGroups Configuration” for more information.
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.