The Tomcat Servlet/JSP Container

Apache Tomcat 4

Apache Logo

The Manager Component

Introduction

The Manager element represents the session manager that will be used to create and maintain HTTP sessions as requested by the associated web application.

A Manager element MAY be nested inside a Context component. If it is not included, a default Manager configuration will be created automatically, which is sufficient for most requirements.

Attributes
Common Attributes

All implementations of Manager support the following attributes:

AttributeDescription
className

Java class name of the implementation to use. This class must implement the org.apache.catalina.Manager interface. If not specified, the standard value (defined below) will be used.

distributable

Set to true to ask the session manager to enforce the restrictions described in the Servlet Specification on distributable applications (primarily, this would mean that all session attributes must implement java.io.Serializable). Set to false (the default) to not enforce these restrictions.

NOTE - The value for this property is inherited automatically based on the presence or absence of the <distributable> element in the web application deployment descriptor (/WEB-INF/web.xml).

Standard Implementation

Tomcat provides two standard implementations of Manager for use - the default one stores active sessions, while the optional one stores active sessions that have been swapped out (in addition to saving sessions across a restart of Tomcat) in a storage location that is selected via the use of an appropriate Store nested element.

Standard Manager Implementation

The standard implementation of Manager is org.apache.catalina.session.StandardManager. It supports the following additional attributes (in addition to the common attributes listed above):

AttributeDescription
algorithm

Name of the Message Digest algorithm used to calculate session identifiers produced by this Manager. This value must be supported by the java.security.MessageDigest class. If not specified, the default value is "MD5".

checkInterval

The number of seconds between checks for expired sessions for this manager. The default value is 60 seconds.

debug

The level of debugging detail logged by this Manager to the associated Logger. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).

entropy

A String value that is utilized when seeding the random number generator used to create session identifiers for this Manager. If not specified, a semi-useful value is calculated, but a long String value should be specified in security-conscious environments.

maxActiveSessions

The maximum number of active sessions that will be created by this Manager, or -1 (the default) for no limit.

pathname

Absolute or relative (to the work directory for this Context) pathname of the file in which session state will be preserved across application restarts, if possible. The default is "SESSIONS.ser". See Restart Persistence for more information.

randomClass

Java class name of the java.util.Random implementation class to use. If not specified, the default value is java.security.SecureRandom.

Persistent Manager Implementation

WARNING - Use of this Manager implementation has not been thoroughly tested, and should be considered experimental!

The persistent implementation of Manager is org.apache.catalina.session.PersistentManager. In addition to the usual operations of creating and deleting sessions, a PersistentManager has the capability to swap active (but idle) sessions out to a persistent storage mechanism, as well as to save all sessions across a normal restart of Tomcat. The actual persistent storage mechanism used is selected by your choice of a Store element nested inside the Manager element - this is required for use of PersistentManager.

This implementation of Manager supports the following attributes in addition to the Common Attributes described earlier.

AttributeDescription
algorithm

Name of the Message Digest algorithm used to calculate session identifiers produced by this Manager. This value must be supported by the java.security.MessageDigest class. If not specified, the default value is "MD5".

checkInterval

The number of seconds between checks for expired sessions for this Manager. The default value is 60 seconds.

className

Java class name of the implementation to use. This class must implement the org.apache.catalina.Manager interface. You must specify org.apache.catalina.session.PersistentManager to use this manager implementation.

debug

The level of debugging detail logged by this Manager to the associated Logger. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).

entropy

A String value that is utilized when seeding the random number generator used to create session identifiers for this Manager. If not specified, a semi-useful value is calculated, but a long String value should be specified in security-conscious environments.

maxActiveSessions

The maximum number of active sessions that will be created by this Manager, or -1 (the default) for no limit.

maxIdleBackup

The time interval (in seconds) since the last access to a session before it is eligible for being persisted to the session store, or -1 to disable this feature. By default, this feature is disabled.

maxIdleSwap

The time interval (in seconds) since the last access to a session before it should be persisted to the session store, and passivated out of the server's memory, or -1 to disable this feature. If this feature is enabled, the time interval specified here should be equal to or longer than the value specified for maxIdleBackup. By default, this feature is disabled.

minIdleSwap

The time interval (in seconds) since the last access to a session before it will be eligible to be persisted to the session store, and passivated out of the server's memory, or -1 for this swapping to be available at any time. If specified, this value should be less than that specified by maxIdleSwap. By default, this value is set to -1.

randomClass

Java class name of the java.util.Random implementation class to use. If not specified, the default value is java.security.SecureRandom.

saveOnRestart

Should all sessions be persisted and reloaded when Tomcat is shut down and restarted (or when this application is reloaded)? By default, this attribute is set to true.

