21.2. Configuring HTTP session state replication

The preceding discussion has been focused on using mod_jk as a load balancer. The following information about clustering HTTP services in JBoss Enterprise Web Platform applies regardless of the load balancer used.

In Section 21.1.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, sticky sessions by themselves are not an ideal solution. If a node goes down, all its session data is lost. A more reliable solution is to replicate session data across the nodes in the cluster. This way, if a server node fails or is shut down, the load balancer can fail over the next client request to any server node and obtain the same session state.

21.2.1. Enabling session replication in your application

To enable replication of your web application you must tag the application as distributable in the web.xml descriptor. Here's an example:

<?xml version="1.0"?> 
<web-app  xmlns="http://java.sun.com/xml/ns/j2ee"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
                              http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" 
          version="2.4">
          
    <distributable/>
    
</web-app>

You can futher configure session replication using the replication-config element in the jboss-web.xml file. However, the replication-config element only needs to be set if one or more of the default values described below is unacceptable. Here is an example:

<!DOCTYPE jboss-web PUBLIC
    -//JBoss//DTD Web Application 5.0//EN
    http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd>

<jboss-web>
   
   <replication-config>
      <cache-name>custom-session-cache</cache-name>
      <replication-trigger>SET</replication-trigger>
      <replication-granularity>ATTRIBUTE</replication-granularity>
      <replication-field-batch-mode>true</replication-field-batch-mode>
      <use-jk>false</use-jk>
      <max-unreplicated-interval>30</max-unreplicated-interval>
      <snapshot-mode>INSTANT</snapshot-mode>
      <snapshot-interval>1000</snapshot-interval>
      <session-notification-policy>com.example.CustomSessionNotificationPolicy</session-notification-policy>
   </replication-config>

</jboss-web>

All of the above configuration elements are optional and can be ommitted if the default value is acceptable. A couple are commonly used; the rest are very infrequently changed from the defaults. We'll cover the commonly used ones first.

The replication-trigger element determines when the container should consider that session data must be replicated across the cluster. The rationale for this setting is that after a mutable object stored as a session attribute is accessed from the session, in the absence of a setAttribute call the container has no clear way to know if the object (and hence the session state) has been modified and needs to be replicated. This element has three valid values:

SET_AND_GET: Always replicates session data, even if its content has not been modified but simply accessed. This previously ensured that every request triggered a timestamp. Since setting max_unreplicated_interval to 0 accomplishes the same thing at much lower cost, using SET_AND_GET is not sensible with Enterprise Web Platform 5.
SET_AND_NON_PRIMITIVE_GET: Only replicates if an object of a non-primitive type has been accessed (that is, the object is not of a well-known immutable JDK type, such as Integer, Long, String, etc.) This is the default value.
SET: Assumes that the developer will explicitly call setAttribute on the session if the data needs to be replicated. This setting prevents unnecessary replication and can have major performance benefits, but requires very good coding practices to ensure that setAttribute is always called whenever a mutable object stored in the session is modified.

In all cases, calling setAttribute marks the session as needing replication.

The replication-granularity element determines the granularity of what gets replicated if the container determines session replication is needed. The supported values are:

SESSION: Indicates that the entire session attribute map should be replicated when any attribute is considered modified. Replication occurs at request end. This option replicates the most data and thus incurs the highest replication cost, but since all attributes values are always replicated together it ensures that any references between attribute values will not be broken when the session is deserialized. For this reason it is the default setting.
ATTRIBUTE: Indicates that only attributes that the session considers to be potentially modified are replicated. Replication occurs at request end. For sessions carrying large amounts of data, parts of which are infrequently updated, this option can significantly increase replication performance. However, it is not suitable for applications that store objects in different attributes that share references with each other (for example, a Person object in the husband attribute sharing a reference to an Address object with another Person in the wife attribute). This is because if the attributes are separately replicated, when the session is deserialized on remote nodes the shared references will be broken.
FIELD: Useful if the classes stored in the session have been bytecode enhanced for use by POJO Cache. If they have been, the session management layer will detect field level changes within objects stored to the session, and will replicate only those changes. This is the most performant setting. Replication is only for individual changed data fields inside session attribute objects. Shared object references will be preserved across the cluster. Potentially most performant, but requires changes to your application (this will be discussed later).

