The Manager Component

Table of Contents

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, — see
Standard Manager Implementation below for the details
of this configuration.

Attributes

Common Attributes

All implementations of Manager
support the following attributes:

Attribute

Description

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.

maxActiveSessions

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

When the limit is reached, any attempt to create a new session
(e.g. with HttpServletRequest.getSession() call)
will fail with an IllegalStateException.

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):

Attribute

Description

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
Persistence Across Restarts
for more information. This persistence may be
disabled by setting this attribute to an empty string.

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.

sessionAttributeNameFilter

A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed if its name matches
this pattern. If the pattern is zero length or null, all
attributes are eligible for distribution. The pattern is anchored so the
session attribute name must fully match the pattern. As an example, the
value (userName|sessionHistory) will only distribute the
two session attributes named userName and
sessionHistory. If not specified, the default value of
null will be used.

sessionAttributeValueClassNameFilter

A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed if the implementation
class name of the value matches this pattern. If the pattern is zero
length or null, all attributes are eligible for
distribution. The pattern is anchored so the fully qualified class name
must fully match the pattern. If not specified, the default value of
null will be used unless a SecurityManager is
enabled in which case the default will be
java\\.lang\\.(?:Boolean|Integer|Long|Number|String).

warnOnSessionAttributeFilterFailure

If sessionAttributeNameFilter or
sessionAttributeValueClassNameFilter blocks an
attribute, should this be logged at WARN level? If
WARN level logging is disabled then it will be logged at
DEBUG. The default value of this attribute is
false unless a SecurityManager is enabled in
which case the default will be true.

Persistent Manager Implementation

NOTE: You must set either the
org.apache.catalina.session.StandardSession.ACTIVITY_CHECK or
org.apache.catalina.STRICT_SERVLET_COMPLIANCEsystem properties to true for
the persistent manager to work correctly.

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.

Attribute

Description

className

It has the same meaning as described in the
Common Attributes above.
You must specify
org.apache.catalina.session.PersistentManager to use
this manager implementation.

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 maximum time a session may be idle before it is eligible to be
swapped to disk due to inactivity. Setting this to -1 means
sessions should not be swapped out just because of inactivity. 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 minimum time in seconds a session must be idle before it is
eligible to be swapped to disk to keep the active session count below
maxActiveSessions. Setting to -1 means sessions will not be
swapped out to keep the active session count down. If specified, this
value should be less than that specified by maxIdleSwap.
By default, this value is set to -1.

processExpiresFrequency

It is the same as described above for the
org.apache.catalina.session.StandardManager class.

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.

secureRandomClass

It is the same as described above for the
org.apache.catalina.session.StandardManager class.

secureRandomProvider

It is the same as described above for the
org.apache.catalina.session.StandardManager class.

secureRandomAlgorithm

It is the same as described above for the
org.apache.catalina.session.StandardManager class.

sessionAttributeNameFilter

A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed if its name matches
this pattern. If the pattern is zero length or null, all
attributes are eligible for distribution. The pattern is anchored so the
session attribute name must fully match the pattern. As an example, the
value (userName|sessionHistory) will only distribute the
two session attributes named userName and
sessionHistory. If not specified, the default value of
null will be used.

sessionAttributeValueClassNameFilter

A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed if the implementation
class name of the value matches this pattern. If the pattern is zero
length or null, all attributes are eligible for
distribution. The pattern is anchored so the fully qualified class name
must fully match the pattern. If not specified, the default value of
null will be used unless a SecurityManager is
enabled in which case the default will be
java\\.lang\\.(?:Boolean|Integer|Long|Number|String).

warnOnSessionAttributeFilterFailure

If sessionAttributeNameFilter or
sessionAttributeValueClassNameFilter blocks an
attribute, should this be logged at WARN level? If
WARN level logging is disabled then it will be logged at
DEBUG. The default value of this attribute is
false unless a SecurityManager is enabled in
which case the default will be true.

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

Nested Components

All Manager Implementations

All Manager implementations allow nesting of a
<SessionIdGenerator> element. It defines
the behavior of session id generation. All implementations
of the SessionIdGenerator allow the
following attributes:

Attribute

Description

sessionIdLength

The length of the session ID may be changed with the
sessionIdLength attribute.

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 below.

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:

Attribute

Description

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.

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:

Attribute

Description

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.

connectionName

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

connectionPassword

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

connectionURL

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

dataSourceName

Name of the JNDI resource for a JDBC DataSource-factory. If this option
is given and a valid JDBC resource can be found, it will be used and any
direct configuration of a JDBC connection via connectionURL,
connectionName, connectionPassword and
driverName will be ignored. Since this code uses prepared
statements, you might want to configure pooled prepared statements as
shown in the JNDI resources
HOW-TO.

driverName

Java class name of the JDBC driver to be used.

localDataSource

This allows the Store to use a DataSource defined for the Context
rather than a global DataSource. If not specified, the default is
false: use a global DataSource.

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. If not specified the default
value of app will be used.

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). If not specified the default value of data will be
used.

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). If not specified the default value of id will
be used.

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). If not
specified the default value of maxinactive will be used.

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). If not specified, the default value of maxinactive
will be used.

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. If not specified the
default value of tomcat$sessions will be used.

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. If not
specified the default value of valid will be used.

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:

Note: The SQL command above does not use the default names for either the
table or the columns so the JDBC Store would need to be configured to reflect
this.

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/lib
directory.

Special Features

Persistence Across Restarts

Whenever Apache Tomcat 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).

The persistence across restarts provided by the
StandardManager is a simpler implementation than that
provided by the PersistentManager. If robust, production
quality persistence across restarts is required then the
PersistentManager should be used with an appropriate
configuration.

Disable Session Persistence

As documented above, every web application by default has
standard manager implementation configured, and it performs session
persistence across restarts. To disable this persistence feature, create
a Context configuration file for your web
application and add the following element there: