| <?xml version="1.0"?> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="manager.html"> |
| |
| &project; |
| |
| <properties> |
| <author email="craigmcc@apache.org">Craig R. McClanahan</author> |
| <title>The Manager Component</title> |
| </properties> |
| |
| <body> |
| |
| |
| <section name="Introduction"> |
| |
| <p>The <strong>Manager</strong> element represents the <em>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</a> 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 <strong>Manager</strong> |
| 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</code> interface. |
| If not specified, the standard value (defined below) will be used.</p> |
| </attribute> |
| |
| <attribute name="distributable" required="false"> |
| <p>Set to <code>true</code> 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</code>). |
| Set to <code>false</code> (the default) to not enforce these |
| restrictions.</p> |
| |
| <p><strong>NOTE</strong> - The value for this property is inherited |
| automatically based on the presence or absence of the |
| <code><distributable></code> element in the web application |
| deployment descriptor (<code>/WEB-INF/web.xml</code>).</p> |
| </attribute> |
| |
| </attributes> |
| |
| </subsection> |
| |
| |
| <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 |
| common attributes listed above):</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="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="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="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> |
| |
| </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> |
| |
| |
| </section> |
| |
| |
| <section name="Nested Components"> |
| |
| <h3>Standard Manager Implementation</h3> |
| |
| <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="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</code>.</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 |
| Java <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, |
| 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</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> |
| |
| |
| <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</code> 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</code> |
| interface. You MAY cause the Manager to enforce this restriction by |
| including the <code><distributable></code> element in your web |
| application deployment descriptor (<code>/WEB-INF/web.xml</code>).</p> |
| |
| </subsection> |
| |
| </section> |
| |
| |
| </body> |
| |
| |
| </document> |
