Chapter 18. High-Availability Web Sessions

JBoss Enterprise Application Server allows you to make web sessions highly available by storing them in a database table.

Important

HTTP session replication with JBoss Cache is the preferred approach to securing web session failover. It is strongly recommended to use this approach if possible (refer to Chapter 17, HTTP session state replication).
To provide high availability web sessions, you can configure JBoss Application Server to store the web session state in a database table. If the server then becomes unavailable, the web session state is still preserved in the database table and can be used by failover servers, while if using session replication, the web session is available on the server and the respective failover nodes. The high availability web session setup can be useful in a WAN with several application server instance or in combination with session replication.
To make web sessions highly available, you need to do the following:
  • configure the server to use the session manager set on your web application (JBoss Application Server by default ignores the web application session manager and switches to JBossCacheManager automatically);
  • configure your web applications to use DataSourcePersistentManager as their session manager (the manager handles the storing of web sessions to the defined database table);
  • create the web session table in the target database and deploy the datasource, which will provide the connection between the session manager and the database table.

Configuring JBoss Enterprise Application Server

To configure JBoss Enterprise Application Server to allow storing of sessions in a database, disable overriding of the session manager set on your web application (overriden to JBossCacheManager; this allows the web application to use its own session manager):
  1. Open the JBOSS_HOME/server/PROFILE/deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml file for editing.
  2. Set the overrideDistributableManager property of the WarDeployer bean to false: 
    <bean name="WarDeployer" class="org.jboss.web.tomcat.service.deployers.TomcatDeployer">

    . . .

    <!-- "False" disables overriding the session manager for distributable webapps -->
    <property name="overrideDistributableManager">false</property>

</bean>

Configuring Web Application

Configure your web application to use the database persistent session manager:
  1. In the application's WEB-INF directory, create the context.xml file, which will define what session manager is to be used as well as the manager's attributes.

    Important

    Note that it is not recommended to add the manager definition to the jboss-web.xml file, although it is the standard web application deployment descriptor. The goal of using the context.xml file instead is to avoid any unnecessary changes to the existing JBoss Application Server code.
  2. In the context.xml file, add the Manager element and its attributes:
    className
    fully-qualified class name of the session manager implementation
    dataSourceJndiName
    datasource that allows the session manager to communicate with the database that stores the web sessions 
    <Context cookies="true" crossContext="true">

   <Manager className="org.jboss.web.tomcat.service.session.persistent.DataSourcePersistentManager"
            dataSourceJndiName="java:HttpSessionDS"/>
   
