JarCastingTable of Contents
- Tomcat Based Web Session Replication
- Features and Requirements
- How Tomcat Session Replication Works
- Configuring Manager Element for Tomcat
- Controlling Session Caching with deferredWrite
- Setting Session Expiration Checks
- Enabling Session Replication in Multi-App Environments
- Sticky Sessions and Tomcat
- Tomcat Failover and the jvmRoute Parameter
Tomcat Based Web Session Replication
Sample Code: Please see our sample application for Tomcat Based Web Session Replication.
You can also check Hazelcast Guides: Spring Boot Tomcat Session Replication using Hazelcast.
Features and Requirements
Hazelcast Tomcat Session Manager is a container specific module that enables session replication for JEE Web Applications without requiring changes to the application.
Features
- Seamless Tomcat 7, 8, 8.5 & 9 integration.
- Support for sticky and non-sticky sessions.
- Tomcat failover.
- Deferred write for performance boost.
Supported Containers
Tomcat Web Session Replication Module has been tested against the following containers.
- Tomcat 7.0.x - It can be downloaded here.
- Tomcat 8.0.x - It can be downloaded here.
- Tomcat 9.0.x - It can be downloaded here.
The latest tested versions are 7.0.40, 8.0.36, 8.5.9, and 9.0.27.
Requirements
- Tomcat instance must be running with Java 1.6 or higher.
- Session objects that need to be clustered have to be serializable on Hazelcast cluster. Please see here for how you can configure and implement serialization for Hazelcast.
- Hazelcast 4.0+ is supported by Hazelcast Tomcat Session Manager v2.0+.
How Tomcat Session Replication Works
Hazelcast Tomcat Session Manager is a Hazelcast Module where each created HttpSession Object is kept in the Hazelcast Distributed Map. If configured with Sticky Sessions, each Tomcat Instance has its own local copy of the session for performance boost.
Since the sessions are in Hazelcast Distributed Map, you can use all the available features offered by Hazelcast Distributed Map implementation, such as MapStore and WAN Replication.
Tomcat Web Sessions run in two different modes:
- P2P: all Tomcat instances launch its own Hazelcast Instance and join to the Hazelcast Cluster and,
- Client/Server: all Tomcat instances put/retrieve the session data to/from an existing Hazelcast Cluster.
Deploying P2P for Tomcat
P2P deployment launches an embedded Hazelcast member in each server instance.
This type of deployment is simple: just configure your Tomcat and launch. There is no need for an external Hazelcast cluster.
The following steps configure a sample P2P for Hazelcast Session Replication.
-
Go to hazelcast.org and download the latest Hazelcast.
-
Unzip the Hazelcast zip file into the folder
$HAZELCAST_ROOT. -
Go to hazelcast-tomcat-sessionmanager repository and download the latest version.
-
Put
$HAZELCAST_ROOT/lib/hazelcast-all-<version>.jar, andhazelcast-tomcat<tomcatversion>-sessionmanager-<version>.jarandhazelcast.xml(if you want to change defaults) in the folder$CATALINA_HOME/lib/. -
Put a
<Listener>element into the file$CATALINA_HOME$/conf/server.xmlas shown below.
<Server>
...
<Listener className="com.hazelcast.session.P2PLifecycleListener" configLocation="/path/to/hazelcast.xml"/>
...
</Server>
- Put a
<Manager>element into the file$CATALINA_HOME$/conf/context.xmlas shown below.
<Context>
...
<Manager className="com.hazelcast.session.HazelcastSessionManager"/>
...
</Context>
- Start Tomcat instances with a configured load balancer and deploy the web application.
Optional Attributes for Listener Element
Optionally, you can add a configLocation attribute into the <Listener> element. If not provided, hazelcast.xml in the classpath is used by default. URL or full filesystem path as a configLocation value is supported.
Classloader for Hazelcast Instance
Hazelcast instance sets and uses context classloader (WebAppClassLoader) whilst the initialization. However, Hazelcast's classloader configuration cannot be changed dynamically after the instance startup. Thus, if the context's classloader changes during the application runtime, it won't be reflected to the Hazelcast instance.
Deploying Client-Server for Tomcat
In this deployment type, Tomcat instances work as clients on an existing Hazelcast Cluster.
Features
- The existing Hazelcast cluster is used as the Session Replication Cluster.
- Offloading Session Cache from Tomcat to the Hazelcast Cluster.
- The architecture is completely independent. Complete reboot of Tomcat instances.
The following steps configure a sample Client/Server for Hazelcast Session Replication.
-
Go to hazelcast.org and download the latest Hazelcast.
-
Unzip the Hazelcast zip file into the folder
$HAZELCAST_ROOT. -
Go to hazelcast-tomcat-sessionmanager repository and download the latest version.
-
Put
$HAZELCAST_ROOT/lib/hazelcast-all-<version>.jar, andhazelcast-tomcat<tomcatversion>-sessionmanager-<version>.jarandhazelcast.xml(if you want to change defaults) in the folder$CATALINA_HOME/lib/. -
Put a
<Listener>element into the$CATALINA_HOME$/conf/server.xmlas shown below.
<Server>
...
<Listener className="com.hazelcast.session.ClientServerLifecycleListener" configLocation="/path/to/hazelcast-client.xml"/>
...
</Server>
- Update the
<Manager>element in the$CATALINA_HOME$/conf/context.xmlas shown below.
<Context>
<Manager className="com.hazelcast.session.HazelcastSessionManager"
clientOnly="true"/>
</Context>
-
Launch a Hazelcast Instance using
$HAZELCAST_ROOT/bin/server.shor$HAZELCAST_ROOT/bin/server.bat. -
Start Tomcat instances with a configured load balancer and deploy the web application.
Optional Attributes for Listener Element
Optionally, you can add configLocation attribute into the <Listener> element. If not provided, hazelcast-client-default.xml in hazelcast-client-<version>.jar file is used by default. Any client XML file in the classpath, URL or full filesystem path as a configLocation value is also supported.
An example client config that connects directly (i.e. doesn't use multicast) to a specified cluster is:
XML Configuration
<?xml version="1.0" encoding="UTF-8"?>
<hazelcast-client xmlns="http://www.hazelcast.com/schema/client-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.hazelcast.com/schema/client-config
http://www.hazelcast.com/schema/client-config/hazelcast-client-config-4.0.xsd">
<network>
<cluster-members>
<address>HAZELCAST_MEMBER</address>
</cluster-members>
</network>
</hazelcast-client>
YAML Configuration
hazelcast:
network:
cluster-members:
- HAZELCAST_MEMBER
Configuring Manager Element for Tomcat
<Manager> element is used both in P2P and Client/Server mode. You can use the following attributes to configure Tomcat Session Replication Module to better serve your needs.
- Add
mapNameattribute into<Manager>element. Its default value is default Hazelcast Distributed Map. Use this attribute if you have a specially configured map for special cases like WAN Replication, Eviction, MapStore, etc. - Add
stickyattribute into<Manager>element. Its default value is true. - Add
processExpiresFrequencyattribute into<Manager>element. It specifies the frequency of session validity check, in seconds. Its default value is 6 and the minimum value that you can set is 1. - Add
deferredWriteattribute into<Manager>element. Its default value is true. - In P2P mode, add
hazelcastInstanceNameattribute into<Manager>element. It specifies an existing Hazelcast instance to use for session replication. The same can be achieved by settinginstanceNameproperty in Hazelcast configuration. If no instance name is configured, Hazelcast instance starts with a default instance name (SessionManager.DEFAULT_INSTANCE_NAME).
Controlling Session Caching with deferredWrite
Tomcat Web Session Replication Module has its own nature of caching. Attribute changes during the HTTP Request/HTTP Response cycle is cached by default. Distributing those changes to the Hazelcast Cluster is costly. Because of that, Session Replication is only done at the end of each request for updated and deleted attributes. The risk in this approach is losing data if a Tomcat crash happens in the middle of the HTTP Request operation.
You can change that behavior by setting deferredWrite=false in your <Manager> element. By disabling it, all updates that are done on session objects are directly distributed into Hazelcast Cluster.
Setting Session Expiration Checks
Based on Tomcat configuration or sessionTimeout setting in web.xml, sessions are expired over time. This requires a cleanup on the Hazelcast Cluster since there is no need to keep expired sessions in the cluster.
processExpiresFrequency, which is defined in <Manager>, is the only setting that controls the behavior of session expiry policy in the Tomcat Web Session Replication Module. By setting this, you can set the frequency of the session expiration checks in the Tomcat Instance.
Starting with v2.1, the session expiration in Hazelcast cluster is not controlled by Tomcat anymore. Instead, Hazelcast's own expiry/eviction mechanism should be configured. In order to to configure the expiration settings on the Hazelcast cluster, you need to configure eviction for the related session map. Please see the Hazelcast's own eviction mechanism details here. Please note that the sessions might be kept alive longer than the sessionTimeout setting in the cluster if you don't configure the Hazelcast expiration/eviction properly.
Enabling Session Replication in Multi-App Environments
Tomcat can be configured in two ways to enable Session Replication for deployed applications.
- Server Context.xml Configuration
- Application Context.xml Configuration
Server Context.xml Configuration
By configuring $CATALINA_HOME$/conf/context.xml, you can enable session replication for all applications deployed in the Tomcat Instance.
Application Context.xml Configuration
By configuring $CATALINA_HOME/conf/[enginename]/[hostname]/[applicationName].xml, you can enable Session Replication per deployed application.
Sticky Sessions and Tomcat
Sticky Sessions (default)
Sticky Sessions are used to improve the performance since the sessions do not move around the cluster.
Requests always go to the same instance where the session was firstly created. By using a sticky session, you mostly eliminate session replication problems, except for the failover cases. In case of failovers, Hazelcast helps you to not lose existing sessions.
Non-Sticky Sessions
Non-Sticky Sessions are not good for performance because you need to move session data all over the cluster every time a new request comes in.
However, load balancing might be super easy with Non-Sticky caches. In case of heavy load, you can distribute the request to the least used Tomcat instance. Hazelcast supports Non-Sticky Sessions as well.
Tomcat Failover and the jvmRoute Parameter
Each HTTP Request is redirected to the same Tomcat instance if sticky sessions are enabled. The parameter jvmRoute is added to the end of session ID as a suffix, to make Load Balancer aware of the target Tomcat instance.
When Tomcat Failure happens and Load Balancer cannot redirect the request to the owning instance, it sends a request to one of the available Tomcat instances. Since the jvmRoute parameter of session ID is different than that of the target Tomcat instance, Hazelcast Session Replication Module updates the session ID of the session with the new jvmRoute parameter. That means that the Session is moved to another Tomcat instance and Load Balancer will redirect all subsequent HTTP Requests to the new Tomcat Instance.
NOTE: If stickySession is enabled, jvmRoute parameter must be set in $CATALINA_HOME$/conf/server.xml and unique among Tomcat instances in the cluster.
<Engine name="Catalina" defaultHost="localhost" jvmRoute="tomcat-8080">
License
Hazelcast Tomcat Session Manager is available under the Hazelcast Community License.
