craigmcc 01/09/25 18:38:08
Modified: webapps/tomcat-docs/config manager.xml
Log:
Port <Manager> documentation update about JDBCStore.
Revision Changes Path
1.2 +284 -2 jakarta-tomcat-4.0/webapps/tomcat-docs/config/manager.xml
Index: manager.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/manager.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- manager.xml 2001/08/25 20:06:30 1.1
+++ manager.xml 2001/09/26 01:38:08 1.2
@@ -75,6 +75,14 @@
<subsection name="Standard Implementation">
+ <p>Tomcat provides two standard implementations of <strong>Manager</strong>
+ 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</strong> nested element.</p>
+
+ <h3>Standard Manager Implementation</h3>
+
<p>The standard implementation of <strong>Manager</strong> is
<strong>org.apache.catalina.session.StandardManager</strong>.
It supports the following additional attributes (in addition to the
@@ -95,7 +103,7 @@
</attribute>
<attribute name="debug" required="false">
- <p>The level of debugging detail logged by this <strong>Engine</strong>
+ <p>The level of debugging detail logged by this <strong>Manager</strong>
to the associated <a href="logger.html">Logger</a>. Higher numbers
generate more detailed output. If not specified, the default
debugging detail level is zero (0).</p>
@@ -130,6 +138,110 @@
</attributes>
+ <h3>Persistent Manager Implementation</h3>
+
+ <p><em><strong>WARNING - Use of this Manager implementation
+ has not been thoroughly tested, and should be considered experimental!
+ </strong></em></p>
+
+ <p>The persistent implementation of <strong>Manager</strong> is
+ <strong>org.apache.catalina.session.PersistentManager</strong>. In
+ addition to the usual operations of creating and deleting sessions, a
+ <code>PersistentManager</code> 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</strong> element nested inside the <strong>Manager</strong>
+ element - this is required for use of <code>PersistentManager</code>.</p>
+
+ <p>This implementation of Manager supports the following attributes in
+ addition to the <a href="#Common Attributes">Common Attributes</a>
+ described earlier.</p>
+
+ <attributes>
+
+ <attribute name="algorithm" required="false">
+ <p>Name of the <em>Message Digest</em> algorithm used to calculate
+ session identifiers produced by this Manager. This value must
+ be supported by the <code>java.security.MessageDigest</code> class.
+ If not specified, the default value is "MD5".</p>
+ </attribute>
+
+ <attribute name="checkInterval" required="false">
+ <p>The number of seconds between checks for expired sessions
+ for this Manager. The default value is 60 seconds.</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</code> interface.
+ You <strong>must</strong> specify
+ <code>org.apache.catalina.session.PersistentManager</code> to use
+ this manager implementation.</p>
+ </attribute>
+
+ <attribute name="debug" required="false">
+ <p>The level of debugging detail logged by this <strong>Manager</strong>
+ to the associated <a href="logger.html">Logger</a>. Higher numbers
+ generate more detailed output. If not specified, the default
+ debugging detail level is zero (0).</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</code> 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</code> 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</code>. By default, this feature is disabled.</p>
+ </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</code> for this
+ swapping to be available at any time. If specified, this value should
+ be less than that specified by <code>maxIdleSwap</code>. By default,
+ this value is set to <code>-1</code>.</p>
+ </attribute>
+
+ <attribute name="randomClass" required="false">
+ <p>Java class name of the <code>java.util.Random</code>
+ implementation class to use. If not specified, the default value is
+ <code>java.security.SecureRandom</code>.</p>
+ </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</code>.</p>
+ </attribute>
+
+ </attributes>
+
+ <p>In order to successfully use a PersistentManager, you must nest inside
+ it a <strong><Store></strong> element, as described below.</p>
+
</subsection>
@@ -137,8 +249,178 @@
<section name="Nested Components">
+
+ <h3>Standard Manager Implementation</h3>
- <p>No components may be nested inside a <strong>Manager</strong> element.</p>
+ <p>If you are using the <em>Standard Manager Implementation</em>
+ as described above, no elements may be nested inside your
+ <strong><Manager></strong> element.</p>
+
+ <h3>Persistent Manager Implementation</h3>
+
+ <p>If you are using the <em>Persistent Manager Implementation</em>
+ as described above, you <strong>MUST</strong> nest a
+ <strong><Store></strong> element inside, which defines the
+ characteristics of the persistent data storage. Two implementations
+ of the <code><Store></code> element are currently available,
+ with different characteristics, as described belowl</p>
+
+ <h5>File Based Store</h5>
+
+ <p>The <em>File Based Store</em> 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 <code><Store></code> nested inside
+ your <code><Manager></code> 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</code> interface. You
+ <strong>must</strong> specify
+ <code>org.apache.catalina.session.FileStore</code>
+ to use this implementation.</p>
+ </attribute>
+
+ <attribute name="debug" required="false">
+ <p>The level of debugging detail logged by this <strong>Store</strong>
+ to the associated <a href="logger.html">Logger</a>. Higher numbers
+ generate more detailed output. If not specified, the default
+ debugging detail level is zero (0).</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</h5>
+
+ <p>The <em>JDBC Based Store</em> 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 <code><Store></code> nested inside
+ your <code><Manager></code> 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</code> interface. You
+ <strong>must</strong> specify
+ <code>org.apache.catalina.session.JDBCStore</code>
+ 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="debug" required="false">
+ <p>The level of debugging detail logged by this <strong>Store</strong>
+ to the associated <a href="logger.html">Logger</a>. Higher numbers
+ generate more detailed output. If not specified, the default
+ debugging detail level is zero (0).</p>
+ </attribute>
+
+ <attribute name="driverName" required="true">
+ <p>Java class name of the JDBC driver to be used.</p>
+ </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</code>
+ property of this session. The column type must accept a
+ Java <code>long</code> (64 bits).</p>
+ </attribute>
+
+ <attribute name="sessionMaxInactiveCol" required="true">
+ <p>Name of the database column, contained in the specified
+ session table, that contains the <code>maxInactiveInterval</code>
+ property of this session. The column type must accept a
+ Jave <code>integer</code> (32 bits).</p>
+ </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,
+ session_data mediumblob
+);
+</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</code>
+ directory (if your applications do not also need it) or into the
+ <code>$CATALINA_HOME/common/lib</code> directory (if you wish to share
+ this driver with your web applications.</p>
</section>
