Chapter 8. Clustering in Web Applications

8.1. Session Replication

8.1.1. About HTTP Session Replication

Session replication ensures that client sessions of distributable applications are not disrupted by failovers by 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.

8.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.
Cache Mode

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

REPL
The REPL mode replicates the entire cache to every other node in the cluster. This is the safest option, but introduces more overhead.
DIST
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.
Owners

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

8.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 8.1. Configure the Web Session Cache

  1. Change the default cache mode to DIST.

    /profile=ha/subsystem=infinispan/cache-container=web/:write-attribute(name=default-cache,value=dist)
    
  2. Set the number of owners for a distributed cache.

    The following command sets 5 owners. The default is 2.
    /profile=ha/subsystem=infinispan/cache-container=web/distributed-cache=dist/:write-attribute(name=owners,value=5)
    
  3. Change the default cache mode back to REPL.

    /profile=ha/subsystem=infinispan/cache-container=web/:write-attribute(name=default-cache,value=repl)
    
  4. Restart the Server

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

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

8.1.4. Enable Session Replication in Your Application

Summary

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 8.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 8.1. Minimum Configuration for a Distributable Application

    <?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>
    				
    
    
  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. 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 8.2. Default <replication-config>Values

    <!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>
          <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>
    				
    
    

Table 8.1. Common Options for session Replication

Option
Description
<replication-trigger>
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.

Valid Values for <replication-trigger>

SET_AND_GET
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.
SET_AND_NON_PRIMITIVE_GET
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.
SET
This option assumes that the application will explicitly call setAttributeon 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().
<replication-granularity>
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.
The following options rarely need to be changed.

Table 8.2. Less Commonly Changed Options for Session Replication

Option
Description
<useJK>
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 jvmRouteportion of the session ID if there is a failover.
<max-unreplicated-interval>
The maximum interval (in seconds) to wait after a session 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. This means that the jvmRoute configuration of the container determines whether JK failover is being used. 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.
<snapshot-mode>
Specifies when sessions are replicated to other nodes. The default is INSTANTand 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.
<snapshot-interval>
The interval, in milliseconds, at which modified sessions should be replicated when using INTERVALfor the value of <snapshot-mode>.
<session-notification-policy>
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.