| <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 Configuration Reference (7.0.77) - The Manager Component</title><meta name="author" content="Craig R. McClanahan"><meta name="author" content="Yoav Shapira"><style type="text/css" media="print"> | |
| .noPrint {display: none;} | |
| td#mainBody {width: 100%;} | |
| </style><style type="text/css"> | |
| code {background-color:rgb(224,255,255);padding:0 0.1em;} | |
| code.attributeName, code.propertyName {background-color:transparent;} | |
| table { | |
| border-collapse: collapse; | |
| text-align: left; | |
| } | |
| table *:not(table) { | |
| /* Prevent border-collapsing for table child elements like <div> */ | |
| border-collapse: separate; | |
| } | |
| th { | |
| text-align: left; | |
| } | |
| div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code { | |
| background-color: transparent; | |
| } | |
| div.codeBox { | |
| overflow: auto; | |
| margin: 1em 0; | |
| } | |
| div.codeBox pre { | |
| margin: 0; | |
| padding: 4px; | |
| border: 1px solid #999; | |
| border-radius: 5px; | |
| background-color: #eff8ff; | |
| display: table; /* To prevent <pre>s from taking the complete available width. */ | |
| /* | |
| When it is officially supported, use the following CSS instead of display: table | |
| to prevent big <pre>s from exceeding the browser window: | |
| max-width: available; | |
| width: min-content; | |
| */ | |
| } | |
| div.codeBox pre.wrap { | |
| white-space: pre-wrap; | |
| } | |
| table.defaultTable tr, table.detail-table tr { | |
| border: 1px solid #CCC; | |
| } | |
| table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) { | |
| background-color: #FAFBFF; | |
| } | |
| table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) { | |
| background-color: #EEEFFF; | |
| } | |
| table.defaultTable th, table.detail-table th { | |
| background-color: #88b; | |
| color: #fff; | |
| } | |
| table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td { | |
| padding: 5px 8px; | |
| } | |
| p.notice { | |
| border: 1px solid rgb(255, 0, 0); | |
| background-color: rgb(238, 238, 238); | |
| color: rgb(0, 51, 102); | |
| padding: 0.5em; | |
| margin: 1em 2em 1em 1em; | |
| } | |
| </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt=" | |
| The Apache Tomcat Servlet/JSP Container | |
| " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>web.xml</strong></p><ul><li><a href="filter.html">Filter</a></li></ul><p><strong>Other</strong></p><ul><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>The Manager Component</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> | |
| <ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Standard_Implementation">Standard Implementation</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a><ol><li><a href="#Persistence_Across_Restarts">Persistence Across Restarts</a></li><li><a href="#Disable_Session_Persistence">Disable Session Persistence</a></li></ol></li></ul> | |
| </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> | |
| <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, — see | |
| <em>Standard Manager Implementation</em> below for the details | |
| of this configuration.</p> | |
| </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote> | |
| <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote> | |
| <p>All implementations of <strong>Manager</strong> | |
| support the following attributes:</p> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">className</code></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">distributable</code></td><td align="left" valign="center"> | |
| <p><strong>Deprecated</strong>: This should be configured via the | |
| Context.</p> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxActiveSessions</code></td><td align="left" valign="center"> | |
| <p>The maximum number of active sessions that will be created by | |
| this Manager, or <code>-1</code> (the default) for no limit.</p> | |
| <p>When the limit is reached, any attempt to create a new session | |
| (e.g. with <code>HttpServletRequest.getSession()</code> call) | |
| will fail with an <code>IllegalStateException</code>.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxInactiveInterval</code></td><td align="left" valign="center"> | |
| <p><strong>Deprecated</strong>: This should be configured via the | |
| Context.</p> | |
| <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 1800 seconds (30 minutes) 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</code> method of the <code>HttpSession</code> object.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionIdLength</code></td><td align="left" valign="center"> | |
| <p>The length of session ids created by this Manager, measured in bytes, | |
| excluding subsequent conversion to a hexadecimal string and | |
| excluding any JVM route information used for load balancing. | |
| The default is 16. You should set the length on a nested | |
| <strong>SessionIdGenerator</strong> element instead.</p> | |
| </td></tr></table> | |
| </blockquote></td></tr></table> | |
| <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standard Implementation"><!--()--></a><a name="Standard_Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote> | |
| <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> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">pathname</code></td><td align="left" valign="center"> | |
| <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".<br>See | |
| <a href="#Persistence_Across_Restarts">Persistence Across Restarts</a> | |
| for more information. This persistence may be | |
| disabled by setting this attribute to an empty string.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">processExpiresFrequency</code></td><td align="left" valign="center"> | |
| <p>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. | |
| </p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomClass</code></td><td align="left" valign="center"> | |
| <p>Name of the Java class that extends | |
| <code>java.security.SecureRandom</code> to use to generate session IDs. | |
| If not specified, the default value is | |
| <code>java.security.SecureRandom</code>.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomProvider</code></td><td align="left" valign="center"> | |
| <p>Name of the provider to use to create the | |
| <code>java.security.SecureRandom</code> 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.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomAlgorithm</code></td><td align="left" valign="center"> | |
| <p>Name of the algorithm to use to create the | |
| <code>java.security.SecureRandom</code> 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.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionAttributeNameFilter</code></td><td align="left" valign="center"> | |
| <p>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 <code>null</code>, 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 <code>(userName|sessionHistory)</code> will only distribute the | |
| two session attributes named <code>userName</code> and | |
| <code>sessionHistory</code>. If not specified, the default value of | |
| <code>null</code> will be used.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionAttributeValueClassNameFilter</code></td><td align="left" valign="center"> | |
| <p>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 <code>null</code>, 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 | |
| <code>null</code> will be used unless a <code>SecurityManager</code> is | |
| enabled in which case the default will be | |
| <code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">warnOnSessionAttributeFilterFailure</code></td><td align="left" valign="center"> | |
| <p>If <strong>sessionAttributeNameFilter</strong> or | |
| <strong>sessionAttributeValueClassNameFilter</strong> blocks an | |
| attribute, should this be logged at <code>WARN</code> level? If | |
| <code>WARN</code> level logging is disabled then it will be logged at | |
| <code>DEBUG</code>. The default value of this attribute is | |
| <code>false</code> unless a <code>SecurityManager</code> is enabled in | |
| which case the default will be <code>true</code>.</p> | |
| </td></tr></table> | |
| <h3>Persistent Manager Implementation</h3> | |
| <p><strong>NOTE:</strong> You must set either the | |
| <code>org.apache.catalina.session.StandardSession.ACTIVITY_CHECK</code> or | |
| <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> | |
| <a href="systemprops.html">system properties</a> to <code>true</code> for | |
| the persistent manager to work correctly.</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> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center"> | |
| <p>It has the same meaning as described in the | |
| <a href="#Common_Attributes">Common Attributes</a> above. | |
| You <strong>must</strong> specify | |
| <code>org.apache.catalina.session.PersistentManager</code> to use | |
| this manager implementation.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxIdleBackup</code></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxIdleSwap</code></td><td align="left" valign="center"> | |
| <p>The maximum time a session may be idle before it is eligible to be | |
| swapped to disk due to inactivity. Setting this to <code>-1</code> 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 <code>maxIdleBackup</code>. By | |
| default, this feature is disabled.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">minIdleSwap</code></td><td align="left" valign="center"> | |
| <p>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 <code>-1</code> 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 <code>maxIdleSwap</code>. | |
| By default, this value is set to <code>-1</code>.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">processExpiresFrequency</code></td><td align="left" valign="center"> | |
| <p>It is the same as described above for the | |
| <code>org.apache.catalina.session.StandardManager</code> class. | |
| </p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">saveOnRestart</code></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomClass</code></td><td align="left" valign="center"> | |
| <p>It is the same as described above for the | |
| <code>org.apache.catalina.session.StandardManager</code> class. | |
| </p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomProvider</code></td><td align="left" valign="center"> | |
| <p>It is the same as described above for the | |
| <code>org.apache.catalina.session.StandardManager</code> class. | |
| </p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomAlgorithm</code></td><td align="left" valign="center"> | |
| <p>It is the same as described above for the | |
| <code>org.apache.catalina.session.StandardManager</code> class. | |
| </p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionAttributeNameFilter</code></td><td align="left" valign="center"> | |
| <p>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 <code>null</code>, 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 <code>(userName|sessionHistory)</code> will only distribute the | |
| two session attributes named <code>userName</code> and | |
| <code>sessionHistory</code>. If not specified, the default value of | |
| <code>null</code> will be used.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionAttributeValueClassNameFilter</code></td><td align="left" valign="center"> | |
| <p>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 <code>null</code>, 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 | |
| <code>null</code> will be used unless a <code>SecurityManager</code> is | |
| enabled in which case the default will be | |
| <code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">warnOnSessionAttributeFilterFailure</code></td><td align="left" valign="center"> | |
| <p>If <strong>sessionAttributeNameFilter</strong> or | |
| <strong>sessionAttributeValueClassNameFilter</strong> blocks an | |
| attribute, should this be logged at <code>WARN</code> level? If | |
| <code>WARN</code> level logging is disabled then it will be logged at | |
| <code>DEBUG</code>. The default value of this attribute is | |
| <code>false</code> unless a <code>SecurityManager</code> is enabled in | |
| which case the default will be <code>true</code>.</p> | |
| </td></tr></table> | |
| <p>In order to successfully use a PersistentManager, you must nest inside | |
| it a <strong><Store></strong> element, as described below.</p> | |
| </blockquote></td></tr></table> | |
| </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote> | |
| <h3>All Manager Implementations</h3> | |
| <p>All Manager implementations bundled with Tomcat or extending | |
| <code>ManagerBase</code> allow nesting of a | |
| <strong><SessionIdGenerator></strong> element. It defines | |
| the behavior of session id generation. All implementations | |
| of the <a href="sessionidgenerator.html">SessionIdGenerator</a> allow the | |
| following attributes: | |
| </p> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">sessionIdLength</code></td><td align="left" valign="center"> | |
| <p>The length of the session ID may be changed with the | |
| <strong>sessionIdLength</strong> attribute. | |
| </p> | |
| </td></tr></table> | |
| <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 below.</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> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">checkInterval</code></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">directory</code></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr></table> | |
| <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> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">checkInterval</code></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionURL</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><code class="attributeName">dataSourceName</code></td><td align="left" valign="center"> | |
| <p>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 <code>connectionURL</code> | |
| and <code>driverName</code> will be ignored. Since this code uses prepared | |
| statements, you might want to configure pooled prepared statements as | |
| shown in <a href="../jndi-resources-howto.html">the JNDI resources | |
| HOW-TO</a>.</p> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">driverName</code></strong></td><td align="left" valign="center"> | |
| <p>Java class name of the JDBC driver to be used.</p> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">sessionAppCol</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">sessionDataCol</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">sessionIdCol</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">sessionLastAccessedCol</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">sessionMaxInactiveCol</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">sessionTable</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">sessionValidCol</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| </td></tr></table> | |
| <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> | |
| <div class="codeBox"><pre><code>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) | |
| );</code></pre></div> | |
| <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/lib</code> | |
| directory.</p> | |
| </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote> | |
| <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Persistence Across Restarts"><!--()--></a><a name="Persistence_Across_Restarts"><strong>Persistence Across Restarts</strong></a></font></td></tr><tr><td><blockquote> | |
| <p>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 <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> | |
| <p>The persistence across restarts provided by the | |
| <strong>StandardManager</strong> is a simpler implementation than that | |
| provided by the <strong>PersistentManager</strong>. If robust, production | |
| quality persistence across restarts is required then the | |
| <strong>PersistentManager</strong> should be used with an appropriate | |
| configuration.</p> | |
| </blockquote></td></tr></table> | |
| <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Disable Session Persistence"><!--()--></a><a name="Disable_Session_Persistence"><strong>Disable Session Persistence</strong></a></font></td></tr><tr><td><blockquote> | |
| <p>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 <a href="context.html">Context</a> configuration file for your web | |
| application and add the following element there:</p> | |
| <div class="codeBox"><pre><code><Manager pathname="" /></code></pre></div> | |
| </blockquote></td></tr></table> | |
| </blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions | |
| on improving documentation for Apache Tomcat.<br><br> | |
| If you have trouble and need help, read | |
| <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page | |
| and ask your question on the tomcat-users | |
| <a href="http://tomcat.apache.org/lists.html">mailing list</a>. | |
| Do not ask such questions here. This is not a Q&A section.<br><br> | |
| The Apache Comments System is explained <a href="../comments.html">here</a>. | |
| Comments may be removed by our moderators if they are either | |
| implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!-- | |
| var comments_shortname = 'tomcat'; | |
| var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/config/manager.html'; | |
| (function(w, d) { | |
| if (w.location.hostname.toLowerCase() == "tomcat.apache.org") { | |
| d.write('<div id="comments_thread"><\/div>'); | |
| var s = d.createElement('script'); | |
| s.type = 'text/javascript'; | |
| s.async = true; | |
| s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; | |
| (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); | |
| } | |
| else { | |
| d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>'); | |
| } | |
| })(window, document); | |
| //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em> | |
| Copyright © 1999-2017, Apache Software Foundation | |
| </em></font></div></td></tr></table></body></html> |