In order to successfully use a PersistentManager, you must nest inside it a <Store> element, as described below.

Nested Components

Standard Manager Implementation

If you are using the Standard Manager Implementation as described above, no elements may be nested inside your <Manager> element.

Persistent Manager Implementation

If you are using the Persistent Manager Implementation as described above, you MUST nest a <Store> element inside, which defines the characteristics of the persistent data storage. Two implementations of the <Store> element are currently available, with different characteristics, as described belowl

File Based Store

The File Based Store implementation saves swapped out sessions in individual files (named based on the session identifier) in a configurable directory. Therefore, you are likely to encounter scalability problems as the number of active sessions increases, and this should primarily be considered a means to easily experiment.

To configure this, add a <Store> nested inside your <Manager> element with the following attributes:

AttributeDescription
checkInterval

The interval (in seconds) between checks for expired sessions among those sessions that are currently swapped out. By default, this interval is set to 60 seconds (one minute).

className

Java class name of the implementation to use. This class must implement the org.apache.catalina.Store interface. You must specify org.apache.catalina.session.FileStore to use this implementation.

debug

The level of debugging detail logged by this Store to the associated Logger. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).

directory

Absolute or relative (to the temporary work directory for this web application) pathname of the directory into which individual session files are written. If not specified, the temporary work directory assigned by the container is utilized.

JDBC Based Store

The JDBC Based Store implementation saves swapped out sessions in individual rows of a preconfigured table in a database that is accessed via a JDBC driver. With large numbers of swapped out sessions, this implementation will exhibit improved performance over the File Based Store described above.

To configure this, add a <Store> nested inside your <Manager> element with the following attributes:

AttributeDescription
checkInterval

The interval (in seconds) between checks for expired sessions among those sessions that are currently swapped out. By default, this interval is set to 60 seconds (one minute).

className

Java class name of the implementation to use. This class must implement the org.apache.catalina.Store interface. You must specify org.apache.catalina.session.JDBCStore to use this implementation.

connectionURL

The connection URL that will be handed to the configured JDBC driver to establish a connection to the database containing our session table.

debug

The level of debugging detail logged by this Store to the associated Logger. Higher numbers generate more detailed output. If not specified, the default debugging detail level is zero (0).

driverName

Java class name of the JDBC driver to be used.

sessionAppCol

Name of the database column, contained in the specified session table, that contains the Engine, Host, and Web Application Context name in the format /Engine/Host/Context.

sessionDataCol

Name of the database column, contained in the specified session table, that contains the serialized form of all session attributes for a swapped out session. The column type must accept a binary object (typically called a BLOB).

sessionIdCol

Name of the database column, contained in the specified session table, that contains the session identifier of the swapped out session. The column type must accept character string data of at least as many characters as are contained in session identifiers created by Tomcat (typically 32).

sessionLastAccessedCol

Name of the database column, contained in the specified session table, that contains the lastAccessedTime property of this session. The column type must accept a Java long (64 bits).

sessionMaxInactiveCol

Name of the database column, contained in the specified session table, that contains the maxInactiveInterval property of this session. The column type must accept a Java integer (32 bits).

sessionTable

Name of the database table to be used for storing swapped out sessions. This table must contain (at least) the database columns that are configured by the other attributes of this element.

sessionValidCol

Name of the database column, contained in the specified session table, that contains a flag indicating whether this swapped out session is still valid or not. The column type must accept a single character.

Before attempting to use the JDBC Based Store for the first time, you must create the table that will be used to store swapped out sessions. Detailed SQL commands vary depending on the database you are using, but a script like this will generally be required:

create table tomcat_sessions (
  session_id     varchar(100) not null primary key,
  valid_session  char(1) not null,
  max_inactive   int not null,
  last_access    bigint not null,
  app_name       varchar(255),
  session_data   mediumblob,
  KEY kapp_name(app_name)
);

In order for the JDBC Based Store to successfully connect to your database, the JDBC driver you configure must be visible to Tomcat's internal class loader. Generally, that means you must place the JAR file containing this driver into the $CATALINA_HOME/server/lib directory (if your applications do not also need it) or into the $CATALINA_HOME/common/lib directory (if you wish to share this driver with your web applications.

Special Features
Restart Persistence

Whenver Catalina is shut down normally and restarted, or when an application reload is triggered, the standard Manager implementation will attempt to serialize all currently active sessions to a disk file located via the pathname attribute. All such saved sessions will then be deserialized and activated (assuming they have not expired in the mean time) when the application reload is completed.

In order to successfully restore the state of session attributes, all such attributes MUST implement the java.io.Serializable interface. You MAY cause the Manager to enforce this restriction by including the <distributable> element in your web application deployment descriptor (/WEB-INF/web.xml).


Copyright © 1999-2009, Apache Software Foundation