The other elements under the replication-config element are much less frequently used.

cacheName: Indicates the name of the JBoss Cache configuration that should be used for storing distributable sessions and replicating them around the cluster. This element lets web applications that require different caching characteristics specify the use of separate, differently configured, JBoss Cache instances. The default value is standard-session-cache if the replication-granularity is not FIELD, and field-granularity-session-cache if it is. See Section 21.2.3, “Configuring the JBoss Cache instance used for session state replication” for more details on JBoss Cache configuration for web tier clustering.
replication-field-batch-mode: Indicates whether all replication messages associated with a request will be batched into one message. This is applicable only if replication-granularity is FIELD. If replication-field-batch-mode is set to true, fine-grained changes made to objects stored in the session attribute map will replicate only when the HTTP request is finished; otherwise they replicate as they occur. Setting this to false is not advised. The default value is true.
useJK: Indicates whether the container should assume that a JK-based software load balancer (for example, mod_jk, mod_proxy, mod_cluster) is being used for load balancing for this web application. If set to true, the container will examine the session ID associated with every request and replace the jvmRoute portion of the session ID if it detects a failover.
The default value is null (that is, unspecified). In this case the session manager will use the presence or absence of a jvmRoute configuration on its enclosing JBoss Web Engine (see Section 21.1.4, “Configuring JBoss to work with mod_jk”) to determine whether JK is used. useJK need only be set to false for web applications whose URL cannot be handled by the JK load balancer.
max-unreplicated-interval: Configures the maximum interval between requests, in seconds, after which a request will trigger replication of the session's timestamp regardless of whether the request has otherwise made the session dirty. Such replication ensures that other nodes in the cluster are aware of the most recent value for the session's timestamp and won't incorrectly expire an unreplicated session upon failover. It also results in correct values for HttpSession.getLastAccessedTime() calls following failover.
A value of 0 means the timestamp will be replicated whenever the session is accessed. A value of -1 means the timestamp will be replicated only if some other activity during the request (for example, modifying an attribute) has resulted in other replication work involving the session. A positive value greater than the HttpSession.getMaxInactiveInterval() value will be treated as a probable misconfiguration and converted to 0; that is, metadata will be replicated on every request. The default value is 60.
snapshot-mode: Configures when sessions are replicated to the other nodes. Possible values are INSTANT (the default) and INTERVAL.
The typical value, INSTANT, replicates changes to the other nodes at the end of requests, using the request processing thread to perform the replication. In this case, the snapshot-interval property is ignored.
With INTERVAL mode, a background task is created that runs every snapshot-interval milliseconds, checking for modified sessions and replicating them.
Note that this property has no effect if replication-granularity is set to FIELD. If it is FIELD, INSTANT mode will be used.
snapshot-interval: Defines how often (in milliseconds) the background task that replicates modified sessions should be started for this web application. Only meaningful if snapshot-mode is set to INTERVAL.
session-notification-policy: Specifies the fully qualified class name of the implementation of the ClusteredSessionNotificationPolicy interface that should be used to govern whether servlet specification notifications should be emitted to any registered HttpSessionListener, HttpSessionAttributeListener or HttpSessionBindingListener.
Sensible event notifications for a non-clustered environment may not remain sensible in a clustered environment. (See https://jira.jboss.org/jira/browse/JBAS-5778 for an example of why a notification may not be desired.) Configuring an appropriate ClusteredSessionNotificationPolicy gives the application author fine-grained control over what notifications are issued.
If no value is explicitly set, the default behavior is IgnoreUndeployLegacyClusteredSessionNotificationPolicy, which implements the same behavior except during undeployment, during which no HttpSessionListener and HttpSessionAttributeListener notifications are sent.