tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs/config manager.xml
Date Wed, 26 Sep 2001 01:38:08 GMT
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>&lt;Store&gt;</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>&lt;Manager&gt;</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>&lt;Store&gt;</strong> element inside, which defines the
  +  characteristics of the persistent data storage.  Two implementations
  +  of the <code>&lt;Store&gt;</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>&lt;Store&gt;</code> nested
inside
  +  your <code>&lt;Manager&gt;</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>&lt;Store&gt;</code> nested
inside
  +  your <code>&lt;Manager&gt;</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>
   
  
  
  

Mime
View raw message