Chapter 17. HTTP session state replication

HTTP session state replication is a means of distributing clients' state across multiple servers. The following terms are important in understanding load balancing. Refer to the Clustering Guide part of the Administration and Configuration Guide for details of associated JBoss Enterprise Application Platform high availability options.
Software Load Balancer

A dedicated software-based service designed to distribute HTTP client session requests across multiple computer servers (cluster). The primary directive of a software load balancer is to maximize resource utilization, reduce request response times, and prevent server overload. The load balancer forwards client session requests to a server cluster, based on server load and availability.

Client Session

A semi-permanent connection between the client (an application) and the server. The load balancer determines whether the client session is created with persistence, or whether a client session is redistributed based on server load and availability.

Session Persistence

Session persistence is a feature where information about a client's session is stored by the server so that if the client's connection is interrupted temporarily, the session can continue at the time the connection error occurred. A persistent session is also commonly known as a sticky session .

Sticky Session

See Session Persistence.

Section 3.1, “Configure worker nodes in mod_jk” describes how to configure session state persistence in the load balancer to ensure a client in a session is always routed to the same server node.
Session persistence on its own is not a best-practice solution because if a server fails, all session state data is lost. For example, if a customer is about to make a purchase on a web site, and the server hosting the shopping cart instance fails, session state data associated with the cart is lost permanently.
One way of preventing client session data loss is to replicate session data across the servers in the cluster. 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.
Using a load balancer that supports session persistence, but not configuring web applications for session replication, allows you to scale your implementation by avoiding the cost of session state replication: each request for a session will always be handled by the same node.
Session state replication is more expensive than basic session persistence, but the reliability it provides for session state data makes it important when creating a load balanced cluster.

17.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=""
You can further 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. All of the configuration elements are optional, and can be omitted if the default value is acceptable.
Here is an example:
<!DOCTYPE jboss-web PUBLIC
    "-//JBoss//DTD Web Application 5.0//EN"


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 3 valid values:
SET_AND_GET is conservative but not optimal (performance-wise): it will always replicate session data even if its content has only been accessed and not modified. This setting made (a little) sense in JBoss Enterprise Application Platform 4 since using it was a way to ensure that every request triggered replication of the session's timestamp. Since setting max_unreplicated_interval to 0 accomplishes the same thing at much lower cost, using SET_AND_GET makes no sense with JBoss Enterprise Application Platform 5 or JBoss Enterprise Web Platform 5.
SET_AND_NON_PRIMITIVE_GET is conservative but will only replicate if an object of a non-primitive type has been accessed (in effect, 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 a major beneficial impact on performance, but requires very good coding practices to ensure 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.
Specifies 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. In JBoss Enterprise Application Platform 4 the cache to use was a server-wide configuration that could not be changed per web application. The default value is standard-session-cache. See Section 17.3, “Configure the JBoss Cache instance used for session state replication” for more details on JBoss Cache configuration for web-tier clustering.
Specifies 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 because it increases the number of replication requests and the chance of session state being out of sync. Default is true.


The FIELD granularity option is now deprecated as JBoss Cache, which provides this feature, is to be subsituted by Infinispan (Infinispan does not support this granularity).
Specifies 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.
You need only set this to false for web applications whose URL cannot be handled by the JK load balancer.
Specifies 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 will not incorrectly expire an unreplicated session upon failover. It also results in correct values for HttpSession.getLastAccessedTime() calls following failover.
The default value is null (in effect, 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 3.2, “Configuring JBoss to work with mod_jk”) to determine whether JK is used.
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 probable misconfiguration and converted to 0; (in effect, replicate the metadata on every request). Default value is 60.
Specifies 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.
Specifies 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.
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 and/or HttpSessionBindingListener.


Event notifications that may be appropriate in non-clustered environment may not necessarily be appropriate in a clustered environment; see 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.