升级Tomcat版本 apache-tomcat-7.0.77
diff --git a/tomcat-cas/webapps/docs/config/context.html b/tomcat-cas/webapps/docs/config/context.html
index bf7f141..04ab44f 100644
--- a/tomcat-cas/webapps/docs/config/context.html
+++ b/tomcat-cas/webapps/docs/config/context.html
@@ -1,19 +1,94 @@
-<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference (6.0.41) - The Context Container</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
- .noPrint {display: none;}
- td#mainBody {width: 100%;}
- </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="
+<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 Configuration Reference (7.0.77) - The Context Container</title><meta name="author" content="Craig R. McClanahan"><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 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.41, May 19 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="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></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="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="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>Apache Tomcat Configuration Reference</h1><h2>The Context Container</h2><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><ol><li><a href="#Naming">Naming</a></li><li><a href="#Defining_a_context">Defining a context</a></li></ol></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="#Logging">Logging</a></li><li><a href="#Access_Logs">Access Logs</a></li><li><a href="#Automatic_Context_Configuration">Automatic Context Configuration</a></li><li><a href="#Context_Parameters">Context Parameters</a></li><li><a href="#Environment_Entries">Environment Entries</a></li><li><a href="#Lifecycle_Listeners">Lifecycle Listeners</a></li><li><a href="#Request_Filters">Request Filters</a></li><li><a href="#Resource_Definitions">Resource Definitions</a></li><li><a href="#Resource_Links">Resource Links</a></li><li><a href="#Transaction">Transaction</a></li></ol></li></ul>
+ " 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 Context Container</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><ol><li><a href="#Parallel_deployment">Parallel deployment</a></li><li><a href="#Naming">Naming</a></li><li><a href="#Defining_a_context">Defining a context</a></li></ol></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="#Logging">Logging</a></li><li><a href="#Access_Logs">Access Logs</a></li><li><a href="#Automatic_Context_Configuration">Automatic Context Configuration</a></li><li><a href="#Context_Parameters">Context Parameters</a></li><li><a href="#Environment_Entries">Environment Entries</a></li><li><a href="#Lifecycle_Listeners">Lifecycle Listeners</a></li><li><a href="#Request_Filters">Request Filters</a></li><li><a href="#Resource_Definitions">Resource Definitions</a></li><li><a href="#Resource_Links">Resource Links</a></li><li><a href="#Transaction">Transaction</a></li><li><a href="#Virtual_webapp">Virtual webapp</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>
- <blockquote><em>
- <p>The description below uses the variable name $CATALINA_BASE to refer the
+ <p><em>
+ The description below uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
- not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE
+ not configured Tomcat for multiple instances by setting a CATALINA_BASE
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
- the directory into which you have installed Tomcat 6.</p>
- </em></blockquote>
+ the directory into which you have installed Tomcat.
+ </em></p>
<p>The <strong>Context</strong> element represents a <em>web
application</em>, which is run within a particular virtual host.
@@ -31,64 +106,123 @@
Request URI against the <em>context path</em> of each defined Context.
Once selected, that Context will select an appropriate servlet to
process the incoming request, according to the servlet mappings defined
- in the <em>web application deployment descriptor</em> file (which MUST
- be located at <code>/WEB-INF/web.xml</code> within the web app's
- directory hierarchy).</p>
+ by the web application deployment.</p>
<p>You may define as many <strong>Context</strong> elements as you
- wish. Each such Context MUST have a unique context path within a virtual
- host. In
- addition, a Context must be present with a context path equal to
+ wish. Each such Context MUST have a unique context name within a virtual
+ host. The context path does not need to be unique (see <em>parallel
+ deployment</em> below). In addition, a Context must be present with a
+ context path equal to
a zero-length string. This Context becomes the <em>default</em>
web application for this virtual host, and is used to process all
requests that do not match any other Context's context path.</p>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Parallel deployment"><!--()--></a><a name="Parallel_deployment"><strong>Parallel deployment</strong></a></font></td></tr><tr><td><blockquote>
+ <p><b>You may deploy multiple versions of a web application with the same
+ context path at the same time.</b> The rules used to match requests to a
+ context version are as follows:
+ </p>
+ <ul>
+ <li>If no session information is present in the request, use the latest
+ version.</li>
+ <li>If session information is present in the request, check the session
+ manager of each version for a matching session and if one is found, use that
+ version.</li>
+ <li>If session information is present in the request but no matching session
+ can be found, use the latest version.</li>
+ </ul>
+ <p>The <a href="host.html">Host</a> may be configured (via the
+ <code>undeployOldVersions</code>) to remove old versions deployed in this way
+ once they are no longer in use.</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="Naming"><strong>Naming</strong></a></font></td></tr><tr><td><blockquote>
<p>When <code>autoDeploy</code> or <code>deployOnStartup</code> operations
- are performed by a Host, the web application is specified by a context XML
- file in <a href="host.html">Host</a>'s <code>xmlBase</code>
- directory or by a WAR file or a directory file in Host's
- <code>appBase</code> directory.
- In this case the context path is derived from the name of the file that
- is being deployed. Consequently, the context path <strong>may not</strong>
- be defined in a <code>META-INF/context.xml</code> embedded in
- the application. There is, therefore, a close relationship between the
- <em>context path</em> and
- the <em>base file name</em> (the name minus <code>.war</code> or
- <code>.xml</code> extension) of the file.</p>
+ are performed by a Host, the name and context path of the web application are
+ derived from the name(s) of the file(s) that define(s) the web application.
+ Consequently, the context path <strong>may not</strong> be defined in a
+ <code>META-INF/context.xml</code> embedded in the application and there is a
+ close relationship between the <em>context name</em>, <em>context path</em>,
+ <em>context version</em> and the <em>base file name</em> (the name minus any
+ <code>.war</code> or <code>.xml</code> extension) of the file.</p>
- <p>Let us assume that you want to deploy your application to respond to
- requests to URIs starting with certain context path. According to the
- Servlet specification, the context path may be an empty string, or a
- string starting with '/'. The rules to define the names for this context
- path are the following:</p>
+ <p>If no version is specified then the <em>context name</em> is always the
+ same as the <em>context path</em>. If the <em>context path</em> is the empty
+ string then the <em>base name</em> will be ROOT (always in upper case)
+ otherwise the <em>base name</em> will be the <em>context path</em> with the
+ leading '/' removed and any remaining '/' characters replaced with '#'.</p>
- <ul>
- <li>If the context path is a zero length string, the <em>base name</em> is
- <code>"ROOT"</code> (uppercase)</li>
- <li>If the context path is not a zero length string, the <em>base
- name</em> is the context path with the leading '/' removed and any
- remaining '/' characters in the path replaced with '#'.</li>
- </ul>
+ <p>If a version is specified then the <em>context path</em> remains unchanged
+ and both the <em>context name</em> and the <em>base name</em> have the string
+ '##' appended to them followed by the version identifier.</p>
- <p>To help clarify these rules, some examples are given in the following
- table.</p>
+ <p>Some examples of these naming conventions are given below.</p>
<table class="detail-table">
<tr>
<td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Context Path</font></td>
+ <td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Context Version</font></td>
+ <td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Context Name</font></td>
<td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Base File Name</font></td>
+ <td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Example File Names (.xml, .war & directory)</font></td>
</tr>
- <tr><td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo</font></td><td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo</font></td></tr>
<tr>
- <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo/bar</font></td><td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo#bar</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>None</i></font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo.xml, foo.war, foo</font></td>
+ </tr>
+ <tr>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo/bar</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>None</i></font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo/bar</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo#bar</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo#bar.xml, foo#bar.war, foo#bar</font></td>
</tr>
<tr>
<td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>Empty String</i></font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>None</i></font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>Empty String</i></font></td>
<td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">ROOT</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">ROOT.xml, ROOT.war, ROOT</font></td>
+ </tr>
+ <tr>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">42</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo##42</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo##42</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo##42.xml, foo##42.war, foo##42</font></td>
+ </tr>
+ <tr>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo/bar</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">42</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo/bar##42</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo#bar##42</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo#bar##42.xml, foo#bar##42.war, foo#bar##42</font></td>
+ </tr>
+ <tr>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>Empty String</i></font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">42</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">##42</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">ROOT##42</font></td>
+ <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">ROOT##42.xml, ROOT##42.war, ROOT##42</font></td>
</tr>
</table>
+ <p>The version component is treated as a <code>String</code> both for
+ performance reasons and to allow flexibility in versioning schemes. String
+ comparisons are used to determine version order. If version is not specified,
+ it is treated as the empty string.
+ Therefore,
+ <code>foo.war</code> will be treated as an earlier version than
+ <code>foo##11.war</code> and
+ <code>foo##11.war</code> will be treated as an earlier version than
+ <code>foo##2.war</code>. If using a purely numerical versioning scheme it is
+ recommended that zero padding is used so that <code>foo##002.war</code> is
+ treated as an earlier version than <code>foo##011.war</code>.
+ </p>
+
<p>If you want to deploy a WAR file or a directory using a context path that
is not related to the base file name then one of the following options must
be used to prevent double-deployment:
@@ -102,24 +236,23 @@
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Defining a context"><!--()--></a><a name="Defining_a_context"><strong>Defining a context</strong></a></font></td></tr><tr><td><blockquote>
- <p><b>It is NOT recommended to place
- <Context> elements directly in the server.xml file.</b> This
- is because it makes modifying the <strong>Context</strong> configuration
- more invasive since the main <code>conf/server.xml</code> file cannot be
- reloaded without restarting Tomcat.</p>
+ <p><b>It is NOT recommended to place <Context> elements directly in the
+ server.xml file.</b> This is because it makes modifying the
+ <strong>Context</strong> configuration more invasive since the main
+ <code>conf/server.xml</code> file cannot be reloaded without restarting
+ Tomcat.</p>
<p>Individual <strong>Context</strong> elements may be explicitly defined:
</p>
<ul>
<li>In an individual file at <code>/META-INF/context.xml</code> inside the
- application files. In Tomcat 6 this file is automatically copied to
+ application files. Optionally (based on the Host's copyXML attribute)
+ this may be copied to
<code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> and renamed to
- application's base file name plus a ".xml" extension.
- (This automated copying became optional in Tomcat 7).
- </li>
+ application's base file name plus a ".xml" extension.</li>
<li>In individual files (with a ".xml" extension) in the
<code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> directory.
- The context path will be derived from the base name of the file
+ The context path and version will be derived from the base name of the file
(the file name less the .xml extension). This file will always take precedence
over any context.xml file packaged in the web application's META-INF
directory.</li>
@@ -160,7 +293,6 @@
section above for creating a <strong>Context</strong> that has a path
that is not related to the base file name.</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="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>
@@ -168,47 +300,54 @@
<p>All implementations of <strong>Context</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>backgroundProcessorDelay</code></td><td align="left" valign="center">
- <p>This value represents the delay in seconds between the
- invocation of the backgroundProcess method on this context and
- its child containers, including all wrappers.
- Child containers will not be invoked if their delay value is not
- negative (which would mean they are using their own processing
- thread). Setting this to a positive value will cause
- a thread to be spawn. After waiting the specified amount of time,
- the thread will invoke the backgroundProcess method on this host
- and all its child containers. A context will use background
+ <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">allowCasualMultipartParsing</code></td><td align="left" valign="center">
+ <p>Set to true if Tomcat should automatically parse
+ multipart/form-data request bodies when HttpServletRequest.getPart*
+ or HttpServletRequest.getParameter* is called, even when the
+ target servlet isn't marked with the @MultipartConfig annotation
+ (See Servlet Specification 3.0, Section 3.2 for details).
+ Note that any setting other than <code>false</code> causes Tomcat
+ to behave in a way that is not technically spec-compliant.
+ The default is <code>false</code></p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">backgroundProcessorDelay</code></td><td align="left" valign="center">
+ <p>This value represents the delay in seconds between the
+ invocation of the backgroundProcess method on this context and
+ its child containers, including all wrappers.
+ Child containers will not be invoked if their delay value is not
+ negative (which would mean they are using their own processing
+ thread). Setting this to a positive value will cause
+ a thread to be spawn. After waiting the specified amount of time,
+ the thread will invoke the backgroundProcess method on this host
+ and all its child containers. A context will use background
processing to perform session expiration and class monitoring for
- reloading. If not specified, the default value for this attribute is
- -1, which means the context will rely on the background processing
+ reloading. If not specified, the default value for this attribute is
+ -1, which means the context will rely on the background processing
thread of its parent host.</p>
- </td></tr><tr><td align="left" valign="center"><code>className</code></td><td align="left" valign="center">
+ </td></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.Context</code> interface.
If not specified, the standard value (defined below) will be used.</p>
- </td></tr><tr><td align="left" valign="center"><code>cookies</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">containerSciFilter</code></td><td align="left" valign="center">
+ <p>The regular expression that specifies which container provided SCIs
+ should be filtered out and not used for this context. Matching uses
+ <code>java.util.regex.Matcher.find()</code> so the regular expression
+ only has to match a sub-string of the fully qualified class name of the
+ container provided SCI for it to be filtered out. If not specified,
+ no filtering will be applied.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cookies</code></td><td align="left" valign="center">
<p>Set to <code>true</code> if you want cookies to be used for
session identifier communication if supported by the client (this
is the default). Set to <code>false</code> if you want to disable
the use of cookies for session identifier communication, and rely
only on URL rewriting by the application.</p>
- </td></tr><tr><td align="left" valign="center"><code>crossContext</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">crossContext</code></td><td align="left" valign="center">
<p>Set to <code>true</code> if you want calls within this application
to <code>ServletContext.getContext()</code> to successfully return a
request dispatcher for other web applications running on this virtual
host. Set to <code>false</code> (the default) in security
conscious environments, to make <code>getContext()</code> always
return <code>null</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>disableURLRewriting</code></td><td align="left" valign="center">
- <p>Set to <code>true</code> to disable support for using URL rewriting
- to track session IDs for clients of this Context. URL rewriting is an
- optional component of the servlet 2.5 specification but disabling URL
- rewriting will result in non-compliant behaviour since the specification
- requires that there <em>must</em> be a way to retain sessions if the
- client doesn't allow session cookies. If not specified, the
- specification compliant default value of <code>false</code> will be
- used.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>docBase</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">docBase</code></strong></td><td align="left" valign="center">
<p>The <em>Document Base</em> (also known as the <em>Context
Root</em>) directory for this web application, or the pathname
to the web application archive file (if this web application is
@@ -223,20 +362,50 @@
symbolic link will only be effective after a Tomcat restart or
by undeploying and redeploying the context. A context reload is not
sufficient.</p>
- </td></tr><tr><td align="left" valign="center"><code>override</code></td><td align="left" valign="center">
- <p>Set to <code>true</code> to have explicit settings in this
- Context element override any corresponding settings in either the global
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">dispatchersUseEncodedPaths</code></td><td align="left" valign="center">
+ <p>Controls whether paths used in calls to obtain a request dispatcher
+ ares expected to be encoded. This affects both how Tomcat handles calls
+ to obtain a request dispatcher as well as how Tomcat generates paths
+ used to obtain request dispatchers internally. If not specified, the
+ default value of <code>true</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">failCtxIfServletStartFails</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> to have the context fail its startup if any
+ servlet that has load-on-startup >=0 fails its own startup.</p>
+ <p>If not specified, the attribute of the same name in the parent Host
+ configuration is used if specified. Otherwise the default value of
+ <code>false</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">fireRequestListenersOnForwards</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> to fire any configured
+ ServletRequestListeners when Tomcat forwards a request. This is
+ primarily of use to users of CDI frameworks that use
+ ServletRequestListeners to configure the necessary environment for a
+ request. If not specified, the default value of <code>false</code> is
+ used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">logEffectiveWebXml</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> if you want the effective web.xml used for a
+ web application to be logged (at INFO level) when the application
+ starts. The effective web.xml is the result of combining the
+ application's web.xml with any defaults configured by Tomcat and any
+ web-fragment.xml files and annotations discovered. If not specified, the
+ default value of <code>false</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">mapperContextRootRedirectEnabled</code></td><td align="left" valign="center">
+ <p>If enabled, requests for a web application context root will be
+ redirected (adding a trailing slash) if necessary by the Mapper rather
+ than the default Servlet. This is more efficient but has the side effect
+ of confirming that the context path exists. If not specified, the
+ default value of <code>true</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">mapperDirectoryRedirectEnabled</code></td><td align="left" valign="center">
+ <p>If enabled, requests for a web application directory will be
+ redirected (adding a trailing slash) if necessary by the Mapper rather
+ than the default Servlet. This is more efficient but has the side effect
+ of confirming that the directory is exists. If not specified, the
+ default value of <code>false</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">override</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> to ignore any settings in both the global
or <a href="host.html">Host</a> default contexts. By default, settings
- from a default context will be used.</p>
- </td></tr><tr><td align="left" valign="center"><code>privileged</code></td><td align="left" valign="center">
- <p>Set to <code>true</code> to allow this context to use container
- servlets, like the manager servlet. Use of the <code>privileged</code>
- attribute will change the context's parent class loader to be the
- <em>Server</em> class loader rather than the <em>Shared</em> class
- loader. Note that in a default installation, the <em>Common</em> class
- loader is used for both the <em>Server</em> and the <em>Shared</em>
- class loaders.</p>
- </td></tr><tr><td align="left" valign="center"><code>path</code></td><td align="left" valign="center">
+ from a default context will be used but may be overridden by a setting
+ the same attribute explicitly for the Context.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">path</code></td><td align="left" valign="center">
<p>The <em>context path</em> of this web application, which is
matched against the beginning of each request URI to select the
appropriate web application for processing. All of the context paths
@@ -253,7 +422,23 @@
<a href="host.html">Host</a>'s <code>appBase</code> or both
<code>deployOnStartup</code> and <code>autoDeploy</code> are false. If
this rule is not followed, double deployment is likely to result.</p>
- </td></tr><tr><td align="left" valign="center"><code>reloadable</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">preemptiveAuthentication</code></td><td align="left" valign="center">
+ <p>When set to <code>true</code> and the user presents credentials for a
+ resource that is not protected by a security constraint, if the
+ authenticator supports preemptive authentication (the standard
+ authenticators provided with Tomcat do) then the user' credentials
+ will be processed. If not specified, the default of <code>false</code>is
+ used.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">privileged</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> to allow this context to use container
+ servlets, like the manager servlet. Use of the <code>privileged</code>
+ attribute will change the context's parent class loader to be the
+ <em>Server</em> class loader rather than the <em>Shared</em> class
+ loader. Note that in a default installation, the <em>Common</em> class
+ loader is used for both the <em>Server</em> and the <em>Shared</em>
+ class loaders.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">reloadable</code></td><td align="left" valign="center">
<p>Set to <code>true</code> if you want Catalina to monitor classes in
<code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
changes, and automatically reload the web application if a change
@@ -264,63 +449,173 @@
can use the <a href="../manager-howto.html">Manager</a> web
application, however, to trigger reloads of deployed applications
on demand.</p>
- </td></tr><tr><td align="left" valign="center"><code>sessionCookieDomain</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">resourceOnlyServlets</code></td><td align="left" valign="center">
+ <p>Comma separated list of Servlet names (as used in
+ <code>/WEB-INF/web.xml</code>) that expect a resource to be present.
+ Ensures that welcome files associated with Servlets that expect a
+ resource to be present (such as the JSP Servlet) are not used when there
+ is no resource present. This prevents issues caused by the clarification
+ of welcome file mapping in section 10.10 of the Servlet 3.0
+ specification. If the
+ <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
+ <a href="systemprops.html">system property</a> is set to
+ <code>true</code>, the default value of this attribute will be the empty
+ string, else the default value will be <code>jsp</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">sendRedirectBody</code></td><td align="left" valign="center">
+ <p>If <code>true</code>, redirect responses will include a short
+ response body that includes details of the redirect as recommended by
+ RFC 2616. This is disabled by default since including a response body
+ may cause problems for some application component such as compression
+ filters.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionCookieDomain</code></td><td align="left" valign="center">
<p>The domain to be used for all session cookies created for this
- Context. If not set, no domain will be specified for session cookies.
- </p>
- </td></tr><tr><td align="left" valign="center"><code>sessionCookieName</code></td><td align="left" valign="center">
+ context. If set, this overrides any domain set by the web application.
+ If not set, the value specified by the web application, if any, will be
+ used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionCookieName</code></td><td align="left" valign="center">
<p>The name to be used for all session cookies created for this
- Context. If not set, the default of JSESSIONID will be used. Note that
- this default will be overridden by the
- <strong>org.apache.catalina.SESSION_COOKIE_NAME</strong> system
- property.</p>
- </td></tr><tr><td align="left" valign="center"><code>sessionCookiePath</code></td><td align="left" valign="center">
+ context. If set, this overrides any name set by the web application.
+ If not set, the value specified by the web application, if any, will be
+ used, or the name <code>JSESSIONID</code> if the web application does
+ not explicitly set one.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionCookiePath</code></td><td align="left" valign="center">
<p>The path to be used for all session cookies created for this
- Context. If not set, the context path will be used. Note that this will
- be overridden by the <strong>emptySessionPath</strong> attribute on the
- connector used to access this Context.</p>
- </td></tr><tr><td align="left" valign="center"><code>tldValidation</code></td><td align="left" valign="center">
+ context. If set, this overrides any path set by the web application.
+ If not set, the value specified by the web application will be used, or
+ the context path used if the web application does not explicitly set
+ one. To configure all web application to use an empty path (this can be
+ useful for portlet specification implementations) set this attribute to
+ <code>/</code> in the global <code>CATALINA_BASE/conf/context.xml</code>
+ file.</p>
+ <p>Note: Once one web application using
+ <code>sessionCookiePath="/"</code> obtains a session, all
+ subsequent sessions for any other web application in the same host also
+ configured with <code>sessionCookiePath="/"</code> will always
+ use the same session ID. This holds even if the session is invalidated
+ and a new one created. This makes session fixation protection more
+ difficult and requires custom, Tomcat specific code to change the
+ session ID shared by the multiple applications.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionCookiePathUsesTrailingSlash</code></td><td align="left" valign="center">
+ <p>Some browsers, such as Internet Explorer, Safari and Edge, will send
+ a session cookie for a context with a path of <code>/foo</code> with a
+ request to <code>/foobar</code> in violation of RFC6265. This could
+ expose a session ID from an application deployed at <code>/foo</code> to
+ an application deployed at <code>/foobar</code>. If the application
+ deployed at <code>/foobar</code> is untrusted, this could create a
+ security risk. However, it should be noted that RFC 6265, section 8.5
+ makes clear that path alone should not be view as sufficient to prevent
+ untrusted applications accessing cookies from other applications. To
+ mitigate this risk, this attribute may be set to <code>true</code> and
+ Tomcat will add a trailing slash to the path associated with the session
+ cookie so, in the above example, the cookie path becomes /foo/. However,
+ with a cookie path of /foo/, browsers will no longer send the cookie
+ with a request to /foo. This should not be a problem unless there is a
+ servlet mapped to /*. In this case this attribute will need to be set to
+ <code>false</code> to disable this feature. The default value for this
+ attribute is <code>false</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">swallowAbortedUploads</code></td><td align="left" valign="center">
+ <p>Set to false if Tomcat should <b>not</b> read any additional request
+ body data for aborted uploads and instead abort the client connection.
+ This setting is used in the following situations:
+ </p>
+ <ul>
+ <li>the size of the request body is larger than the
+ <code>maxPostSize</code> configured in the connector</li>
+ <li>the size limit of a MultiPart upload is reached</li>
+ <li>the servlet sets the response status to 413 (Request Entity Too
+ Large) </li>
+ </ul>
+ <p>
+ Not reading the additional data will free the request processing thread
+ more quickly. Unfortunately most HTTP clients will not read the response
+ if they can not write the full request.</p>
+ <p>The default is <code>true</code>, so additional data will be
+ read.</p>
+ <p>Note if an error occurs during the request processing that triggers
+ a 5xx response, any unread request data will always be ignored and the
+ client connection will be closed once the error response has been
+ written.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">swallowOutput</code></td><td align="left" valign="center">
+ <p>If the value of this flag is <code>true</code>, the bytes output to
+ System.out and System.err by the web application will be redirected to
+ the web application logger. If not specified, the default value
+ of the flag is <code>false</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">tldValidation</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, the TLD files
- will be XML validated on context startup. If the
+ will be XML validated on context startup. If the
<code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
<a href="systemprops.html">system property</a> is set to
<code>true</code>, the default value of this attribute will be
<code>true</code>, else the default value will be <code>false</code>.
Setting this attribute to <code>true</code> will incur a performance
penalty.</p>
- </td></tr><tr><td align="left" valign="center"><code>useHttpOnly</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">useHttpOnly</code></td><td align="left" valign="center">
<p>Should the HttpOnly flag be set on session cookies to prevent client
side script from accessing the session ID? Defaults to
- <code>false</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>wrapperClass</code></td><td align="left" valign="center">
+ <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">useRelativeRedirects</code></td><td align="left" valign="center">
+ <p>Controls whether HTTP 1.1 and later location headers generated by a
+ call to
+ <code>javax.servlet.http.HttpServletResponse#sendRedirect(String)</code>
+ will use relative or absolute redirects. Relative redirects are more
+ efficient but may not work with reverse proxies that change the context
+ path. It should be noted that it is not recommended to use a reverse
+ proxy to change the context path because of the multiple issues it
+ creates. Absolute redirects should work with reverse proxies that change
+ the context path but may cause issues with the
+ <code>org.apache.catalina.filters.RemoteIpFilter</code> if the filter is
+ changing the scheme and/or port. If the
+ <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
+ <a href="systemprops.html">system property</a> is set to
+ <code>true</code>, the default value of this attribute will be
+ <code>false</code>, else the default value will be <code>true</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">validateClientProvidedNewSessionId</code></td><td align="left" valign="center">
+ <p>When a client provides the ID for a new session, this attribute
+ controls whether that ID is validated. The only use case for using a
+ client provided session ID is to have a common session ID across
+ multiple web applications. Therefore, any client provided session ID
+ should already exist in another web application. If this check is
+ enabled, the client provided session ID will only be used if the session
+ ID exists in at least one other web application for the current host.
+ Note that the following additional tests are always applied,
+ irrespective of this setting:</p>
+ <ul>
+ <li>The session ID is provided by a cookie</li>
+ <li>The session cookie has a path of {@code /}</li>
+ </ul>
+ <p>If not specified, the default value of <code>true</code> will be
+ used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">wrapperClass</code></td><td align="left" valign="center">
<p>Java class name of the <code>org.apache.catalina.Wrapper</code>
implementation class that will be used for servlets managed by this
Context. If not specified, a standard default value will be used.</p>
- </td></tr><tr><td align="left" valign="center"><code>xmlBlockExternal</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">xmlBlockExternal</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, the parsing of
<code>web.xml</code>, <code>web-fragment.xml</code>, <code>*.tld</code>,
<code>*.jspx</code>, <code>*.tagx</code> and <code>tagPlugins.xml</code>
files for this web application will not permit external entities to be
loaded. If not specified, the default value of <code>true</code> will
be used.</p>
- </td></tr><tr><td align="left" valign="center"><code>xmlNamespaceAware</code></td><td align="left" valign="center">
- <p>If the value of this flag is <code>true</code>, the parsing of the
- <code>web.xml</code> file for this web application will be
- namespace-aware. Note that <code>*.tld</code>, <code>*.jspx</code> and
- <code>*.tagx</code> files are always parsed using a namespace-aware
- parser and that the <code>tagPlugins.xml</code> file (if any) is never
- parsed using a namespace-aware parser. Note also that if you turn this
- flag on, you should probably also turn <code>xmlValidation</code> on. If
- the <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">xmlNamespaceAware</code></td><td align="left" valign="center">
+ <p>If the value of this flag is <code>true</code>, the parsing of
+ <code>web.xml</code> and <code>web-fragment.xml</code> files for this
+ web application will be namespace-aware. Note that <code>*.tld</code>,
+ <code>*.jspx</code> and <code>*.tagx</code> files are always parsed
+ using a namespace-aware parser and that the <code>tagPlugins.xml</code>
+ file (if any) is never parsed using a namespace-aware parser. Note also
+ that if you turn this flag on, you should probably also turn
+ <code>xmlValidation</code> on. If the
+ <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
<a href="systemprops.html">system property</a> is set to
<code>true</code>, the default value of this attribute will be
<code>true</code>, else the default value will be <code>false</code>.
Setting this attribute to <code>true</code> will incur a performance
penalty.</p>
- </td></tr><tr><td align="left" valign="center"><code>xmlValidation</code></td><td align="left" valign="center">
- <p>If the value of this flag is <code>true</code>, the parsing of the
- <code>web.xml</code> file for this web application will use a validating
- parser. If the
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">xmlValidation</code></td><td align="left" valign="center">
+ <p>If the value of this flag is <code>true</code>, the parsing of
+ <code>web.xml</code> and <code>web-fragment.xml</code> files for this
+ web application will use a validating parser. If the
<code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
<a href="systemprops.html">system property</a> is set to
<code>true</code>, the default value of this attribute will be
@@ -339,7 +634,38 @@
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>allowLinking</code></td><td align="left" valign="center">
+ <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">addWebinfClassesResources</code></td><td align="left" valign="center">
+ <p>This attribute controls if, in addition to static resources being
+ served from <code>META-INF/resources</code> inside web application JAR
+ files, static resources are also served from
+ <code>WEB-INF/classes/META-INF/resources</code>. This only applies to
+ web applications with a major version of 3 or higher. Since this is a
+ proprietary extension to the Servlet 3 specification, it is disabled by
+ default. To enable this feature, set the attribute to <code>true</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">aliases</code></td><td align="left" valign="center">
+ <p>This attribute provides a list of external locations from which to
+ load resources for this context. The list of aliases should be of
+ the form <code>"/aliasPath1=docBase1,/aliasPath2=docBase2"</code> where
+ <code>aliasPathN</code> must include a leading '/' and
+ <code>docBaseN</code> must be an absolute path to either a .war file or
+ a directory.</p>
+ <p>Whitespace is permitted around both the <code>,</code> and
+ <code>=</code> delimiters, and will be trimmed. Therefore, an aliases
+ attribute with the value <code>"/aliasPath1 = docBase1,<br>
+ /aliasPath2= docBase2"</code> is equivalent to
+ <code>"/aliasPath1=docBase1,/aliasPath2=docBase2"</code></p>
+ <p>A resource will be searched for in the first <code>docBaseN</code>
+ for which <code>aliasPathN</code> is a leading path segment of the
+ resource. If there is no such alias, then the resource will be searched
+ in the usual way.</p>
+ <p>Using '/' as an aliasPath is not allowed. Consider using
+ <code>docBase</code> instead.</p>
+ <p>These external locations will not be emptied if the context
+ is un-deployed.</p>
+ <p>A more powerful feature (for development only) is
+ <a href="#Virtual_webapp">Virtual webapp</a>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">allowLinking</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, symlinks will be
allowed inside the web application, pointing to resources outside the
web application base path. If not specified, the default value
@@ -348,7 +674,7 @@
(or any other OS which does not have a case sensitive filesystem),
as it will disable case sensitivity checks, allowing JSP source code
disclosure, among other security problems.</b></p>
- </td></tr><tr><td align="left" valign="center"><code>antiJARLocking</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">antiJARLocking</code></td><td align="left" valign="center">
<p>If true, the Tomcat classloader will take extra measures to avoid
JAR file locking when resources are accessed inside JARs through URLs.
This will impact startup time of applications, but could prove to be
@@ -359,13 +685,13 @@
<code>antiResourceLocking</code> and therefore, to prevent duplicate
work and possible issues, only one of these attributes should be set
to <code>true</code> at any one time.</p>
- </td></tr><tr><td align="left" valign="center"><code>antiResourceLocking</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">antiResourceLocking</code></td><td align="left" valign="center">
<p>If true, Tomcat will prevent any file locking.
- This will significantly impact startup time of applications,
- but allows full webapp hot deploy and undeploy on platforms
+ This will significantly impact startup time of applications,
+ but allows full webapp hot deploy and undeploy on platforms
or configurations where file locking can occur.
If not specified, the default value is <code>false</code>.</p>
-
+
<p><code>antiJARLocking</code> is a subset of
<code>antiResourceLocking</code> and therefore, to prevent duplicate
work and possible issues, only one of these attributes should be set
@@ -373,44 +699,34 @@
<p>Please note that setting this to <code>true</code> has some side
effects, including the disabling of JSP reloading in a running server:
- see <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=37668">
+ see <a href="http://bz.apache.org/bugzilla/show_bug.cgi?id=37668">
Bugzilla 37668</a>.</p>
<p>Please note that setting this flag to true in applications that are
outside the appBase for the Host (the <code>webapps</code> directory
by default) will cause the application to be <strong>deleted</strong> on
- Tomcat shutdown. You probably don't want to do this, so think twice
+ Tomcat shutdown. You probably don't want to do this, so think twice
before setting antiResourceLocking=true on a webapp that's outside the
appBase for its Host.</p>
- </td></tr><tr><td align="left" valign="center"><code>cacheMaxSize</code></td><td align="left" valign="center">
- <p>Maximum size of the static resource cache in kilobytes.
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cacheMaxSize</code></td><td align="left" valign="center">
+ <p>Maximum size of the static resource cache in kilobytes.
If not specified, the default value is <code>10240</code>
(10 megabytes).</p>
- </td></tr><tr><td align="left" valign="center"><code>cacheObjectMaxSize</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cacheObjectMaxSize</code></td><td align="left" valign="center">
<p>Maximum size of the static resource that will be placed in the cache.
If not specified, the default value is <code>512</code>
(512 kilobytes). If this value is greater than
<code>cacheMaxSize/20</code> it will be reduced to
<code>cacheMaxSize/20</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>cacheTTL</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cacheTTL</code></td><td align="left" valign="center">
<p>Amount of time in milliseconds between cache entries revalidation.
- If not specified, the default value is <code>5000</code>
+ If not specified, the default value is <code>5000</code>
(5 seconds).</p>
- </td></tr><tr><td align="left" valign="center"><code>cachingAllowed</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cachingAllowed</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, the cache for static
resources will be used. If not specified, the default value
of the flag is <code>true</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>caseSensitive</code></td><td align="left" valign="center">
- <p><strong>Deprecated.</strong> This option is removed in Tomcat 7
- onwards where the default of <code>true</code> is always used.</p>
- <p>If the value of this flag is <code>false</code>, all case sensitivity
- checks will be disabled. If not
- specified, the default value of the flag is <code>true</code>.</p>
- <p><b>NOTE: This flag MUST NOT be set to false on the Windows platform
- (or any other OS which does not have a case sensitive filesystem),
- as it will disable case sensitivity checks, allowing JSP source code
- disclosure, among other security problems.</b></p>
- </td></tr><tr><td align="left" valign="center"><code>clearReferencesHttpClientKeepAliveThread</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">clearReferencesHttpClientKeepAliveThread</code></td><td align="left" valign="center">
<p>If <code>true</code> and an <code>sun.net.www.http.HttpClient</code>
keep-alive timer thread has been started by this web application and is
still running, Tomcat will change the context class loader for that
@@ -420,49 +736,95 @@
keep-alives all expire however, on a busy system that might not happen
for some time. If not specified, the default value of
<code>true</code> will be used.</p>
- </td></tr><tr><td align="left" valign="center"><code>clearReferencesStopThreads</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">clearReferencesRmiTargets</code></td><td align="left" valign="center">
+ <p>If <code>true</code>, Tomcat looks for memory leaks associated with
+ RMI Targets and clears any it finds. This feature uses reflection to
+ identify the leaks and therefore requires that the command line option
+ <code>-XaddExports:java.rmi/sun.rmi.transport=ALL-UNNAMED</code> is set
+ when running on Java 9 and above. Applications without memory leaks
+ should operate correctly with this attribute set to <code>false</code>.
+ If not specified, the default value of <code>true</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">clearReferencesStatic</code></td><td align="left" valign="center">
+ <p>If <code>true</code>, Tomcat attempts to null out any static or final
+ fields from loaded classes when a web application is stopped as a work
+ around for apparent garbage collection bugs and application coding
+ errors. There have been some issues reported with log4j when this
+ is <code>true</code>. Applications without memory leaks using recent
+ JVMs should operate correctly with this attribute set to
+ <code>false</code>. If not specified, the default value of
+ <code>false</code> will be used.</p>
+ <p>This attribute has been deprecated and will be removed in Tomcat
+ 8.5.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">clearReferencesStopThreads</code></td><td align="left" valign="center">
<p>If <code>true</code>, Tomcat attempts to terminate threads that have
been started by the web application. Stopping threads is performed via
the deprecated (for good reason) <code>Thread.stop()</code> method and
is likely to result in instability. As such, enabling this should be
viewed as an option of last resort in a development environment and is
not recommended in a production environment. If not specified, the
- default value of <code>false</code> will be used.</p>
- </td></tr><tr><td align="left" valign="center"><code>clearReferencesStopTimerThreads</code></td><td align="left" valign="center">
+ default value of <code>false</code> will be used. If this feature is
+ enabled, web applications may take up to two seconds longer to stop as
+ executor threads are given up to two seconds to stop gracefully before
+ <code>Thread.stop()</code> is called on any remaining threads.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">clearReferencesStopTimerThreads</code></td><td align="left" valign="center">
<p>If <code>true</code>, Tomcat attempts to terminate
<code>java.util.Timer</code> threads that have been started by the web
application. Unlike standard threads, timer threads can be stopped
safely although there may still be side-effects for the application. If
not specified, the default value of <code>false</code> will be used.</p>
- </td></tr><tr><td align="left" valign="center"><code>clearReferencesThreadLocals</code></td><td align="left" valign="center">
- <p>If <code>true</code>, Tomcat attempts to clear any ThreadLocal
- objects that are instances of classes loaded by this class loader.
- Failure to remove any such objects will result in a memory leak on web
- application stop, undeploy or reload. If not specified, the default
- value of <code>false</code> will be used since the clearing of the
- ThreadLocal objects is not performed in a thread-safe manner.</p>
- </td></tr><tr><td align="left" valign="center"><code>processTlds</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">copyXML</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> if you want a context XML descriptor
+ embedded inside the application (located at
+ <code>/META-INF/context.xml</code>) to be copied to the owning
+ <a href="host.html">Host</a>'s <code>xmlBase</code> when the application
+ is deployed. On subsequent starts, the copied context XML descriptor
+ will be used in preference to any context XML descriptor embedded inside
+ the application even if the descriptor embedded inside the application
+ is more recent. The flag's value defaults to <code>false</code>. Note if
+ the <strong>deployXML</strong> attribute of the owning
+ <a href="host.html">Host</a> is <code>false</code> or if the
+ <strong>copyXML</strong> attribute of the owning
+ <a href="host.html">Host</a> is <code>true</code>, this attribute will
+ have no effect.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">jndiExceptionOnFailedWrite</code></td><td align="left" valign="center">
+ <p>If <code>true</code>, any attempt by an application to modify the
+ provided JNDI context with a call to bind(), unbind(),
+ createSubContext(), destroySubContext() or close() will trigger a
+ <code>javax.naming.OperationNotSupportedException</code> as required by
+ section EE.5.3.4 of the Java EE specification. This exception can be
+ disabled by setting this attribute to true in which case any calls to
+ modify the JNDI context will return <b>without</b> making any changes
+ and methods that return values will return <code>null</code>. If not
+ specified, the specification compliant default of <code>true</code> will
+ be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">processTlds</code></td><td align="left" valign="center">
<p>Whether the context should process TLDs on startup. The default
is true. The false setting is intended for special cases
that know in advance TLDs are not part of the webapp.</p>
- </td></tr><tr><td align="left" valign="center"><code>swallowOutput</code></td><td align="left" valign="center">
- <p>If the value of this flag is <code>true</code>, the bytes output to
- System.out and System.err by the web application will be redirected to
- the web application logger. If not specified, the default value
- of the flag is <code>false</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>unloadDelay</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">renewThreadsWhenStoppingContext</code></td><td align="left" valign="center">
+ <p>If <code>true</code>, when this context is stopped, Tomcat renews all
+ the threads from the thread pool that was used to serve this context.
+ This also requires that the
+ <code>ThreadLocalLeakPreventionListener</code> be configured in
+ <code>server.xml</code> and that the <code>threadRenewalDelay</code>
+ property of the <code>Executor</code> be >=0. If not specified, the
+ default value of <code>true</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">unloadDelay</code></td><td align="left" valign="center">
<p>Number of ms that the container will wait for servlets to unload.
If not specified, the default value is <code>2000</code> ms.</p>
- </td></tr><tr><td align="left" valign="center"><code>unpackWAR</code></td><td align="left" valign="center">
- <p>If true, Tomcat will unpack all compressed web applications before
- running them.
- If not specified, the default value is <code>true</code>.</p>
- </td></tr><tr><td align="left" valign="center"><code>useNaming</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">unpackWAR</code></td><td align="left" valign="center">
+ <p>If <code>false</code>, the <strong>unpackWARs</strong> attribute of
+ the owning <a href="host.html">Host</a> will be overridden and the WAR
+ file will not be unpacked. If <code>true</code>, the value of the owning
+ <a href="host.html">Host</a>'s <strong>unpackWARs</strong>
+ attribute will determine if the WAR is unpacked. If not specified, the
+ default value is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">useNaming</code></td><td align="left" valign="center">
<p>Set to <code>true</code> (the default) to have Catalina enable a
JNDI <code>InitialContext</code> for this web application that is
compatible with Java2 Enterprise Edition (J2EE) platform
conventions.</p>
- </td></tr><tr><td align="left" valign="center"><code>workDir</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">workDir</code></td><td align="left" valign="center">
<p>Pathname to a scratch directory to be provided by this Context
for temporary read-write use by servlets within the associated web
application. This directory will be made visible to servlets in the
@@ -500,9 +862,9 @@
Configure the resource manager that will be used to access the static
resources associated with this web application. Normally, the
default configuration of the resource manager will be sufficient.</li>
- <li><strong>WatchedResource</strong> - The auto deployer will monitor the
+ <li><strong>WatchedResource</strong> - The auto deployer will monitor the
specified static resource of the web application for updates, and will
- reload the web application if is is updated. The content of this element
+ reload the web application if it is updated. The content of this element
must be a string.</li>
</ul>
@@ -511,7 +873,7 @@
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Logging"><strong>Logging</strong></a></font></td></tr><tr><td><blockquote>
- <p>A context is associated with the
+ <p>A context is associated with the
<code>org.apache.catalina.core.ContainerBase.[enginename].[hostname].[path]</code>
log category. Note that the brackets are actually part of the name, don't omit them.</p>
@@ -532,17 +894,15 @@
<a href="host.html">Host</a>, or <a href="context.html">Context</a>
by nesting a <a href="valve.html">Valve</a> element like this:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<Context>
+<div class="codeBox"><pre><code><Context>
...
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="localhost_access_log." suffix=".txt"
pattern="common"/>
...
-</Context>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</Context></code></pre></div>
- <p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
+ <p>See <a href="valve.html#Access_Logging">Access Logging Valves</a>
for more information on the configuration attributes that are
supported.</p>
@@ -555,7 +915,7 @@
the following configuration steps occur automatically when Catalina
is started, or whenever this web application is reloaded. No special
configuration is required to enable this feature.</p>
-
+
<ul>
<li>If you have not declared your own <a href="loader.html">Loader</a>
element, a standard web application class loader will be configured.
@@ -586,41 +946,37 @@
web application as servlet context initialization parameters by nesting
<code><Parameter></code> elements inside this element. For
example, you can create an initialization parameter like this:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<Context>
+<div class="codeBox"><pre><code><Context>
...
<Parameter name="companyName" value="My Company, Incorporated"
override="false"/>
...
-</Context>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</Context></code></pre></div>
<p>This is equivalent to the inclusion of the following element in the
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<context-param>
+<div class="codeBox"><pre><code><context-param>
<param-name>companyName</param-name>
<param-value>My Company, Incorporated</param-value>
-</context-param>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</context-param></code></pre></div>
<p>but does <em>not</em> require modification of the deployment descriptor
to customize this value.</p>
<p>The valid attributes for a <code><Parameter></code> element
are as follows:</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>description</code></td><td align="left" valign="center">
+ <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">description</code></td><td align="left" valign="center">
<p>Optional, human-readable description of this context
initialization parameter.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">name</code></strong></td><td align="left" valign="center">
<p>The name of the context initialization parameter to be created.</p>
- </td></tr><tr><td align="left" valign="center"><code>override</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">override</code></td><td align="left" valign="center">
<p>Set this to <code>false</code> if you do <strong>not</strong> want
a <code><context-param></code> for the same parameter name,
found in the web application deployment descriptor, to override the
value specified here. By default, overrides are allowed.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>value</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">value</code></strong></td><td align="left" valign="center">
<p>The parameter value that will be presented to the application
when requested by calling
<code>ServletContext.getInitParameter()</code>.</p>
@@ -635,51 +991,43 @@
web application as environment entry resources, by nesting
<code><Environment></code> entries inside this element. For
example, you can create an environment entry like this:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<Context>
+<div class="codeBox"><pre><code><Context>
...
<Environment name="maxExemptions" value="10"
type="java.lang.Integer" override="false"/>
...
-</Context>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</Context></code></pre></div>
<p>This is equivalent to the inclusion of the following element in the
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<env-entry>
+<div class="codeBox"><pre><code><env-entry>
<env-entry-name>maxExemptions</env-entry-name>
<env-entry-value>10</env-entry-value>
<env-entry-type>java.lang.Integer</env-entry-type>
-</env-entry>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</env-entry></code></pre></div>
<p>but does <em>not</em> require modification of the deployment descriptor
to customize this value.</p>
<p>The valid attributes for an <code><Environment></code> element
are as follows:</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>description</code></td><td align="left" valign="center">
+ <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">description</code></td><td align="left" valign="center">
<p>Optional, human-readable description of this environment entry.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">name</code></strong></td><td align="left" valign="center">
<p>The name of the environment entry to be created, relative to the
<code>java:comp/env</code> context.</p>
- </td></tr><tr><td align="left" valign="center"><code>override</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">override</code></td><td align="left" valign="center">
<p>Set this to <code>false</code> if you do <strong>not</strong> want
an <code><env-entry></code> for the same environment entry name,
found in the web application deployment descriptor, to override the
value specified here. By default, overrides are allowed.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">type</code></strong></td><td align="left" valign="center">
<p>The fully qualified Java class name expected by the web application
- for this environment entry. Must be one of the legal values for
+ for this environment entry. Must be a legal value for
<code><env-entry-type></code> in the web application deployment
- descriptor: <code>java.lang.Boolean</code>,
- <code>java.lang.Byte</code>, <code>java.lang.Character</code>,
- <code>java.lang.Double</code>, <code>java.lang.Float</code>,
- <code>java.lang.Integer</code>, <code>java.lang.Long</code>,
- <code>java.lang.Short</code>, or <code>java.lang.String</code>.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>value</code></strong></td><td align="left" valign="center">
+ descriptor.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">value</code></strong></td><td align="left" valign="center">
<p>The parameter value that will be presented to the application
when requested from the JNDI context. This value must be convertable
to the Java type defined by the <code>type</code> attribute.</p>
@@ -695,18 +1043,16 @@
nesting a <strong>Listener</strong> element inside this element. The
class name you specify must implement the
<code>org.apache.catalina.LifecycleListener</code> interface, and
- the class must be packaged in a jar and placed in the
- <code>$CATALINA_HOME/lib</code> directory.
+ the class must be packaged in a jar and placed in the
+ <code>$CATALINA_HOME/lib</code> directory.
It will be notified about the occurrence of the corresponding
lifecycle events. Configuration of such a listener looks like this:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<Context>
+<div class="codeBox"><pre><code><Context>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
-</Context>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</Context></code></pre></div>
<p>Note that a Listener can have any number of additional properties
that may be configured from this element. Attribute names are matched
@@ -722,25 +1068,23 @@
incoming request directed to the surrounding
<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
<a href="context.html">Context</a> element. The remote address or name
- will be checked against a configured list of "accept" and/or "deny"
+ will be checked against configured "accept" and/or "deny"
filters, which are defined using <code>java.util.regex</code> Regular
Expression syntax. Requests that come from locations that are
not accepted will be rejected with an HTTP "Forbidden" error.
Example filter declarations:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<Context>
+<div class="codeBox"><pre><code><Context>
...
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow=".*\.mycompany\.com|www\.yourcompany\.com"/>
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
deny="192\.168\.1\.\d+"/>
...
-</Context>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</Context></code></pre></div>
- <p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
- and <a href="valve.html#Remote Host Filter">Remote Host Filter</a> for
+ <p>See <a href="valve.html#Remote_Address_Filter">Remote Address Filter</a>
+ and <a href="valve.html#Remote_Host_Filter">Remote Host Filter</a> for
more information about the configuration options that are supported.</p>
</blockquote></td></tr></table>
@@ -752,31 +1096,27 @@
to be returned for JNDI lookups of <code><resource-ref></code> and
<code><resource-env-ref></code> elements in the web application
deployment descriptor. You <strong>MUST</strong> also define
- the needed resource parameters as attributes of the <code>Resource</code>
- element, to configure the object factory to be used (if not known to Tomcat
+ the needed resource parameters as attributes of the <code>Resource</code>
+ element, to configure the object factory to be used (if not known to Tomcat
already), and the properties used to configure that object factory.</p>
<p>For example, you can create a resource definition like this:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<Context>
+<div class="codeBox"><pre><code><Context>
...
<Resource name="jdbc/EmployeeDB" auth="Container"
type="javax.sql.DataSource"
description="Employees Database for HR Applications"/>
...
-</Context>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</Context></code></pre></div>
<p>This is equivalent to the inclusion of the following element in the
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<resource-ref>
+<div class="codeBox"><pre><code><resource-ref>
<description>Employees Database for HR Applications</description>
<res-ref-name>jdbc/EmployeeDB</res-ref-name>
<res-ref-type>javax.sql.DataSource</res-ref-type>
<res-auth>Container</res-auth>
-</resource-ref>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</resource-ref></code></pre></div>
<p>but does <em>not</em> require modification of the deployment
descriptor to customize this value.</p>
@@ -784,9 +1124,9 @@
<p>The valid attributes for a <code><Resource></code> element
are as follows:</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>auth</code></td><td align="left" valign="center">
+ <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">auth</code></td><td align="left" valign="center">
<p>Specify whether the web Application code signs on to the
- corresponding resource manager programatically, or whether the
+ corresponding resource manager programmatically, or whether the
Container will sign on to the resource manager on behalf of the
application. The value of this attribute must be
<code>Application</code> or <code>Container</code>. This
@@ -794,17 +1134,37 @@
will use a <code><resource-ref></code> element in the web
application deployment descriptor, but is optional if the
application uses a <code><resource-env-ref></code> instead.</p>
- </td></tr><tr><td align="left" valign="center"><code>description</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">closeMethod</code></td><td align="left" valign="center">
+ <p>Name of the zero-argument method to call on a singleton resource when
+ it is no longer required. This is intended to speed up clean-up of
+ resources that would otherwise happen as part of garbage collection.
+ This attribute is ignored if the <code>singleton</code> attribute is
+ false. If not specified, no default is defined and no close method will
+ be called.</p>
+ <p>For Apache Commons DBCP and Apache Tomcat JDBC connection pools
+ you can use <code>closeMethod="close"</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">description</code></td><td align="left" valign="center">
<p>Optional, human-readable description of this resource.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">name</code></strong></td><td align="left" valign="center">
<p>The name of the resource to be created, relative to the
<code>java:comp/env</code> context.</p>
- </td></tr><tr><td align="left" valign="center"><code>scope</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">scope</code></td><td align="left" valign="center">
<p>Specify whether connections obtained through this resource
manager can be shared. The value of this attribute must be
<code>Shareable</code> or <code>Unshareable</code>. By default,
connections are assumed to be shareable.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">singleton</code></td><td align="left" valign="center">
+ <p>Specify whether this resource definition is for a singleton resource,
+ i.e. one where there is only a single instance of the resource. If this
+ attribute is <code>true</code>, multiple JNDI lookups for this resource
+ will return the same object. If this attribute is <code>false</code>,
+ multiple JNDI lookups for this resource will return different objects.
+ This attribute must be <code>true</code> for
+ <code>javax.sql.DataSource</code> resources to enable JMX registration
+ of the DataSource. The value of this attribute must be <code>true</code>
+ or <code>false</code>. By default, this attribute is <code>true</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">type</code></strong></td><td align="left" valign="center">
<p>The fully qualified Java class name expected by the web
application when it performs a lookup for this resource.</p>
</td></tr></table>
@@ -816,33 +1176,31 @@
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Resource Links"><!--()--></a><a name="Resource_Links"><strong>Resource Links</strong></a></font></td></tr><tr><td><blockquote>
<p>This element is used to create a link to a global JNDI resource. Doing
- a JNDI lookup on the link name will then return the linked global
+ a JNDI lookup on the link name will then return the linked global
resource.</p>
<p>For example, you can create a resource link like this:</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<Context>
+<div class="codeBox"><pre><code><Context>
...
<ResourceLink name="linkToGlobalResource"
global="simpleValue"
type="java.lang.Integer"
...
-</Context>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+</Context></code></pre></div>
<p>The valid attributes for a <code><ResourceLink></code> element
are as follows:</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>global</code></strong></td><td align="left" valign="center">
- <p>The name of the linked global resource in the
+ <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">global</code></strong></td><td align="left" valign="center">
+ <p>The name of the linked global resource in the
global JNDI context.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">name</code></strong></td><td align="left" valign="center">
<p>The name of the resource link to be created, relative to the
<code>java:comp/env</code> context.</p>
- </td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">type</code></strong></td><td align="left" valign="center">
<p>The fully qualified Java class name expected by the web
application when it performs a lookup for this resource link.</p>
- </td></tr><tr><td align="left" valign="center"><code>factory</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">factory</code></td><td align="left" valign="center">
<p>The fully qualified Java class name for the class creating these objects.
This class should implement the <code>javax.naming.spi.ObjectFactory</code> interface.</p>
</td></tr></table>
@@ -854,13 +1212,13 @@
Under the hood, what happens is that a call to <a href="http://docs.oracle.com/javase/6/docs/api/javax/sql/DataSource.html#getConnection()"><code>getConnection()</code></a>
is simply translated to a call <a href="http://docs.oracle.com/javase/6/docs/api/javax/sql/DataSource.html#getConnection(java.lang.String,%20java.lang.String)">
<code>getConnection(username, password)</code></a> on the global data source. This is an easy way to get code to be transparent to what schemas are being used,
- yet be able to control connections (or pools) in the global configuration.
+ yet be able to control connections (or pools) in the global configuration.
</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>username</code></td><td align="left" valign="center">
+ <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">username</code></td><td align="left" valign="center">
<p><code>username</code> value for the <code>getConnection(username, password)</code>
call on the linked global DataSource.
</p>
- </td></tr><tr><td align="left" valign="center"><code>password</code></td><td align="left" valign="center">
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">password</code></td><td align="left" valign="center">
<p><code>password</code> value for the <code>getConnection(username, password)</code>
call on the linked global DataSource.
</p>
@@ -871,13 +1229,11 @@
<a href="http://commons.apache.org/dbcp/">Apache Commons DBCP</a> pool that
Tomcat uses by default does not support it. See its Javadoc for
<code>BasicDataSource</code> class.
-<a href="http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html">Apache Tomcat JDBC pool</a>
-(included with Tomcat 7 and later) does support it,
+<a href="../jdbc-pool.html">Apache Tomcat JDBC pool</a> does support it,
but by default this support is disabled and can be enabled by
<code>alternateUsernameAllowed</code> attribute. See its documentation
-for details. The example below uses Apache Tomcat JDBC pool.</p>
-<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
-<GlobalNamingResources>
+for details.</p>
+<div class="codeBox"><pre><code><GlobalNamingResources>
...
<Resource name="sharedDataSource"
global="sharedDataSource"
@@ -892,7 +1248,7 @@
<Context path="/foo"...>
...
- <ResourceLink
+ <ResourceLink
name="appDataSource"
global="sharedDataSource"
type="javax.sql.DataSource"
@@ -903,35 +1259,140 @@
</Context>
<Context path="/bar"...>
...
- <ResourceLink
+ <ResourceLink
name="appDataSource"
global="sharedDataSource"
type="javax.sql.DataSource"
...
-</Context>
-</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
- <p>When a request for <code>getConnection()</code> is made in the <code>/foo</code> context, the request is translated into
- <code>getConnection("foo","foopass")</code>, while a request in the <code>/bar</code> gets passed straight through.</p>
+</Context></code></pre></div>
+ <p>When a request for <code>getConnection()</code> is made in the
+ <code>/foo</code> context, the request is translated into
+ <code>getConnection("foo","foopass")</code>,
+ while a request in the <code>/bar</code> gets passed straight through.</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="Transaction"><strong>Transaction</strong></a></font></td></tr><tr><td><blockquote>
<p>You can declare the characteristics of the UserTransaction
- to be returned for JNDI lookup for <code>java:comp/UserTransaction</code>.
+ to be returned for JNDI lookup for <code>java:comp/UserTransaction</code>.
You <strong>MUST</strong> define an object factory class to instantiate
- this object as well as the needed resource parameters as attributes of the
- <code>Transaction</code>
+ this object as well as the needed resource parameters as attributes of the
+ <code>Transaction</code>
element, and the properties used to configure that object factory.</p>
<p>The valid attributes for the <code><Transaction></code> element
are as follows:</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>factory</code></strong></td><td align="left" valign="center">
+ <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">factory</code></strong></td><td align="left" valign="center">
<p>The class name for the JNDI object factory.</p>
</td></tr></table>
</blockquote></td></tr></table>
-</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
- Copyright © 1999-2014, Apache Software Foundation
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Virtual webapp"><!--()--></a><a name="Virtual_webapp"><strong>Virtual webapp</strong></a></font></td></tr><tr><td><blockquote>
+ <p>During development it may be more productive to avoid copying files (static
+ resources, JSPs, classes, jars...) and configure tomcat to use files from their
+ source locations. To do that, several customisations of the context configuration are
+ required:</p>
+ <ul>
+ <li>The <code>VirtualDirContext</code> implementation of
+ <a href="resources.html">Resources</a></li>
+ <li>The <code>VirtualWebappLoader</code> implementation of
+ <a href="loader.html">Loader</a></li>
+ <li><code>scanAllDirectories="true"</code> on the <a href="jar-scanner.html">JarScanner</a></li>
+ </ul>
+ <p>To illustrate this feature, here is an example of a standard maven webapp source tree:</p>
+
+<div class="codeBox"><pre><code>mywebapp/
+ src/
+ main/
+ java/
+ resources/
+ webapp/
+ WEB-INF/
+ classes/
+ target/
+ classes/
+</code></pre></div>
+
+ <p>To deploy such an application (assuming it also uses the log4j maven artefact),
+ the context configuration looks like:</p>
+
+<div class="codeBox"><pre class="wrap"><code><Context path="/mywebapp" docBase="/Users/theuser/mywebapp/src/main/webapp">
+ <Resources className="org.apache.naming.resources.VirtualDirContext"
+ extraResourcePaths="/WEB-INF/classes=/Users/theuser/mywebapp/target/classes" />
+ <Loader className="org.apache.catalina.loader.VirtualWebappLoader"
+ virtualClasspath="/Users/theuser/mywebapp/target/classes;/Users/theuser/.m2/repository/log4j/log4j/1.2.15/log4j-1.2.15.jar" />
+ <JarScanner scanAllDirectories="true" />
+</Context>
+</code></pre></div>
+
+ <p>Here is another example where the webapp serves pictures under /pictures and movies
+ under /movies and also depends on another maven project mylib that would normally
+ produce a jar to be packaged in WEB-INF/lib:</p>
+
+<div class="codeBox"><pre><code>mylib/
+ src/
+ main/
+ java/
+ resources/
+ META-INF/
+ resources/
+ target/
+ classes/
+mymovies/
+mypictures/
+mywebapp/
+ src/
+ main/
+ java/
+ resources/
+ webapp/
+ WEB-INF/
+ classes/
+ target/
+ classes/
+</code></pre></div>
+
+ <p>The configuration is:</p>
+
+<div class="codeBox"><pre class="wrap"><code><Context path="/mywebapp" docBase="/Users/theuser/mywebapp/src/main/webapp">
+ <Resources className="org.apache.naming.resources.VirtualDirContext"
+ extraResourcePaths="/WEB-INF/classes=/Users/theuser/mywebapp/target/classes,/pictures=/Users/theuser/mypictures,/movies=/Users/theuser/mymovies" />
+ <Loader className="org.apache.catalina.loader.VirtualWebappLoader"
+ virtualClasspath="/Users/theuser/mywebapp/target/classes;/Users/theuser/mylib/target/classes;/Users/theuser/.m2/repository/log4j/log4j/1.2.15/log4j-1.2.15.jar" />
+ <JarScanner scanAllDirectories="true" />
+</Context>
+</code></pre></div>
+
+ <p>Note that resources in mylib/target/classes/META-INF/resources/ are mapped to / as
+ required by servlet 3 specification.</p>
+ </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/context.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>
\ No newline at end of file