|
|
Tomcat example source code file (manager.xml)
This example Tomcat source code file (manager.xml) is included in the DevDaily.com
"Java Source Code
Warehouse" project. The intent of this project is to help you "Learn Java by Example" TM.
The Tomcat manager.xml source code
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="manager.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan
<author email="yoavs@apache.org">Yoav Shapira
<title>The Manager Component
</properties>
<body>
<section name="Introduction">
<p>The Manager element represents the session
manager</em> that will be used to create and maintain HTTP sessions
as requested by the associated web application.</p>
<p>A Manager element MAY be nested inside a
<a href="context.html">Context component. If it is not included,
a default Manager configuration will be created automatically, which
is sufficient for most requirements.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of Manager
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Manager interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="distributable" required="false">
<p>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 <code>java.io.Serializable).
Set to <code>false (the default) to not enforce these
restrictions.</p>
<p>NOTE - The value for this property is inherited
automatically based on the presence or absence of the
<code><distributable> element in the web application
deployment descriptor (<code>/WEB-INF/web.xml).
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>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 <strong>Store nested element.
<h3>Standard Manager Implementation
<p>The standard implementation of Manager is
<strong>org.apache.catalina.session.StandardManager.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
<attribute name="algorithm" required="false">
<p>Name of the Message Digest algorithm used to calculate
session identifiers produced by this Manager. This value must
be supported by the <code>java.security.MessageDigest class.
If not specified, the default value is "MD5".</p>
</attribute>
<attribute name="entropy" required="false">
<p>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.</p>
</attribute>
<attribute name="maxActiveSessions" required="false">
<p>The maximum number of active sessions that will be created by
this Manager, or -1 (the default) for no limit.</p>
</attribute>
<attribute name="maxInactiveInterval" required="false">
<p>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 60 seconds is used.</p>
<p>This attribute provides the initial value whenever a
new session is created, but the interval may be dynamically
varied by a servlet via the
<code>setMaxInactiveInterval method of the HttpSession object.
</attribute>
<attribute name="pathname" required="false">
<p>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 <a href="#Restart Persistence">Restart
Persistence</a> for more information. Restart persistence may be
disabled by setting this attribute to an empty string.</p>
</attribute>
<attribute name="processExpiresFrequency" required="false">
<p>Frequency of the session expiration, and related manager operations.
Manager operations will be done once for the specified amount of
backgrondProcess calls (ie, the lower the amount, the more often the
checks will occur). The minimum value is 1, and the default value is 6.
</p>
</attribute>
<attribute name="randomClass" required="false">
<p>Java class name of the java.util.Random
implementation class to use. If not specified, the default value is
<code>java.security.SecureRandom.
</attribute>
<attribute name="sessionIdLength" required="false">
<p>The length of session ids created by this Manager, excluding any
JVM route information used for load balancing.
The default is 16.</p>
</attribute>
</attributes>
<h3>Persistent Manager Implementation
<p>WARNING - Use of this Manager implementation
has not been thoroughly tested, and should be considered experimental!
</strong>
<p>The persistent implementation of Manager is
<strong>org.apache.catalina.session.PersistentManager. In
addition to the usual operations of creating and deleting sessions, a
<code>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
<strong>Store element nested inside the Manager
element - this is required for use of <code>PersistentManager.
<p>This implementation of Manager supports the following attributes in
addition to the <a href="#Common Attributes">Common Attributes
described earlier.</p>
<attributes>
<attribute name="algorithm" required="false">
<p>Name of the Message Digest algorithm used to calculate
session identifiers produced by this Manager. This value must
be supported by the <code>java.security.MessageDigest class.
If not specified, the default value is "MD5".</p>
</attribute>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Manager interface.
You <strong>must specify
<code>org.apache.catalina.session.PersistentManager to use
this manager implementation.</p>
</attribute>
<attribute name="entropy" required="false">
<p>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.</p>
</attribute>
<attribute name="maxActiveSessions" required="false">
<p>The maximum number of active sessions that will be created by
this Manager, or -1 (the default) for no limit.</p>
</attribute>
<attribute name="maxIdleBackup" required="false">
<p>The time interval (in seconds) since the last access to a session
before it is eligible for being persisted to the session store, or
<code>-1 to disable this feature. By default, this feature is
disabled.</p>
</attribute>
<attribute name="maxIdleSwap" required="false">
<p>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 <code>-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
<code>maxIdleBackup. By default, this feature is disabled.
</attribute>
<attribute name="minIdleSwap" required="false">
<p>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 <code>-1 for this
swapping to be available at any time. If specified, this value should
be less than that specified by <code>maxIdleSwap. By default,
this value is set to <code>-1.
</attribute>
<attribute name="maxInactiveInterval" required="false">
<p>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 60 seconds is used.</p>
<p>This attribute provides the initial value whenever a
new session is created, but the interval may be dynamically
varied by a servlet via the
<code>setMaxInactiveIntervalmethod of the HttpSession object.
</attribute>
<attribute name="randomClass" required="false">
<p>Java class name of the java.util.Random
implementation class to use. If not specified, the default value is
<code>java.security.SecureRandom.
</attribute>
<attribute name="saveOnRestart" required="false">
<p>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 <code>true.
</attribute>
<attribute name="sessionIdLength" required="false">
<p>The length of session ids created by this Manager, excluding any
JVM route information used for load balancing.
The default is 16.</p>
</attribute>
</attributes>
<p>In order to successfully use a PersistentManager, you must nest inside
it a <strong><Store> element, as described below.
</subsection>
</section>
<section name="Nested Components">
<h3>Standard Manager Implementation
<p>If you are using the Standard Manager Implementation
as described above, no elements may be nested inside your
<strong><Manager> element.
<h3>Persistent Manager Implementation
<p>If you are using the Persistent Manager Implementation
as described above, you <strong>MUST nest a
<strong><Store> element inside, which defines the
characteristics of the persistent data storage. Two implementations
of the <code><Store> element are currently available,
with different characteristics, as described belowl</p>
<h5>File Based Store
<p>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.</p>
<p>To configure this, add a <Store> nested inside
your <code><Manager> element with the following attributes:
</p>
<attributes>
<attribute name="checkInterval" required="false">
<p>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).</p>
</attribute>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Store interface. You
<strong>must specify
<code>org.apache.catalina.session.FileStore
to use this implementation.</p>
</attribute>
<attribute name="directory" required="false">
<p>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.</p>
</attribute>
</attributes>
<h5>JDBC Based Store
<p>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.</p>
<p>To configure this, add a <Store> nested inside
your <code><Manager> element with the following attributes:
</p>
<attributes>
<attribute name="checkInterval" required="false">
<p>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).</p>
</attribute>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Store interface. You
<strong>must specify
<code>org.apache.catalina.session.JDBCStore
to use this implementation.</p>
</attribute>
<attribute name="connectionURL" required="true">
<p>The connection URL that will be handed to the configured JDBC
driver to establish a connection to the database containing our
session table.</p>
</attribute>
<attribute name="driverName" required="true">
<p>Java class name of the JDBC driver to be used.
</attribute>
<attribute name="sessionAppCol" required="true">
<p>Name of the database column, contained in the specified session
table, that contains the Engine, Host, and Web Application Context
name in the format <code>/Engine/Host/Context.
</attribute>
<attribute name="sessionDataCol" required="true">
<p>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).</p>
</attribute>
<attribute name="sessionIdCol" required="true">
<p>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).</p>
</attribute>
<attribute name="sessionLastAccessedCol" required="true">
<p>Name of the database column, contained in the specified
session table, that contains the <code>lastAccessedTime
property of this session. The column type must accept a
Java <code>long (64 bits).
</attribute>
<attribute name="sessionMaxInactiveCol" required="true">
<p>Name of the database column, contained in the specified
session table, that contains the <code>maxInactiveInterval
property of this session. The column type must accept a
Java <code>integer (32 bits).
</attribute>
<attribute name="sessionTable" required="true">
<p>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.</p>
</attribute>
<attribute name="sessionValidCol" required="true">
<p>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.</p>
</attribute>
</attributes>
<p>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:</p>
<source>
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)
);
</source>
<p>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 <code>$CATALINA_HOME/server/lib
directory (if your applications do not also need it) or into the
<code>$CATALINA_HOME/common/lib directory (if you wish to share
this driver with your web applications.</p>
</section>
<section name="Special Features">
<subsection name="Restart Persistence">
<p>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 <code>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.</p>
<p>In order to successfully restore the state of session attributes,
all such attributes MUST implement the <code>java.io.Serializable
interface. You MAY cause the Manager to enforce this restriction by
including the <code><distributable> element in your web
application deployment descriptor (<code>/WEB-INF/web.xml).
</subsection>
</section>
</body>
</document>
Other Tomcat examples (source code examples)
Here is a short list of links related to this Tomcat manager.xml source code file:
|
The search page
Other Tomcat source code examples at this package level
Click here to learn more about this project
