Chapter 10. Clustering in Web Applications

download PDF

10.1. Session Replication

10.1.1. About HTTP Session Replication

Session replication ensures that client sessions of distributable applications are not disrupted by failovers of nodes in a cluster. Each node in the cluster shares information about ongoing sessions, and can take them over if the originally-involved node disappears.
Session replication is the mechanism by which mod_cluster, mod_jk, mod_proxy, ISAPI, and NSAPI clusters provide high availability.

10.1.2. About the Web Session Cache

The web session cache can be configured when you use any of the HA profiles, including the standalone-ha.xml profile, or the managed domain profiles ha or full-ha. The most commonly configured elements are the cache mode and the number of cache owners for a distributed cache. The owners parameter works only in the DIST mode.
Cache Mode

The cache mode can either be REPL (the default) or DIST.

The REPL mode replicates the entire cache to every other node in the cluster. This is the safest option, but introduces more overhead.
The DIST mode is similar to the buddy mode provided in previous implementations. It reduces overhead by distributing the cache to the number of nodes specified in the owners parameter. This number of owners defaults to 2.

The owners parameter controls how many cluster nodes hold replicated copies of the session. The default is 2.

10.1.3. Configure the Web Session Cache

The web session cache defaults to REPL. If you wish to use DIST mode, run the following two commands in the Management CLI. If you use a different profile, change the profile name in the commands. If you use a standalone server, remove the /profile=ha portion of the commands.

Procedure 10.1. Configure the Web Session Cache

  1. Change the default cache mode to DIST.

  2. Set the number of owners for a distributed cache.

    The following command sets 5 owners. The default is 2.
  3. Change the default cache mode back to REPL.

  4. Restart the Server

    After changing the web cache mode, you must restart the server.

Your server is configured for session replication. To use session replication in your own applications, refer to the following topic: Section 10.1.4, “Enable Session Replication in Your Application”.

10.1.4. Enable Session Replication in Your Application


To take advantage of JBoss EAP 6 High Availability (HA) features, you must configure your application to be distributable. This procedure shows how to do that, and then explains some of the advanced configuration options you can use.

Procedure 10.2. Make your Application Distributable

  1. Required: Indicate that your application is distributable.

    If your application is not marked as distributable, its sessions will never be distributed. Add the <distributable/> element inside the <web-app> tag of your application's web.xml descriptor file. Here is an example.

    Example 10.1. Minimum Configuration for a Distributable Application

    <?xml version="1.0"?>
    <web-app  xmlns=""
  2. Modify the default replication behavior if desired.

    If you want to change any of the values affecting session replication, you can override them inside a <replication-config> element which is a child element of the <jboss-web> element of your application's jboss-web.xml file. For a given element, only include it if you want to override the defaults. The following example lists all of the default settings, and is followed by a table which explains the most commonly changed options.

    Example 10.2. Example <replication-config>Values

    <!DOCTYPE jboss-web PUBLIC
        "-//JBoss//DTD Web Application 5.0//EN"
Table 10.1. Common Options for Session Replication
Controls which conditions should trigger session data replication across the cluster. This option is necessary because after a mutable object (stored as a session attribute) is accessed from the session, the container has no clear way to know if the object has been modified and needs to be replicated, unless method setAttribute() is called directly.
This is the safest but worst-performing option. Session data is always replicated, even if its content has only been accessed, and not modified. This setting is preserved for legacy purposes only. To get the same behavior with better performance, you may, instead of using this setting, set <max-unreplicated-interval> to 0.
The default value. Session data is only replicated if an object of a non-primitive type is accessed. This means that the object is not of a well-known Java type such as Integer, Long, or String.
This option assumes that the application will explicitly call setAttribute on the session when the data needs to be replicated. It prevents unnecessary replication and can benefit overall performance, but is inherently unsafe.
Regardless of the setting, you can always trigger session replication by calling setAttribute().
Determines the granularity of data that is replicated. It defaults to SESSION, but can be set to ATTRIBUTE instead, to increase performance on sessions where most attributes remain unchanged.
This is only for dirty attributes in the session and for some session data like the last-accessed timestamp.
The default value. The entire session object is replicated if any attribute is dirty. The shared object references are maintained on remote nodes since the entire session is serialized in one unit.


FIELD is not supported in JBoss EAP 6.
The following options rarely need to be changed.
Table 10.2. Less Commonly Changed Options for Session Replication
Whether to assume that a load balancer such as mod_cluster, mod_jk, or mod_proxy is in use. The default is false. If set to true, the container examines the session ID associated with each request and replaces the jvmRoute portion of the session ID if there is a failover.
The maximum interval (in seconds) to wait after a session was accessed before triggering a replication of a session's timestamp, even if it is considered to be unchanged. This ensures that cluster nodes are aware of each session's timestamp and that an unreplicated session will not expire incorrectly during a failover. It also ensures that you can rely on a correct value for calls to method HttpSession.getLastAccessedTime()during a failover.
By default, no value is specified. A value of 0 causes the timestamp to be replicated whenever the session is accessed. A value of -1 causes the timestamp to be replicated only if other activity during the request triggers a replication. A positive value greater than HttpSession.getMaxInactiveInterval() is treated as a misconfiguration and converted to 0.
Specifies when sessions are replicated to other nodes. The default is INSTANT and the other possible value is INTERVAL.
In INSTANT mode, changes are replicated at the end of a request, by means of the request processing thread. The <snapshot-interval> option is ignored.
In INTERVAL mode, a background task runs at the interval specified by <snapshot-interval>, and replicates modified sessions.
The interval, in milliseconds, at which modified sessions should be replicated when using INTERVAL for the value of <snapshot-mode>.
The fully-qualified class name of the implementation of interface ClusteredSessionNotificationPolicy which governs whether servlet specification notifications are emitted to any registered HttpSessionListener, HttpSessionAttributeListener, or HttpSessionBindingListener.
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.