The ClusterManager object

Table of Contents

Introduction

A cluster manager is an extension to Tomcat's session manager interface, org.apache.catalina.Manager. A cluster manager must implement the org.apache.catalina.ha.ClusterManager and is solely responsible for how the session is replicated.
There are currently two different managers, the org.apache.catalina.ha.session.DeltaManager replicates deltas of session data to all members in the cluster. This implementation is proven and works very well, but has a limitation as it requires the cluster members to be homogeneous, all nodes must deploy the same applications and be exact replicas. The org.apache.catalina.ha.session.BackupManager also replicates deltas but only to one backup node. The location of the backup node is known to all nodes in the cluster. It also supports heterogeneous deployments, so the manager knows at what locations the web application is deployed.

The <Manager>

The <Manager> element defined inside the <Cluster> element is the template defined for all web applications that are marked <distributable/> in their web.xml file. However, you can still override the manager implementation on a per web application basis, by putting the <Manager> inside the <Context> element either in the context.xml file or the server.xml file.

Attributes

Common Attributes

Attribute Description
className
name The name of this cluster manager, the name is used to identify a session manager on a node. The name might get modified by the Cluster element to make it unique in the container.
notifyListenersOnReplication Set to true if you wish to have session listeners notified when session attributes are being replicated or removed across Tomcat nodes in the cluster.
sessionAttributeFilter A regular expression used to filter, which session attributes will be replicated. An attribute will only be replicated, if its name matches this pattern. If the pattern is not set (default), all attributes are eligible for replication. As an example, the value ^(userName|sessionHistory)$ will only replicate the two session attributes named userName and sessionHistory.
maxInactiveInterval

The initial maximum time interval, in seconds, between client requests before a session is invalidated. A negative value will result in sessions never timing out. If the attribute is not provided, a default of 1800 seconds (30 minutes) is used.

This attribute provides the initial value whenever a new session is created, but the interval may be dynamically varied by a servlet via the setMaxInactiveInterval method of the HttpSession object.

sessionIdLength

The length of session ids created by this Manager, measured in bytes, excluding subsequent conversion to a hexadecimal string and excluding any JVM route information used for load balancing. The default is 16.

processExpiresFrequency

Frequency of the session expiration, and related manager operations. Manager operations will be done once for the specified amount of backgroundProcess calls (i.e., the lower the amount, the more often the checks will occur). The minimum value is 1, and the default value is 6.

secureRandomClass

Name of the Java class that extends java.security.SecureRandom to use to generate session IDs. If not specified, the default value is java.security.SecureRandom.

secureRandomProvider

Name of the provider to use to create the java.security.SecureRandom instances that generate session IDs. If an invalid algorithm and/or provider is specified, the Manager will use the platform default provider and the default algorithm. If not specified, the platform default provider will be used.

secureRandomAlgorithm

Name of the algorithm to use to create the java.security.SecureRandom instances that generate session IDs. If an invalid algorithm and/or provider is specified, the Manager will use the platform default provider and the default algorithm. If not specified, the default algorithm of SHA1PRNG will be used. If the default algorithm is not supported, the platform default will be used. To specify that the platform default should be used, do not set the secureRandomProvider attribute and set this attribute to the empty string.

org.apache.catalina.ha.session.DeltaManager Attributes

Attribute Description
expireSessionsOnShutdown When a web application is being shutdown, Tomcat issues an expire call to each session to notify all the listeners. If you wish for all sessions to expire on all nodes when a shutdown occurs on one node, set this value to true. Default value is false.
maxActiveSessions The maximum number of active sessions that will be created by this Manager, or -1 (the default) for no limit. For this manager, all sessions are counted as active sessions irrespective if whether or not the current node is the primary node for the session.
notifySessionListenersOnReplication Set to true if you wish to have session listeners notified when sessions are created and expired across Tomcat nodes in the cluster.
notifyContainerListenersOnReplication Set to true if you wish to have container listeners notified across Tomcat nodes in the cluster.
stateTransferTimeout The time in seconds to wait for a session state transfer to complete from another node when a node is starting up. Default value is 60 seconds.
sendAllSessions Flag whether send sessions as split blocks. If set to true, send all sessions as one big block. If set to false, send sessions as split blocks. Default value is true.
sendAllSessionsSize The number of sessions in a session block message. This value is effective only when sendAllSessions is false. Default is 1000.
sendAllSessionsWaitTime Wait time between sending of session block messages. This value is effective only when sendAllSessions is false. Default is 2000 milliseconds.
stateTimestampDrop When this node sends a GET_ALL_SESSIONS message to other node, all session messages that are received as a response are queued. If this attribute is set to true, the received session messages (except any GET_ALL_SESSIONS sent by other nodes) are filtered by their timestamp. A message is dropped if it is not a GET_ALL_SESSIONS message and its timestamp is earlier than the timestamp of our GET_ALL_SESSIONS message. If set to false, all queued session messages are handled. Default is true.

org.apache.catalina.ha.session.BackupManager Attributes

Attribute Description
mapSendOptions The backup manager uses a replicated map, this map is sending and receiving messages. You can setup the flag for how this map is sending messages, the default value is 6(synchronous).
Note that if you use asynchronous messaging it is possible for update messages for a session to be processed by the receiving node in a different order to the order in which they were sent.
maxActiveSessions The maximum number of active sessions that will be created by this Manager, or -1 (the default) for no limit. For this manager, only sessions where the current node is the primary node for the session are considered active sessions.
rpcTimeout Timeout for RPC message used for broadcast and transfer state from another map. Default value is 15000 milliseconds.
terminateOnStartFailure Set to true if you wish to terminate replication map when replication map fails to start. If replication map is terminated, associated context will fail to start. If you set this attribute to false, replication map does not end. It will try to join the map membership in the heartbeat. Default value is false .

Comments

Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.

If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.

The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.