20.6. Configuring HTTP session state replication

The preceding discussion has been focused on using mod_jk as a load balancer. The content of the remainder our discussion of clustering HTTP services in JBoss AS applies no matter what load balancer is used.

In Section 20.4, “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, sticky sessions by themselves are not an ideal solution. 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. This MBean is defined in the deploy/jboss-web-cluster.sar/META-INF/jboss-service.xml file.

Note

Before AS 4.2.0, the location of the HTTP session cache configuration file was deploy/tc5-cluster.sar/META-INF/jboss-service.xml. Prior to AS 4.0.4 CR2, the file was named deploy/tc5-cluster-service.xml.

Below is a typical deploy/jbossweb-cluster.sar/META-INF/jboss-service.xml file. The configuration attributes in the TomcatClusteringCache MBean are very similar to those in the JBoss AS cache 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>
    <attribute name="SyncReplTimeout">20000</attribute>
</mbean>

Note that the value of the mbean element's code attribute is org.jboss.cache.aop.TreeCacheAop, which is different from the other JBoss Cache Mbeans used in JBoss AS. This is because FIELD granularity HTTP session replication (covered below) needs the added features of the TreeCacheAop (a.k.a. PojoCache) class.

The details of all the configuration options for a TreeCache MBean are covered in the JBoss Cache documentation. 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 transactions. Please do not change this.
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 the the word "Tomcat-" appended by the current JBoss partition name. All the nodes must use the same 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. Please refer to Section 22.1, “JGroups Configuration” for more information.
LockAcquisitionTimeout sets the maximum number of milliseconds to wait for a lock acquisition when trying to lock a cache node. The default value is 15000.
SyncReplTimeout sets the maximum number of milliseconds to wait for a response from all nodes in the cluster when a synchronous replication message is sent out. The default value is 20000; should be a few seconds longer than LockAcquisitionTimeout.