:</Context>

    Note

    The className and dataSourceJndiName are compulsory attributes. You can also define further Context and Manager attributes (refer to Section 18.1, “DataSourcePersistentManager Configuration Attributes”.

Configuring Database and Datasource

Create the database session table, which will hold the web session data and then create the respective datasource:
  1. Create the web session ( httpsessions ) database table:
    You can change the name of the table and of the columns; however, make sure to configure the DataSourcePersistentManager attributes appropriately.
    Individual columns must be able to store values of particular datatypes:
    • creationtime and lastaccess : java long values
    • maxinactive and version : java int value
    • metadata : serialized java objects (currently not used)
    • attributes : serialized java objects (stores the session attributes map; should be large enough to store your largest sessions)
    • primary key : synthetic primary key (optional, make sure there is a UNIQUE INDEX on app + id).
    The following command creates the table with default settings in the most common databases (MySQL, IBM DB2, Oracle Database): 
    CREATE TABLE httpsessions (app VARCHAR(255) NOT NULL, id VARCHAR(255) NOT NULL, 
     fullId VARCHAR(255) NOT NULL, creationtime BIGINT NOT NULL, 
     maxinactive BIGINT NOT NULL, version INT NOT NULL, lastaccess BIGINT NOT NULL, 
     isnew CHAR(1) NOT NULL, valid CHAR(1) NOT NULL, metadata VARBINARY NULL, 
     attributes LONGVARBINARY NOT NULL, 
     CONSTRAINT app_id PRIMARY KEY (app, id))
  2. Deploy an appropriate datasource to allow the DataSourcePersistentManager to communicate with the database (refer to the chapter on Datasource Configuration in the Administration and Configuration Guide. Make sure the datasource is set up as local-tx-datasource (xa-datasources are not supported).
  3. Add the dataSourceJndiName with the jndi-name of the created datasource to DataSourcePersistentManager element in the context.xml file.

18.1. DataSourcePersistentManager Configuration Attributes

The DataSourcePersistentManager element must define the className and dataSourceJndiName attributes. Apart from these, it can define other properties to specify manager's behavior and the way it interacts with the database.

Compulsory Properties

className
fully-qualified class name of the org.apache.catalina.Manager implementation (that is, org.jboss.web.tomcat.service.session.persistent.DataSourcePersistentManager)
dataSourceJndiName
JNDI name of the data source, which defines the database connection to the httpsessions

Properties Defining the Database Connection Properties

connectionName
value of the username parameter to pass to the DataSource.getConnection method (if null, the getConnection with no arguments is called)
connectionPassword
password to pass to DataSource.getConnection
sessionTable
name of the database session table in which sessions are stored (by default httpsessions)
sessionAppCol
name of the column with the web application name associated with the session (by default app)
sessionIdCol
name of the column with the core, immutable part of a session ID (by default id; this and the sessionAppCol columns form the unique index for the table)
sessionFullIdCol
name of the column with the full session ID (including any mutable element added to the core session ID, for example a jvmRoute; by default fullid)
sessionCreationTimeCol
name of the column with the time when the session was created (of the long datatype, by default creationtime)
sessionMaxInactiveCol
name of the column with the maximum number of milliseconds the session can remain unaccessed before expiring (by default maxinactive)
sessionVersionCol
name of the column which stores the session's "version" (session version is incremented each time the session is persisted; by default version)
sessionLastAccessedCol
name of the column with the timestamp of the last session access (take the long data type value; by default lastaccess)
sessionNewCol
Name of the column with the flag indicating whether the session is new (session is considered new if it was not yet joined by the client; by default isnew
sessionValidCol
name of the column with the flag indicating whether the session is valid (by default isvalid
sessionMetadataCol
name of the column which can store serialized metadata about the session (currently unused; by default metadata
sessionAttributeCol
name of the column with the serialized session attribute map (by default attributes)

Properties Defining the Manager's Behavior

cleanupInterval
minimum period of time in seconds that must lapse from the last cleaning of old "abandoned" sessions from the database before the next cleaning (by default 14400 seconds, that is, 4 hours)
A session is abandoned if the only server that was handling the session requests was shut down before the session expired, no further requests for the session were received so that the session did not fail over to another server. Such session do not expire on the normal session expiration checks. Therefore a special process runs periodically to clean the session from the database.
replicationTriggerString
activity executed during a request that makes the session database persistent (the activity with the replication-trigger property SET)
maxUnreplicatedInterval
maximum interval between requests, in seconds, after which the session's timestamp is persisted regardless of whether the request caused the session to become dirty in any other way
useJK
flag determining whether the container assumes a JK-based software load balancer is used for load balancing (if set to true, the container examines the session ID associated with every request and replace the jvmRoute portion of the session ID if it detects a failover)
maxActiveAllowed
maximum number of active sessions
useSessionPassivation
flag for enabling/disabling session passivation (session is removed from memory but remains always in the persistent store)
passivationMinIdleTime
minimum time, in seconds, a session must be inactive before passivated
passivationMaxIdleTime
maximum time, in seconds, a session can be inactive before passivated
processExpiresFrequency
frequency at which the background process thread calls the session manager to perform background processes (for example, expire or passivate sessions; (by default, every 10 seconds)
This configuration is defined as value N with the background cleanup process called 1 in N callings to the session manager. Default is 1, that is, the cleanup process is performed every time the manager is called by the background process, that is cleanup is performed every 10 seconds. For example, if set to 6, the manager performs the cleanup once a minute (1/6, that is once in 60 seconds).
sessionNotificationPolicy
fully qualified class name of the implementation of the ClusteredSessionNotificationPolicy interface that is used to govern whether servlet specification notifications is emitted to any registered HttpSessionListener, HttpSessionAttributeListener or HttpSessionBindingListener.