132 lines
4.5 KiB
XML
132 lines
4.5 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
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="sessionidgenerator.html">
|
|
|
|
&project;
|
|
|
|
<properties>
|
|
<title>The SessionIdGenerator Component</title>
|
|
</properties>
|
|
|
|
<body>
|
|
|
|
<section name="Table of Contents">
|
|
<toc/>
|
|
</section>
|
|
|
|
<section name="Introduction">
|
|
|
|
<p>The <strong>SessionIdGenerator</strong> element represents the <em>session
|
|
id generator</em> that will be used to create session ids used by
|
|
web application HTTP sessions.</p>
|
|
|
|
<p>A SessionIdGenerator element MAY be nested inside a
|
|
<a href="manager.html">Manager</a> component. If it is not included,
|
|
a default SessionIdGenerator configuration will be created automatically, which
|
|
is sufficient for most requirements, — see
|
|
<em>Standard SessionIdGenerator Implementation</em> below for the details
|
|
of this configuration.</p>
|
|
|
|
</section>
|
|
|
|
|
|
<section name="Attributes">
|
|
|
|
<subsection name="Common Attributes">
|
|
|
|
<p>All implementations of <strong>SessionIdGenerator</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.SessionIdGenerator</code> interface.
|
|
If not specified, the standard value (defined below) will be used.</p>
|
|
</attribute>
|
|
|
|
<attribute name="jvmRoute" required="false">
|
|
<p>A routing identifier for this Tomcat instance. It will be added
|
|
to the session id to allow for stateless stickyness routing by
|
|
load balancers. The details on how the <code>jvmRoute</code>
|
|
will be included in the id are implementation dependent.
|
|
See <a href="#Standard_Implementation">Standard Implementation</a>
|
|
for the default behavior.</p>
|
|
|
|
<p><strong>NOTE</strong> - The value for this property is inherited
|
|
automatically from the <code>jvmRoute</code> attribute of the
|
|
<a href="engine.html">Engine</a> element.</p>
|
|
</attribute>
|
|
|
|
<attribute name="sessionIdLength" required="false">
|
|
<p>The length of session ids created by this SessionIdGenerator.
|
|
The details on how the <code>sessionIdLength</code>
|
|
influences the session id length are implementation dependent.
|
|
See <a href="#Standard_Implementation">Standard Implementation</a>
|
|
for the default behavior.</p>
|
|
</attribute>
|
|
|
|
</attributes>
|
|
|
|
</subsection>
|
|
|
|
|
|
<subsection name="Standard Implementation">
|
|
|
|
<p>Tomcat provides a standard implementations of <strong>SessionIdGenerator</strong>
|
|
for use.</p>
|
|
|
|
<h3>Standard SessionIdGenerator Implementation</h3>
|
|
|
|
<p>The standard implementation of <strong>SessionIdGenerator</strong> is
|
|
<strong>org.apache.catalina.util.StandardSessionIdGenerator</strong>.
|
|
It supports the following attributes:</p>
|
|
|
|
<attributes>
|
|
|
|
<attribute name="jvmRoute" required="false">
|
|
<p>A routing identifier for this Tomcat instance. It will be added
|
|
to the end of the session id separated by a ".".</p>
|
|
</attribute>
|
|
|
|
<attribute name="sessionIdLength" required="false">
|
|
<p>The length of session ids created by this SessionIdGenerator.
|
|
More precisely the session id length is twice the value of
|
|
<code>sessionIdLength</code> plus the length of the trailing
|
|
<code>jvmRoute</code> if given. The factor 2 is because
|
|
the session id is constructed using <code>sessionIdLength</code>
|
|
random bytes, each byte being encoded in two hex characters
|
|
in the actual id. The default value is 16.</p>
|
|
</attribute>
|
|
|
|
</attributes>
|
|
|
|
</subsection>
|
|
|
|
|
|
</section>
|
|
|
|
|
|
</body>
|
|
|
|
|
|
</document>
|