Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / 6266f996613ae5631b7288523f895b36e30fe5af / . / tomcat-cas / webapps / docs / config / context.html
blob: 04ab44f808c683eb949497bef6f1874404c8146d [file] [log] [blame]
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1<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">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4</style><style type="text/css">
5code {background-color:rgb(224,255,255);padding:0 0.1em;}
6code.attributeName, code.propertyName {background-color:transparent;}
7
8
9table {
10 border-collapse: collapse;
11 text-align: left;
12}
13table *:not(table) {
14 /* Prevent border-collapsing for table child elements like <div> */
15 border-collapse: separate;
16}
17
18th {
19 text-align: left;
20}
21
22
23div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
24 background-color: transparent;
25}
26div.codeBox {
27 overflow: auto;
28 margin: 1em 0;
29}
30div.codeBox pre {
31 margin: 0;
32 padding: 4px;
33 border: 1px solid #999;
34 border-radius: 5px;
35 background-color: #eff8ff;
36 display: table; /* To prevent <pre>s from taking the complete available width. */
37 /*
38 When it is officially supported, use the following CSS instead of display: table
39 to prevent big <pre>s from exceeding the browser window:
40 max-width: available;
41 width: min-content;
42 */
43}
44
45div.codeBox pre.wrap {
46 white-space: pre-wrap;
47}
48
49
50table.defaultTable tr, table.detail-table tr {
51 border: 1px solid #CCC;
52}
53
54table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
55 background-color: #FAFBFF;
56}
57
58table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
59 background-color: #EEEFFF;
60}
61
62table.defaultTable th, table.detail-table th {
63 background-color: #88b;
64 color: #fff;
65}
66
67table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
68 padding: 5px 8px;
69}
70
71
72p.notice {
73 border: 1px solid rgb(255, 0, 0);
74 background-color: rgb(238, 238, 238);
75 color: rgb(0, 51, 102);
76 padding: 0.5em;
77 margin: 1em 2em 1em 1em;
78}
79</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="
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]80 The Apache Tomcat Servlet/JSP Container
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]81 " 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>
82<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>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]83</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>
84
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]85 <p><em>
86 The description below uses the variable name $CATALINA_BASE to refer the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]87 base directory against which most relative paths are resolved. If you have
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]88 not configured Tomcat for multiple instances by setting a CATALINA_BASE
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]89 directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]90 the directory into which you have installed Tomcat.
91 </em></p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]92
93 <p>The <strong>Context</strong> element represents a <em>web
94 application</em>, which is run within a particular virtual host.
95 Each web application is based on a <em>Web Application Archive</em>
96 (WAR) file, or a corresponding directory containing the corresponding
97 unpacked contents, as described in the Servlet Specification (version
98 2.2 or later). For more information about web application archives,
99 you can download the
100 <a href="http://wiki.apache.org/tomcat/Specifications">Servlet
101 Specification</a>, and review the Tomcat
102 <a href="../appdev/index.html">Application Developer's Guide</a>.</p>
103
104 <p>The web application used to process each HTTP request is selected
105 by Catalina based on matching the longest possible prefix of the
106 Request URI against the <em>context path</em> of each defined Context.
107 Once selected, that Context will select an appropriate servlet to
108 process the incoming request, according to the servlet mappings defined
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]109 by the web application deployment.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]110
111 <p>You may define as many <strong>Context</strong> elements as you
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]112 wish. Each such Context MUST have a unique context name within a virtual
113 host. The context path does not need to be unique (see <em>parallel
114 deployment</em> below). In addition, a Context must be present with a
115 context path equal to
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]116 a zero-length string. This Context becomes the <em>default</em>
117 web application for this virtual host, and is used to process all
118 requests that do not match any other Context's context path.</p>
119
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]120 <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>
121 <p><b>You may deploy multiple versions of a web application with the same
122 context path at the same time.</b> The rules used to match requests to a
123 context version are as follows:
124 </p>
125 <ul>
126 <li>If no session information is present in the request, use the latest
127 version.</li>
128 <li>If session information is present in the request, check the session
129 manager of each version for a matching session and if one is found, use that
130 version.</li>
131 <li>If session information is present in the request but no matching session
132 can be found, use the latest version.</li>
133 </ul>
134 <p>The <a href="host.html">Host</a> may be configured (via the
135 <code>undeployOldVersions</code>) to remove old versions deployed in this way
136 once they are no longer in use.</p>
137 </blockquote></td></tr></table>
138
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]139 <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>
140 <p>When <code>autoDeploy</code> or <code>deployOnStartup</code> operations
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]141 are performed by a Host, the name and context path of the web application are
142 derived from the name(s) of the file(s) that define(s) the web application.
143 Consequently, the context path <strong>may not</strong> be defined in a
144 <code>META-INF/context.xml</code> embedded in the application and there is a
145 close relationship between the <em>context name</em>, <em>context path</em>,
146 <em>context version</em> and the <em>base file name</em> (the name minus any
147 <code>.war</code> or <code>.xml</code> extension) of the file.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]148
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]149 <p>If no version is specified then the <em>context name</em> is always the
150 same as the <em>context path</em>. If the <em>context path</em> is the empty
151 string then the <em>base name</em> will be ROOT (always in upper case)
152 otherwise the <em>base name</em> will be the <em>context path</em> with the
153 leading '/' removed and any remaining '/' characters replaced with '#'.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]154
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]155 <p>If a version is specified then the <em>context path</em> remains unchanged
156 and both the <em>context name</em> and the <em>base name</em> have the string
157 '##' appended to them followed by the version identifier.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]158
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]159 <p>Some examples of these naming conventions are given below.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]160
161 <table class="detail-table">
162 <tr>
163 <td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Context Path</font></td>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]164 <td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Context Version</font></td>
165 <td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Context Name</font></td>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]166 <td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Base File Name</font></td>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]167 <td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Example File Names (.xml, .war &amp; directory)</font></td>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]168 </tr>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]169 <tr>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]170 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo</font></td>
171 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>None</i></font></td>
172 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo</font></td>
173 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo</font></td>
174 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo.xml, foo.war, foo</font></td>
175 </tr>
176 <tr>
177 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo/bar</font></td>
178 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>None</i></font></td>
179 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo/bar</font></td>
180 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo#bar</font></td>
181 <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>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]182 </tr>
183 <tr>
184 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>Empty String</i></font></td>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]185 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>None</i></font></td>
186 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>Empty String</i></font></td>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]187 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">ROOT</font></td>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]188 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">ROOT.xml, ROOT.war, ROOT</font></td>
189 </tr>
190 <tr>
191 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo</font></td>
192 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">42</font></td>
193 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo##42</font></td>
194 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo##42</font></td>
195 <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>
196 </tr>
197 <tr>
198 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo/bar</font></td>
199 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">42</font></td>
200 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo/bar##42</font></td>
201 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo#bar##42</font></td>
202 <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>
203 </tr>
204 <tr>
205 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>Empty String</i></font></td>
206 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">42</font></td>
207 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">##42</font></td>
208 <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">ROOT##42</font></td>
209 <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>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]210 </tr>
211 </table>
212
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]213 <p>The version component is treated as a <code>String</code> both for
214 performance reasons and to allow flexibility in versioning schemes. String
215 comparisons are used to determine version order. If version is not specified,
216 it is treated as the empty string.
217 Therefore,
218 <code>foo.war</code> will be treated as an earlier version than
219 <code>foo##11.war</code> and
220 <code>foo##11.war</code> will be treated as an earlier version than
221 <code>foo##2.war</code>. If using a purely numerical versioning scheme it is
222 recommended that zero padding is used so that <code>foo##002.war</code> is
223 treated as an earlier version than <code>foo##011.war</code>.
224 </p>
225
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]226 <p>If you want to deploy a WAR file or a directory using a context path that
227 is not related to the base file name then one of the following options must
228 be used to prevent double-deployment:
229 </p>
230 <ul>
231 <li>Disable autoDeploy and deployOnStartup and define all
232 <strong>Context</strong>s in server.xml</li>
233 <li>Locate the WAR and/or directory outside of the Host's appBase and use
234 a context.xml file with a docBase attribute to define it.</li>
235 </ul>
236 </blockquote></td></tr></table>
237
238 <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>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]239 <p><b>It is NOT recommended to place &lt;Context&gt; elements directly in the
240 server.xml file.</b> This is because it makes modifying the
241 <strong>Context</strong> configuration more invasive since the main
242 <code>conf/server.xml</code> file cannot be reloaded without restarting
243 Tomcat.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]244
245 <p>Individual <strong>Context</strong> elements may be explicitly defined:
246 </p>
247 <ul>
248 <li>In an individual file at <code>/META-INF/context.xml</code> inside the
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]249 application files. Optionally (based on the Host's copyXML attribute)
250 this may be copied to
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]251 <code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> and renamed to
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]252 application's base file name plus a ".xml" extension.</li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]253 <li>In individual files (with a ".xml" extension) in the
254 <code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> directory.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]255 The context path and version will be derived from the base name of the file
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]256 (the file name less the .xml extension). This file will always take precedence
257 over any context.xml file packaged in the web application's META-INF
258 directory.</li>
259 <li>Inside a <a href="host.html">Host</a> element in the main
260 <code>conf/server.xml</code>.</li>
261 </ul>
262
263 <p>Default <strong>Context</strong> elements may be defined that apply to
264 multiple web applications. Configuration for an individual web application
265 will override anything configured in one of these defaults. Any nested
266 elements, e.g. &lt;Resource&gt; elements, that are defined in a default
267 <strong>Context</strong> will be created once for each
268 <strong>Context</strong> to which the default applies. They will <b>not</b> be
269 shared between <strong>Context</strong> elements.
270 </p>
271 <ul>
272 <li>In the <code>$CATALINA_BASE/conf/context.xml</code> file:
273 the Context element information will be loaded by all web applications.</li>
274 <li>In the
275 <code>$CATALINA_BASE/conf/[enginename]/[hostname]/context.xml.default</code>
276 file: the Context element information will be loaded by all web applications
277 of that host.</li>
278 </ul>
279
280 <p>With the exception of server.xml, files that define <strong>Context
281 </strong> elements may only define a single <strong>Context</strong> element.
282 </p>
283
284 <p>In addition to explicitly specified Context elements, there are
285 several techniques by which Context elements can be created automatically
286 for you. See <a href="host.html#Automatic_Application_Deployment">
287 Automatic Application Deployment</a> and
288 <a href="host.html#User_Web_Applications">User Web Applications</a>
289 for more information.</p>
290
291 <p>To define multiple contexts that use a single WAR file or directory,
292 use one of the options described in the <a href="#Naming">Naming</a>
293 section above for creating a <strong>Context</strong> that has a path
294 that is not related to the base file name.</p>
295 </blockquote></td></tr></table>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]296</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>
297
298 <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>
299
300 <p>All implementations of <strong>Context</strong>
301 support the following attributes:</p>
302
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]303 <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">
304 <p>Set to true if Tomcat should automatically parse
305 multipart/form-data request bodies when HttpServletRequest.getPart*
306 or HttpServletRequest.getParameter* is called, even when the
307 target servlet isn't marked with the @MultipartConfig annotation
308 (See Servlet Specification 3.0, Section 3.2 for details).
309 Note that any setting other than <code>false</code> causes Tomcat
310 to behave in a way that is not technically spec-compliant.
311 The default is <code>false</code></p>
312 </td></tr><tr><td align="left" valign="center"><code class="attributeName">backgroundProcessorDelay</code></td><td align="left" valign="center">
313 <p>This value represents the delay in seconds between the
314 invocation of the backgroundProcess method on this context and
315 its child containers, including all wrappers.
316 Child containers will not be invoked if their delay value is not
317 negative (which would mean they are using their own processing
318 thread). Setting this to a positive value will cause
319 a thread to be spawn. After waiting the specified amount of time,
320 the thread will invoke the backgroundProcess method on this host
321 and all its child containers. A context will use background
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]322 processing to perform session expiration and class monitoring for
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]323 reloading. If not specified, the default value for this attribute is
324 -1, which means the context will rely on the background processing
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]325 thread of its parent host.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]326 </td></tr><tr><td align="left" valign="center"><code class="attributeName">className</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]327 <p>Java class name of the implementation to use. This class must
328 implement the <code>org.apache.catalina.Context</code> interface.
329 If not specified, the standard value (defined below) will be used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]330 </td></tr><tr><td align="left" valign="center"><code class="attributeName">containerSciFilter</code></td><td align="left" valign="center">
331 <p>The regular expression that specifies which container provided SCIs
332 should be filtered out and not used for this context. Matching uses
333 <code>java.util.regex.Matcher.find()</code> so the regular expression
334 only has to match a sub-string of the fully qualified class name of the
335 container provided SCI for it to be filtered out. If not specified,
336 no filtering will be applied.</p>
337 </td></tr><tr><td align="left" valign="center"><code class="attributeName">cookies</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]338 <p>Set to <code>true</code> if you want cookies to be used for
339 session identifier communication if supported by the client (this
340 is the default). Set to <code>false</code> if you want to disable
341 the use of cookies for session identifier communication, and rely
342 only on URL rewriting by the application.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]343 </td></tr><tr><td align="left" valign="center"><code class="attributeName">crossContext</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]344 <p>Set to <code>true</code> if you want calls within this application
345 to <code>ServletContext.getContext()</code> to successfully return a
346 request dispatcher for other web applications running on this virtual
347 host. Set to <code>false</code> (the default) in security
348 conscious environments, to make <code>getContext()</code> always
349 return <code>null</code>.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]350 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">docBase</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]351 <p>The <em>Document Base</em> (also known as the <em>Context
352 Root</em>) directory for this web application, or the pathname
353 to the web application archive file (if this web application is
354 being executed directly from the WAR file). You may specify
355 an absolute pathname for this directory or WAR file, or a pathname
356 that is relative to the <code>appBase</code> directory of the
357 owning <a href="host.html">Host</a>.</p>
358 <p>The value of this field must not be set unless the Context element is
359 defined in server.xml or the <code>docBase</code> is not located under
360 the <a href="host.html">Host</a>'s <code>appBase</code>.</p>
361 <p>If a symbolic link is used for docBase then changes to the
362 symbolic link will only be effective after a Tomcat restart or
363 by undeploying and redeploying the context. A context reload is not
364 sufficient.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]365 </td></tr><tr><td align="left" valign="center"><code class="attributeName">dispatchersUseEncodedPaths</code></td><td align="left" valign="center">
366 <p>Controls whether paths used in calls to obtain a request dispatcher
367 ares expected to be encoded. This affects both how Tomcat handles calls
368 to obtain a request dispatcher as well as how Tomcat generates paths
369 used to obtain request dispatchers internally. If not specified, the
370 default value of <code>true</code> is used.</p>
371 </td></tr><tr><td align="left" valign="center"><code class="attributeName">failCtxIfServletStartFails</code></td><td align="left" valign="center">
372 <p>Set to <code>true</code> to have the context fail its startup if any
373 servlet that has load-on-startup &gt;=0 fails its own startup.</p>
374 <p>If not specified, the attribute of the same name in the parent Host
375 configuration is used if specified. Otherwise the default value of
376 <code>false</code> is used.</p>
377 </td></tr><tr><td align="left" valign="center"><code class="attributeName">fireRequestListenersOnForwards</code></td><td align="left" valign="center">
378 <p>Set to <code>true</code> to fire any configured
379 ServletRequestListeners when Tomcat forwards a request. This is
380 primarily of use to users of CDI frameworks that use
381 ServletRequestListeners to configure the necessary environment for a
382 request. If not specified, the default value of <code>false</code> is
383 used.</p>
384 </td></tr><tr><td align="left" valign="center"><code class="attributeName">logEffectiveWebXml</code></td><td align="left" valign="center">
385 <p>Set to <code>true</code> if you want the effective web.xml used for a
386 web application to be logged (at INFO level) when the application
387 starts. The effective web.xml is the result of combining the
388 application's web.xml with any defaults configured by Tomcat and any
389 web-fragment.xml files and annotations discovered. If not specified, the
390 default value of <code>false</code> is used.</p>
391 </td></tr><tr><td align="left" valign="center"><code class="attributeName">mapperContextRootRedirectEnabled</code></td><td align="left" valign="center">
392 <p>If enabled, requests for a web application context root will be
393 redirected (adding a trailing slash) if necessary by the Mapper rather
394 than the default Servlet. This is more efficient but has the side effect
395 of confirming that the context path exists. If not specified, the
396 default value of <code>true</code> is used.</p>
397 </td></tr><tr><td align="left" valign="center"><code class="attributeName">mapperDirectoryRedirectEnabled</code></td><td align="left" valign="center">
398 <p>If enabled, requests for a web application directory will be
399 redirected (adding a trailing slash) if necessary by the Mapper rather
400 than the default Servlet. This is more efficient but has the side effect
401 of confirming that the directory is exists. If not specified, the
402 default value of <code>false</code> is used.</p>
403 </td></tr><tr><td align="left" valign="center"><code class="attributeName">override</code></td><td align="left" valign="center">
404 <p>Set to <code>true</code> to ignore any settings in both the global
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]405 or <a href="host.html">Host</a> default contexts. By default, settings
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]406 from a default context will be used but may be overridden by a setting
407 the same attribute explicitly for the Context.</p>
408 </td></tr><tr><td align="left" valign="center"><code class="attributeName">path</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]409 <p>The <em>context path</em> of this web application, which is
410 matched against the beginning of each request URI to select the
411 appropriate web application for processing. All of the context paths
412 within a particular <a href="host.html">Host</a> must be unique.
413 If you specify a context path of an empty string (""), you are
414 defining the <em>default</em> web application for this Host, which
415 will process all requests not assigned to other Contexts.</p>
416 <p>This attribute must only be used when statically defining a Context
417 in server.xml. In all other circumstances, the path will be inferred
418 from the filenames used for either the .xml context file or the docBase.
419 </p>
420 <p>Even when statically defining a Context in server.xml, this attribute
421 must not be set unless either the docBase is not located under the
422 <a href="host.html">Host</a>'s <code>appBase</code> or both
423 <code>deployOnStartup</code> and <code>autoDeploy</code> are false. If
424 this rule is not followed, double deployment is likely to result.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]425 </td></tr><tr><td align="left" valign="center"><code class="attributeName">preemptiveAuthentication</code></td><td align="left" valign="center">
426 <p>When set to <code>true</code> and the user presents credentials for a
427 resource that is not protected by a security constraint, if the
428 authenticator supports preemptive authentication (the standard
429 authenticators provided with Tomcat do) then the user' credentials
430 will be processed. If not specified, the default of <code>false</code>is
431 used.
432 </p>
433 </td></tr><tr><td align="left" valign="center"><code class="attributeName">privileged</code></td><td align="left" valign="center">
434 <p>Set to <code>true</code> to allow this context to use container
435 servlets, like the manager servlet. Use of the <code>privileged</code>
436 attribute will change the context's parent class loader to be the
437 <em>Server</em> class loader rather than the <em>Shared</em> class
438 loader. Note that in a default installation, the <em>Common</em> class
439 loader is used for both the <em>Server</em> and the <em>Shared</em>
440 class loaders.</p>
441 </td></tr><tr><td align="left" valign="center"><code class="attributeName">reloadable</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]442 <p>Set to <code>true</code> if you want Catalina to monitor classes in
443 <code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
444 changes, and automatically reload the web application if a change
445 is detected. This feature is very useful during application
446 development, but it requires significant runtime overhead and is
447 not recommended for use on deployed production applications. That's
448 why the default setting for this attribute is <i>false</i>. You
449 can use the <a href="../manager-howto.html">Manager</a> web
450 application, however, to trigger reloads of deployed applications
451 on demand.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]452 </td></tr><tr><td align="left" valign="center"><code class="attributeName">resourceOnlyServlets</code></td><td align="left" valign="center">
453 <p>Comma separated list of Servlet names (as used in
454 <code>/WEB-INF/web.xml</code>) that expect a resource to be present.
455 Ensures that welcome files associated with Servlets that expect a
456 resource to be present (such as the JSP Servlet) are not used when there
457 is no resource present. This prevents issues caused by the clarification
458 of welcome file mapping in section 10.10 of the Servlet 3.0
459 specification. If the
460 <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
461 <a href="systemprops.html">system property</a> is set to
462 <code>true</code>, the default value of this attribute will be the empty
463 string, else the default value will be <code>jsp</code>.</p>
464 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sendRedirectBody</code></td><td align="left" valign="center">
465 <p>If <code>true</code>, redirect responses will include a short
466 response body that includes details of the redirect as recommended by
467 RFC 2616. This is disabled by default since including a response body
468 may cause problems for some application component such as compression
469 filters.</p>
470 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionCookieDomain</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]471 <p>The domain to be used for all session cookies created for this
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]472 context. If set, this overrides any domain set by the web application.
473 If not set, the value specified by the web application, if any, will be
474 used.</p>
475 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionCookieName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]476 <p>The name to be used for all session cookies created for this
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]477 context. If set, this overrides any name set by the web application.
478 If not set, the value specified by the web application, if any, will be
479 used, or the name <code>JSESSIONID</code> if the web application does
480 not explicitly set one.</p>
481 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionCookiePath</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]482 <p>The path to be used for all session cookies created for this
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]483 context. If set, this overrides any path set by the web application.
484 If not set, the value specified by the web application will be used, or
485 the context path used if the web application does not explicitly set
486 one. To configure all web application to use an empty path (this can be
487 useful for portlet specification implementations) set this attribute to
488 <code>/</code> in the global <code>CATALINA_BASE/conf/context.xml</code>
489 file.</p>
490 <p>Note: Once one web application using
491 <code>sessionCookiePath="/"</code> obtains a session, all
492 subsequent sessions for any other web application in the same host also
493 configured with <code>sessionCookiePath="/"</code> will always
494 use the same session ID. This holds even if the session is invalidated
495 and a new one created. This makes session fixation protection more
496 difficult and requires custom, Tomcat specific code to change the
497 session ID shared by the multiple applications.</p>
498 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionCookiePathUsesTrailingSlash</code></td><td align="left" valign="center">
499 <p>Some browsers, such as Internet Explorer, Safari and Edge, will send
500 a session cookie for a context with a path of <code>/foo</code> with a
501 request to <code>/foobar</code> in violation of RFC6265. This could
502 expose a session ID from an application deployed at <code>/foo</code> to
503 an application deployed at <code>/foobar</code>. If the application
504 deployed at <code>/foobar</code> is untrusted, this could create a
505 security risk. However, it should be noted that RFC 6265, section 8.5
506 makes clear that path alone should not be view as sufficient to prevent
507 untrusted applications accessing cookies from other applications. To
508 mitigate this risk, this attribute may be set to <code>true</code> and
509 Tomcat will add a trailing slash to the path associated with the session
510 cookie so, in the above example, the cookie path becomes /foo/. However,
511 with a cookie path of /foo/, browsers will no longer send the cookie
512 with a request to /foo. This should not be a problem unless there is a
513 servlet mapped to /*. In this case this attribute will need to be set to
514 <code>false</code> to disable this feature. The default value for this
515 attribute is <code>false</code>.</p>
516 </td></tr><tr><td align="left" valign="center"><code class="attributeName">swallowAbortedUploads</code></td><td align="left" valign="center">
517 <p>Set to false if Tomcat should <b>not</b> read any additional request
518 body data for aborted uploads and instead abort the client connection.
519 This setting is used in the following situations:
520 </p>
521 <ul>
522 <li>the size of the request body is larger than the
523 <code>maxPostSize</code> configured in the connector</li>
524 <li>the size limit of a MultiPart upload is reached</li>
525 <li>the servlet sets the response status to 413 (Request Entity Too
526 Large) </li>
527 </ul>
528 <p>
529 Not reading the additional data will free the request processing thread
530 more quickly. Unfortunately most HTTP clients will not read the response
531 if they can not write the full request.</p>
532 <p>The default is <code>true</code>, so additional data will be
533 read.</p>
534 <p>Note if an error occurs during the request processing that triggers
535 a 5xx response, any unread request data will always be ignored and the
536 client connection will be closed once the error response has been
537 written.</p>
538 </td></tr><tr><td align="left" valign="center"><code class="attributeName">swallowOutput</code></td><td align="left" valign="center">
539 <p>If the value of this flag is <code>true</code>, the bytes output to
540 System.out and System.err by the web application will be redirected to
541 the web application logger. If not specified, the default value
542 of the flag is <code>false</code>.</p>
543 </td></tr><tr><td align="left" valign="center"><code class="attributeName">tldValidation</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]544 <p>If the value of this flag is <code>true</code>, the TLD files
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]545 will be XML validated on context startup. If the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]546 <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
547 <a href="systemprops.html">system property</a> is set to
548 <code>true</code>, the default value of this attribute will be
549 <code>true</code>, else the default value will be <code>false</code>.
550 Setting this attribute to <code>true</code> will incur a performance
551 penalty.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]552 </td></tr><tr><td align="left" valign="center"><code class="attributeName">useHttpOnly</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]553 <p>Should the HttpOnly flag be set on session cookies to prevent client
554 side script from accessing the session ID? Defaults to
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]555 <code>true</code>.</p>
556 </td></tr><tr><td align="left" valign="center"><code class="attributeName">useRelativeRedirects</code></td><td align="left" valign="center">
557 <p>Controls whether HTTP 1.1 and later location headers generated by a
558 call to
559 <code>javax.servlet.http.HttpServletResponse#sendRedirect(String)</code>
560 will use relative or absolute redirects. Relative redirects are more
561 efficient but may not work with reverse proxies that change the context
562 path. It should be noted that it is not recommended to use a reverse
563 proxy to change the context path because of the multiple issues it
564 creates. Absolute redirects should work with reverse proxies that change
565 the context path but may cause issues with the
566 <code>org.apache.catalina.filters.RemoteIpFilter</code> if the filter is
567 changing the scheme and/or port. If the
568 <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
569 <a href="systemprops.html">system property</a> is set to
570 <code>true</code>, the default value of this attribute will be
571 <code>false</code>, else the default value will be <code>true</code>.
572 </p>
573 </td></tr><tr><td align="left" valign="center"><code class="attributeName">validateClientProvidedNewSessionId</code></td><td align="left" valign="center">
574 <p>When a client provides the ID for a new session, this attribute
575 controls whether that ID is validated. The only use case for using a
576 client provided session ID is to have a common session ID across
577 multiple web applications. Therefore, any client provided session ID
578 should already exist in another web application. If this check is
579 enabled, the client provided session ID will only be used if the session
580 ID exists in at least one other web application for the current host.
581 Note that the following additional tests are always applied,
582 irrespective of this setting:</p>
583 <ul>
584 <li>The session ID is provided by a cookie</li>
585 <li>The session cookie has a path of {@code /}</li>
586 </ul>
587 <p>If not specified, the default value of <code>true</code> will be
588 used.</p>
589 </td></tr><tr><td align="left" valign="center"><code class="attributeName">wrapperClass</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]590 <p>Java class name of the <code>org.apache.catalina.Wrapper</code>
591 implementation class that will be used for servlets managed by this
592 Context. If not specified, a standard default value will be used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]593 </td></tr><tr><td align="left" valign="center"><code class="attributeName">xmlBlockExternal</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]594 <p>If the value of this flag is <code>true</code>, the parsing of
595 <code>web.xml</code>, <code>web-fragment.xml</code>, <code>*.tld</code>,
596 <code>*.jspx</code>, <code>*.tagx</code> and <code>tagPlugins.xml</code>
597 files for this web application will not permit external entities to be
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]598 loaded. If not specified, the default value of <code>true</code> will
599 be used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]600 </td></tr><tr><td align="left" valign="center"><code class="attributeName">xmlNamespaceAware</code></td><td align="left" valign="center">
601 <p>If the value of this flag is <code>true</code>, the parsing of
602 <code>web.xml</code> and <code>web-fragment.xml</code> files for this
603 web application will be namespace-aware. Note that <code>*.tld</code>,
604 <code>*.jspx</code> and <code>*.tagx</code> files are always parsed
605 using a namespace-aware parser and that the <code>tagPlugins.xml</code>
606 file (if any) is never parsed using a namespace-aware parser. Note also
607 that if you turn this flag on, you should probably also turn
608 <code>xmlValidation</code> on. If the
609 <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]610 <a href="systemprops.html">system property</a> is set to
611 <code>true</code>, the default value of this attribute will be
612 <code>true</code>, else the default value will be <code>false</code>.
613 Setting this attribute to <code>true</code> will incur a performance
614 penalty.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]615 </td></tr><tr><td align="left" valign="center"><code class="attributeName">xmlValidation</code></td><td align="left" valign="center">
616 <p>If the value of this flag is <code>true</code>, the parsing of
617 <code>web.xml</code> and <code>web-fragment.xml</code> files for this
618 web application will use a validating parser. If the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]619 <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
620 <a href="systemprops.html">system property</a> is set to
621 <code>true</code>, the default value of this attribute will be
622 <code>true</code>, else the default value will be <code>false</code>.
623 Setting this attribute to <code>true</code> will incur a performance
624 penalty.</p>
625 </td></tr></table>
626
627 </blockquote></td></tr></table>
628
629
630 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standard Implementation"><!--()--></a><a name="Standard_Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote>
631
632 <p>The standard implementation of <strong>Context</strong> is
633 <strong>org.apache.catalina.core.StandardContext</strong>.
634 It supports the following additional attributes (in addition to the
635 common attributes listed above):</p>
636
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]637 <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">
638 <p>This attribute controls if, in addition to static resources being
639 served from <code>META-INF/resources</code> inside web application JAR
640 files, static resources are also served from
641 <code>WEB-INF/classes/META-INF/resources</code>. This only applies to
642 web applications with a major version of 3 or higher. Since this is a
643 proprietary extension to the Servlet 3 specification, it is disabled by
644 default. To enable this feature, set the attribute to <code>true</code>.
645 </p>
646 </td></tr><tr><td align="left" valign="center"><code class="attributeName">aliases</code></td><td align="left" valign="center">
647 <p>This attribute provides a list of external locations from which to
648 load resources for this context. The list of aliases should be of
649 the form <code>"/aliasPath1=docBase1,/aliasPath2=docBase2"</code> where
650 <code>aliasPathN</code> must include a leading '/' and
651 <code>docBaseN</code> must be an absolute path to either a .war file or
652 a directory.</p>
653 <p>Whitespace is permitted around both the <code>,</code> and
654 <code>=</code> delimiters, and will be trimmed. Therefore, an aliases
655 attribute with the value <code>"/aliasPath1 = docBase1,<br>
656 /aliasPath2= docBase2"</code> is equivalent to
657 <code>"/aliasPath1=docBase1,/aliasPath2=docBase2"</code></p>
658 <p>A resource will be searched for in the first <code>docBaseN</code>
659 for which <code>aliasPathN</code> is a leading path segment of the
660 resource. If there is no such alias, then the resource will be searched
661 in the usual way.</p>
662 <p>Using '/' as an aliasPath is not allowed. Consider using
663 <code>docBase</code> instead.</p>
664 <p>These external locations will not be emptied if the context
665 is un-deployed.</p>
666 <p>A more powerful feature (for development only) is
667 <a href="#Virtual_webapp">Virtual webapp</a>.</p>
668 </td></tr><tr><td align="left" valign="center"><code class="attributeName">allowLinking</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]669 <p>If the value of this flag is <code>true</code>, symlinks will be
670 allowed inside the web application, pointing to resources outside the
671 web application base path. If not specified, the default value
672 of the flag is <code>false</code>.</p>
673 <p><b>NOTE: This flag MUST NOT be set to true on the Windows platform
674 (or any other OS which does not have a case sensitive filesystem),
675 as it will disable case sensitivity checks, allowing JSP source code
676 disclosure, among other security problems.</b></p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]677 </td></tr><tr><td align="left" valign="center"><code class="attributeName">antiJARLocking</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]678 <p>If true, the Tomcat classloader will take extra measures to avoid
679 JAR file locking when resources are accessed inside JARs through URLs.
680 This will impact startup time of applications, but could prove to be
681 useful on platforms or configurations where file locking can occur.
682 If not specified, the default value is <code>false</code>.</p>
683
684 <p><code>antiJARLocking</code> is a subset of
685 <code>antiResourceLocking</code> and therefore, to prevent duplicate
686 work and possible issues, only one of these attributes should be set
687 to <code>true</code> at any one time.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]688 </td></tr><tr><td align="left" valign="center"><code class="attributeName">antiResourceLocking</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]689 <p>If true, Tomcat will prevent any file locking.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]690 This will significantly impact startup time of applications,
691 but allows full webapp hot deploy and undeploy on platforms
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]692 or configurations where file locking can occur.
693 If not specified, the default value is <code>false</code>.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]694
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]695 <p><code>antiJARLocking</code> is a subset of
696 <code>antiResourceLocking</code> and therefore, to prevent duplicate
697 work and possible issues, only one of these attributes should be set
698 to <code>true</code> at any one time.</p>
699
700 <p>Please note that setting this to <code>true</code> has some side
701 effects, including the disabling of JSP reloading in a running server:
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]702 see <a href="http://bz.apache.org/bugzilla/show_bug.cgi?id=37668">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]703 Bugzilla 37668</a>.</p>
704
705 <p>Please note that setting this flag to true in applications that are
706 outside the appBase for the Host (the <code>webapps</code> directory
707 by default) will cause the application to be <strong>deleted</strong> on
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]708 Tomcat shutdown. You probably don't want to do this, so think twice
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]709 before setting antiResourceLocking=true on a webapp that's outside the
710 appBase for its Host.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]711 </td></tr><tr><td align="left" valign="center"><code class="attributeName">cacheMaxSize</code></td><td align="left" valign="center">
712 <p>Maximum size of the static resource cache in kilobytes.
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]713 If not specified, the default value is <code>10240</code>
714 (10 megabytes).</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]715 </td></tr><tr><td align="left" valign="center"><code class="attributeName">cacheObjectMaxSize</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]716 <p>Maximum size of the static resource that will be placed in the cache.
717 If not specified, the default value is <code>512</code>
718 (512 kilobytes). If this value is greater than
719 <code>cacheMaxSize/20</code> it will be reduced to
720 <code>cacheMaxSize/20</code>.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]721 </td></tr><tr><td align="left" valign="center"><code class="attributeName">cacheTTL</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]722 <p>Amount of time in milliseconds between cache entries revalidation.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]723 If not specified, the default value is <code>5000</code>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]724 (5 seconds).</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]725 </td></tr><tr><td align="left" valign="center"><code class="attributeName">cachingAllowed</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]726 <p>If the value of this flag is <code>true</code>, the cache for static
727 resources will be used. If not specified, the default value
728 of the flag is <code>true</code>.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]729 </td></tr><tr><td align="left" valign="center"><code class="attributeName">clearReferencesHttpClientKeepAliveThread</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]730 <p>If <code>true</code> and an <code>sun.net.www.http.HttpClient</code>
731 keep-alive timer thread has been started by this web application and is
732 still running, Tomcat will change the context class loader for that
733 thread from the current <code>WebappClassLoader</code> to
734 <code>WebappClassLoader#parent</code> to prevent a memory leak. Note
735 that the keep-alive timer thread will stop on its own once the
736 keep-alives all expire however, on a busy system that might not happen
737 for some time. If not specified, the default value of
738 <code>true</code> will be used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]739 </td></tr><tr><td align="left" valign="center"><code class="attributeName">clearReferencesRmiTargets</code></td><td align="left" valign="center">
740 <p>If <code>true</code>, Tomcat looks for memory leaks associated with
741 RMI Targets and clears any it finds. This feature uses reflection to
742 identify the leaks and therefore requires that the command line option
743 <code>-XaddExports:java.rmi/sun.rmi.transport=ALL-UNNAMED</code> is set
744 when running on Java 9 and above. Applications without memory leaks
745 should operate correctly with this attribute set to <code>false</code>.
746 If not specified, the default value of <code>true</code> will be used.</p>
747 </td></tr><tr><td align="left" valign="center"><code class="attributeName">clearReferencesStatic</code></td><td align="left" valign="center">
748 <p>If <code>true</code>, Tomcat attempts to null out any static or final
749 fields from loaded classes when a web application is stopped as a work
750 around for apparent garbage collection bugs and application coding
751 errors. There have been some issues reported with log4j when this
752 is <code>true</code>. Applications without memory leaks using recent
753 JVMs should operate correctly with this attribute set to
754 <code>false</code>. If not specified, the default value of
755 <code>false</code> will be used.</p>
756 <p>This attribute has been deprecated and will be removed in Tomcat
757 8.5.</p>
758 </td></tr><tr><td align="left" valign="center"><code class="attributeName">clearReferencesStopThreads</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]759 <p>If <code>true</code>, Tomcat attempts to terminate threads that have
760 been started by the web application. Stopping threads is performed via
761 the deprecated (for good reason) <code>Thread.stop()</code> method and
762 is likely to result in instability. As such, enabling this should be
763 viewed as an option of last resort in a development environment and is
764 not recommended in a production environment. If not specified, the
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]765 default value of <code>false</code> will be used. If this feature is
766 enabled, web applications may take up to two seconds longer to stop as
767 executor threads are given up to two seconds to stop gracefully before
768 <code>Thread.stop()</code> is called on any remaining threads.</p>
769 </td></tr><tr><td align="left" valign="center"><code class="attributeName">clearReferencesStopTimerThreads</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]770 <p>If <code>true</code>, Tomcat attempts to terminate
771 <code>java.util.Timer</code> threads that have been started by the web
772 application. Unlike standard threads, timer threads can be stopped
773 safely although there may still be side-effects for the application. If
774 not specified, the default value of <code>false</code> will be used.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]775 </td></tr><tr><td align="left" valign="center"><code class="attributeName">copyXML</code></td><td align="left" valign="center">
776 <p>Set to <code>true</code> if you want a context XML descriptor
777 embedded inside the application (located at
778 <code>/META-INF/context.xml</code>) to be copied to the owning
779 <a href="host.html">Host</a>'s <code>xmlBase</code> when the application
780 is deployed. On subsequent starts, the copied context XML descriptor
781 will be used in preference to any context XML descriptor embedded inside
782 the application even if the descriptor embedded inside the application
783 is more recent. The flag's value defaults to <code>false</code>. Note if
784 the <strong>deployXML</strong> attribute of the owning
785 <a href="host.html">Host</a> is <code>false</code> or if the
786 <strong>copyXML</strong> attribute of the owning
787 <a href="host.html">Host</a> is <code>true</code>, this attribute will
788 have no effect.</p>
789 </td></tr><tr><td align="left" valign="center"><code class="attributeName">jndiExceptionOnFailedWrite</code></td><td align="left" valign="center">
790 <p>If <code>true</code>, any attempt by an application to modify the
791 provided JNDI context with a call to bind(), unbind(),
792 createSubContext(), destroySubContext() or close() will trigger a
793 <code>javax.naming.OperationNotSupportedException</code> as required by
794 section EE.5.3.4 of the Java EE specification. This exception can be
795 disabled by setting this attribute to true in which case any calls to
796 modify the JNDI context will return <b>without</b> making any changes
797 and methods that return values will return <code>null</code>. If not
798 specified, the specification compliant default of <code>true</code> will
799 be used.</p>
800 </td></tr><tr><td align="left" valign="center"><code class="attributeName">processTlds</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]801 <p>Whether the context should process TLDs on startup. The default
802 is true. The false setting is intended for special cases
803 that know in advance TLDs are not part of the webapp.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]804 </td></tr><tr><td align="left" valign="center"><code class="attributeName">renewThreadsWhenStoppingContext</code></td><td align="left" valign="center">
805 <p>If <code>true</code>, when this context is stopped, Tomcat renews all
806 the threads from the thread pool that was used to serve this context.
807 This also requires that the
808 <code>ThreadLocalLeakPreventionListener</code> be configured in
809 <code>server.xml</code> and that the <code>threadRenewalDelay</code>
810 property of the <code>Executor</code> be &gt;=0. If not specified, the
811 default value of <code>true</code> will be used.</p>
812 </td></tr><tr><td align="left" valign="center"><code class="attributeName">unloadDelay</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]813 <p>Number of ms that the container will wait for servlets to unload.
814 If not specified, the default value is <code>2000</code> ms.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]815 </td></tr><tr><td align="left" valign="center"><code class="attributeName">unpackWAR</code></td><td align="left" valign="center">
816 <p>If <code>false</code>, the <strong>unpackWARs</strong> attribute of
817 the owning <a href="host.html">Host</a> will be overridden and the WAR
818 file will not be unpacked. If <code>true</code>, the value of the owning
819 <a href="host.html">Host</a>'s <strong>unpackWARs</strong>
820 attribute will determine if the WAR is unpacked. If not specified, the
821 default value is <code>true</code>.</p>
822 </td></tr><tr><td align="left" valign="center"><code class="attributeName">useNaming</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]823 <p>Set to <code>true</code> (the default) to have Catalina enable a
824 JNDI <code>InitialContext</code> for this web application that is
825 compatible with Java2 Enterprise Edition (J2EE) platform
826 conventions.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]827 </td></tr><tr><td align="left" valign="center"><code class="attributeName">workDir</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]828 <p>Pathname to a scratch directory to be provided by this Context
829 for temporary read-write use by servlets within the associated web
830 application. This directory will be made visible to servlets in the
831 web application by a servlet context attribute (of type
832 <code>java.io.File</code>) named
833 <code>javax.servlet.context.tempdir</code> as described in the
834 Servlet Specification. If not specified, a suitable directory
835 underneath <code>$CATALINA_BASE/work</code> will be provided.</p>
836 </td></tr></table>
837
838 </blockquote></td></tr></table>
839
840
841</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
842
843 <p>You can nest at most one instance of the following utility components
844 by nesting a corresponding element inside your <strong>Context</strong>
845 element:</p>
846 <ul>
847 <li><a href="loader.html"><strong>Loader</strong></a> -
848 Configure the web application class loader that will be used to load
849 servlet and bean classes for this web application. Normally, the
850 default configuration of the class loader will be sufficient.</li>
851 <li><a href="manager.html"><strong>Manager</strong></a> -
852 Configure the session manager that will be used to create, destroy,
853 and persist HTTP sessions for this web application. Normally, the
854 default configuration of the session manager will be sufficient.</li>
855 <li><a href="realm.html"><strong>Realm</strong></a> -
856 Configure a realm that will allow its
857 database of users, and their associated roles, to be utilized solely
858 for this particular web application. If not specified, this web
859 application will utilize the Realm associated with the owning
860 <a href="host.html">Host</a> or <a href="engine.html">Engine</a>.</li>
861 <li><a href="resources.html"><strong>Resources</strong></a> -
862 Configure the resource manager that will be used to access the static
863 resources associated with this web application. Normally, the
864 default configuration of the resource manager will be sufficient.</li>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]865 <li><strong>WatchedResource</strong> - The auto deployer will monitor the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]866 specified static resource of the web application for updates, and will
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]867 reload the web application if it is updated. The content of this element
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]868 must be a string.</li>
869 </ul>
870
871</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
872
873
874 <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>
875
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]876 <p>A context is associated with the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]877 <code>org.apache.catalina.core.ContainerBase.[enginename].[hostname].[path]</code>
878 log category. Note that the brackets are actually part of the name, don't omit them.</p>
879
880 </blockquote></td></tr></table>
881
882
883 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Access Logs"><!--()--></a><a name="Access_Logs"><strong>Access Logs</strong></a></font></td></tr><tr><td><blockquote>
884
885 <p>When you run a web server, one of the output files normally generated
886 is an <em>access log</em>, which generates one line of information for
887 each request processed by the server, in a standard format. Catalina
888 includes an optional <a href="valve.html">Valve</a> implementation that
889 can create access logs in the same standard format created by web servers,
890 or in any number of custom formats.</p>
891
892 <p>You can ask Catalina to create an access log for all requests
893 processed by an <a href="engine.html">Engine</a>,
894 <a href="host.html">Host</a>, or <a href="context.html">Context</a>
895 by nesting a <a href="valve.html">Valve</a> element like this:</p>
896
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]897<div class="codeBox"><pre><code>&lt;Context&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]898 ...
899 &lt;Valve className="org.apache.catalina.valves.AccessLogValve"
900 prefix="localhost_access_log." suffix=".txt"
901 pattern="common"/&gt;
902 ...
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]903&lt;/Context&gt;</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]904
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]905 <p>See <a href="valve.html#Access_Logging">Access Logging Valves</a>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]906 for more information on the configuration attributes that are
907 supported.</p>
908
909 </blockquote></td></tr></table>
910
911
912 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Automatic Context Configuration"><!--()--></a><a name="Automatic_Context_Configuration"><strong>Automatic Context Configuration</strong></a></font></td></tr><tr><td><blockquote>
913
914 <p>If you use the standard <strong>Context</strong> implementation,
915 the following configuration steps occur automatically when Catalina
916 is started, or whenever this web application is reloaded. No special
917 configuration is required to enable this feature.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]918
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]919 <ul>
920 <li>If you have not declared your own <a href="loader.html">Loader</a>
921 element, a standard web application class loader will be configured.
922 </li>
923 <li>If you have not declared your own <a href="manager.html">Manager</a>
924 element, a standard session manager will be configured.</li>
925 <li>If you have not declared your own <a href="resources.html">Resources</a>
926 element, a standard resources manager will be configured.</li>
927 <li>The web application properties listed in <code>conf/web.xml</code>
928 will be processed as defaults for this web application. This is used
929 to establish default mappings (such as mapping the <code>*.jsp</code>
930 extension to the corresponding JSP servlet), and other standard
931 features that apply to all web applications.</li>
932 <li>The web application properties listed in the
933 <code>/WEB-INF/web.xml</code> resource for this web application
934 will be processed (if this resource exists).</li>
935 <li>If your web application has specified security constraints that might
936 require user authentication, an appropriate Authenticator that
937 implements the login method you have selected will be configured.</li>
938 </ul>
939
940 </blockquote></td></tr></table>
941
942
943 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Context Parameters"><!--()--></a><a name="Context_Parameters"><strong>Context Parameters</strong></a></font></td></tr><tr><td><blockquote>
944
945 <p>You can configure named values that will be made visible to the
946 web application as servlet context initialization parameters by nesting
947 <code>&lt;Parameter&gt;</code> elements inside this element. For
948 example, you can create an initialization parameter like this:</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]949<div class="codeBox"><pre><code>&lt;Context&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]950 ...
951 &lt;Parameter name="companyName" value="My Company, Incorporated"
952 override="false"/&gt;
953 ...
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]954&lt;/Context&gt;</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]955
956 <p>This is equivalent to the inclusion of the following element in the
957 web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
958 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]959<div class="codeBox"><pre><code>&lt;context-param&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]960 &lt;param-name&gt;companyName&lt;/param-name&gt;
961 &lt;param-value&gt;My Company, Incorporated&lt;/param-value&gt;
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]962&lt;/context-param&gt;</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]963 <p>but does <em>not</em> require modification of the deployment descriptor
964 to customize this value.</p>
965
966 <p>The valid attributes for a <code>&lt;Parameter&gt;</code> element
967 are as follows:</p>
968
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]969 <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">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]970 <p>Optional, human-readable description of this context
971 initialization parameter.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]972 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">name</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]973 <p>The name of the context initialization parameter to be created.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]974 </td></tr><tr><td align="left" valign="center"><code class="attributeName">override</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]975 <p>Set this to <code>false</code> if you do <strong>not</strong> want
976 a <code>&lt;context-param&gt;</code> for the same parameter name,
977 found in the web application deployment descriptor, to override the
978 value specified here. By default, overrides are allowed.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]979 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">value</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]980 <p>The parameter value that will be presented to the application
981 when requested by calling
982 <code>ServletContext.getInitParameter()</code>.</p>
983 </td></tr></table>
984
985 </blockquote></td></tr></table>
986
987
988 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Environment Entries"><!--()--></a><a name="Environment_Entries"><strong>Environment Entries</strong></a></font></td></tr><tr><td><blockquote>
989
990 <p>You can configure named values that will be made visible to the
991 web application as environment entry resources, by nesting
992 <code>&lt;Environment&gt;</code> entries inside this element. For
993 example, you can create an environment entry like this:</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]994<div class="codeBox"><pre><code>&lt;Context&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]995 ...
996 &lt;Environment name="maxExemptions" value="10"
997 type="java.lang.Integer" override="false"/&gt;
998 ...
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]999&lt;/Context&gt;</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1000
1001 <p>This is equivalent to the inclusion of the following element in the
1002 web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
1003 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1004<div class="codeBox"><pre><code>&lt;env-entry&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1005 &lt;env-entry-name&gt;maxExemptions&lt;/env-entry-name&gt;
1006 &lt;env-entry-value&gt;10&lt;/env-entry-value&gt;
1007 &lt;env-entry-type&gt;java.lang.Integer&lt;/env-entry-type&gt;
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1008&lt;/env-entry&gt;</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1009 <p>but does <em>not</em> require modification of the deployment descriptor
1010 to customize this value.</p>
1011
1012 <p>The valid attributes for an <code>&lt;Environment&gt;</code> element
1013 are as follows:</p>
1014
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1015 <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">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1016 <p>Optional, human-readable description of this environment entry.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1017 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">name</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1018 <p>The name of the environment entry to be created, relative to the
1019 <code>java:comp/env</code> context.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1020 </td></tr><tr><td align="left" valign="center"><code class="attributeName">override</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1021 <p>Set this to <code>false</code> if you do <strong>not</strong> want
1022 an <code>&lt;env-entry&gt;</code> for the same environment entry name,
1023 found in the web application deployment descriptor, to override the
1024 value specified here. By default, overrides are allowed.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1025 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">type</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1026 <p>The fully qualified Java class name expected by the web application
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1027 for this environment entry. Must be a legal value for
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1028 <code>&lt;env-entry-type&gt;</code> in the web application deployment
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1029 descriptor.</p>
1030 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">value</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1031 <p>The parameter value that will be presented to the application
1032 when requested from the JNDI context. This value must be convertable
1033 to the Java type defined by the <code>type</code> attribute.</p>
1034 </td></tr></table>
1035
1036 </blockquote></td></tr></table>
1037
1038
1039 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Lifecycle Listeners"><!--()--></a><a name="Lifecycle_Listeners"><strong>Lifecycle Listeners</strong></a></font></td></tr><tr><td><blockquote>
1040
1041 <p>If you have implemented a Java object that needs to know when this
1042 <strong>Context</strong> is started or stopped, you can declare it by
1043 nesting a <strong>Listener</strong> element inside this element. The
1044 class name you specify must implement the
1045 <code>org.apache.catalina.LifecycleListener</code> interface, and
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1046 the class must be packaged in a jar and placed in the
1047 <code>$CATALINA_HOME/lib</code> directory.
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1048 It will be notified about the occurrence of the corresponding
1049 lifecycle events. Configuration of such a listener looks like this:</p>
1050
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1051<div class="codeBox"><pre><code>&lt;Context&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1052 ...
1053 &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
1054 ...
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1055&lt;/Context&gt;</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1056
1057 <p>Note that a Listener can have any number of additional properties
1058 that may be configured from this element. Attribute names are matched
1059 to corresponding JavaBean property names using the standard property
1060 method naming patterns.</p>
1061
1062 </blockquote></td></tr></table>
1063
1064
1065 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Request Filters"><!--()--></a><a name="Request_Filters"><strong>Request Filters</strong></a></font></td></tr><tr><td><blockquote>
1066
1067 <p>You can ask Catalina to check the IP address, or host name, on every
1068 incoming request directed to the surrounding
1069 <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
1070 <a href="context.html">Context</a> element. The remote address or name
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1071 will be checked against configured "accept" and/or "deny"
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1072 filters, which are defined using <code>java.util.regex</code> Regular
1073 Expression syntax. Requests that come from locations that are
1074 not accepted will be rejected with an HTTP "Forbidden" error.
1075 Example filter declarations:</p>
1076
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1077<div class="codeBox"><pre><code>&lt;Context&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1078 ...
1079 &lt;Valve className="org.apache.catalina.valves.RemoteHostValve"
1080 allow=".*\.mycompany\.com|www\.yourcompany\.com"/&gt;
1081 &lt;Valve className="org.apache.catalina.valves.RemoteAddrValve"
1082 deny="192\.168\.1\.\d+"/&gt;
1083 ...
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1084&lt;/Context&gt;</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1085
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1086 <p>See <a href="valve.html#Remote_Address_Filter">Remote Address Filter</a>
1087 and <a href="valve.html#Remote_Host_Filter">Remote Host Filter</a> for
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1088 more information about the configuration options that are supported.</p>
1089
1090 </blockquote></td></tr></table>
1091
1092
1093 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Resource Definitions"><!--()--></a><a name="Resource_Definitions"><strong>Resource Definitions</strong></a></font></td></tr><tr><td><blockquote>
1094
1095 <p>You can declare the characteristics of the resource
1096 to be returned for JNDI lookups of <code>&lt;resource-ref&gt;</code> and
1097 <code>&lt;resource-env-ref&gt;</code> elements in the web application
1098 deployment descriptor. You <strong>MUST</strong> also define
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1099 the needed resource parameters as attributes of the <code>Resource</code>
1100 element, to configure the object factory to be used (if not known to Tomcat
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1101 already), and the properties used to configure that object factory.</p>
1102
1103 <p>For example, you can create a resource definition like this:</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1104<div class="codeBox"><pre><code>&lt;Context&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1105 ...
1106 &lt;Resource name="jdbc/EmployeeDB" auth="Container"
1107 type="javax.sql.DataSource"
1108 description="Employees Database for HR Applications"/&gt;
1109 ...
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1110&lt;/Context&gt;</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1111
1112 <p>This is equivalent to the inclusion of the following element in the
1113 web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1114<div class="codeBox"><pre><code>&lt;resource-ref&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1115 &lt;description&gt;Employees Database for HR Applications&lt;/description&gt;
1116 &lt;res-ref-name&gt;jdbc/EmployeeDB&lt;/res-ref-name&gt;
1117 &lt;res-ref-type&gt;javax.sql.DataSource&lt;/res-ref-type&gt;
1118 &lt;res-auth&gt;Container&lt;/res-auth&gt;
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1119&lt;/resource-ref&gt;</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1120
1121 <p>but does <em>not</em> require modification of the deployment
1122 descriptor to customize this value.</p>
1123
1124 <p>The valid attributes for a <code>&lt;Resource&gt;</code> element
1125 are as follows:</p>
1126
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1127 <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">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1128 <p>Specify whether the web Application code signs on to the
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1129 corresponding resource manager programmatically, or whether the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1130 Container will sign on to the resource manager on behalf of the
1131 application. The value of this attribute must be
1132 <code>Application</code> or <code>Container</code>. This
1133 attribute is <strong>required</strong> if the web application
1134 will use a <code>&lt;resource-ref&gt;</code> element in the web
1135 application deployment descriptor, but is optional if the
1136 application uses a <code>&lt;resource-env-ref&gt;</code> instead.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1137 </td></tr><tr><td align="left" valign="center"><code class="attributeName">closeMethod</code></td><td align="left" valign="center">
1138 <p>Name of the zero-argument method to call on a singleton resource when
1139 it is no longer required. This is intended to speed up clean-up of
1140 resources that would otherwise happen as part of garbage collection.
1141 This attribute is ignored if the <code>singleton</code> attribute is
1142 false. If not specified, no default is defined and no close method will
1143 be called.</p>
1144 <p>For Apache Commons DBCP and Apache Tomcat JDBC connection pools
1145 you can use <code>closeMethod="close"</code>.</p>
1146 </td></tr><tr><td align="left" valign="center"><code class="attributeName">description</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1147 <p>Optional, human-readable description of this resource.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1148 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">name</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1149 <p>The name of the resource to be created, relative to the
1150 <code>java:comp/env</code> context.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1151 </td></tr><tr><td align="left" valign="center"><code class="attributeName">scope</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1152 <p>Specify whether connections obtained through this resource
1153 manager can be shared. The value of this attribute must be
1154 <code>Shareable</code> or <code>Unshareable</code>. By default,
1155 connections are assumed to be shareable.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1156 </td></tr><tr><td align="left" valign="center"><code class="attributeName">singleton</code></td><td align="left" valign="center">
1157 <p>Specify whether this resource definition is for a singleton resource,
1158 i.e. one where there is only a single instance of the resource. If this
1159 attribute is <code>true</code>, multiple JNDI lookups for this resource
1160 will return the same object. If this attribute is <code>false</code>,
1161 multiple JNDI lookups for this resource will return different objects.
1162 This attribute must be <code>true</code> for
1163 <code>javax.sql.DataSource</code> resources to enable JMX registration
1164 of the DataSource. The value of this attribute must be <code>true</code>
1165 or <code>false</code>. By default, this attribute is <code>true</code>.
1166 </p>
1167 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">type</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1168 <p>The fully qualified Java class name expected by the web
1169 application when it performs a lookup for this resource.</p>
1170 </td></tr></table>
1171
1172
1173 </blockquote></td></tr></table>
1174
1175
1176 <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>
1177
1178 <p>This element is used to create a link to a global JNDI resource. Doing
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1179 a JNDI lookup on the link name will then return the linked global
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1180 resource.</p>
1181
1182 <p>For example, you can create a resource link like this:</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1183<div class="codeBox"><pre><code>&lt;Context&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1184 ...
1185 &lt;ResourceLink name="linkToGlobalResource"
1186 global="simpleValue"
1187 type="java.lang.Integer"
1188 ...
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1189&lt;/Context&gt;</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1190
1191 <p>The valid attributes for a <code>&lt;ResourceLink&gt;</code> element
1192 are as follows:</p>
1193
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1194 <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">
1195 <p>The name of the linked global resource in the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1196 global JNDI context.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1197 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">name</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1198 <p>The name of the resource link to be created, relative to the
1199 <code>java:comp/env</code> context.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1200 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">type</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1201 <p>The fully qualified Java class name expected by the web
1202 application when it performs a lookup for this resource link.</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1203 </td></tr><tr><td align="left" valign="center"><code class="attributeName">factory</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1204 <p>The fully qualified Java class name for the class creating these objects.
1205 This class should implement the <code>javax.naming.spi.ObjectFactory</code> interface.</p>
1206 </td></tr></table>
1207
1208 <p>When the attribute <code>factory="org.apache.naming.factory.DataSourceLinkFactory"</code> the resource link can be used with
1209 two additional attributes to allow a shared data source to be used with different credentials.
1210 When these two additional attributes are used in combination with the <code>javax.sql.DataSource</code>
1211 type, different contexts can share a global data source with different credentials.
1212 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>
1213 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)">
1214 <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,
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1215 yet be able to control connections (or pools) in the global configuration.
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1216 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1217 <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">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1218 <p><code>username</code> value for the <code>getConnection(username, password)</code>
1219 call on the linked global DataSource.
1220 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1221 </td></tr><tr><td align="left" valign="center"><code class="attributeName">password</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1222 <p><code>password</code> value for the <code>getConnection(username, password)</code>
1223 call on the linked global DataSource.
1224 </p>
1225 </td></tr></table>
1226 <p>Shared Data Source Example:</p>
1227 <p><strong>Warning:</strong> This feature works only if the global DataSource
1228supports <code>getConnection(username, password)</code> method.
1229<a href="http://commons.apache.org/dbcp/">Apache Commons DBCP</a> pool that
1230Tomcat uses by default does not support it. See its Javadoc for
1231<code>BasicDataSource</code> class.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1232<a href="../jdbc-pool.html">Apache Tomcat JDBC pool</a> does support it,
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1233but by default this support is disabled and can be enabled by
1234<code>alternateUsernameAllowed</code> attribute. See its documentation
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1235for details.</p>
1236<div class="codeBox"><pre><code>&lt;GlobalNamingResources&gt;
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1237 ...
1238 &lt;Resource name="sharedDataSource"
1239 global="sharedDataSource"
1240 type="javax.sql.DataSource"
1241 factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
1242 alternateUsernameAllowed="true"
1243 username="bar"
1244 password="barpass"
1245 ...
1246 ...
1247&lt;/GlobalNamingResources&gt;
1248
1249&lt;Context path="/foo"...&gt;
1250 ...
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1251 &lt;ResourceLink
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1252 name="appDataSource"
1253 global="sharedDataSource"
1254 type="javax.sql.DataSource"
1255 factory="org.apache.naming.factory.DataSourceLinkFactory"
1256 username="foo"
1257 password="foopass"
1258 ...
1259&lt;/Context&gt;
1260&lt;Context path="/bar"...&gt;
1261 ...
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1262 &lt;ResourceLink
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1263 name="appDataSource"
1264 global="sharedDataSource"
1265 type="javax.sql.DataSource"
1266 ...
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1267&lt;/Context&gt;</code></pre></div>
1268 <p>When a request for <code>getConnection()</code> is made in the
1269 <code>/foo</code> context, the request is translated into
1270 <code>getConnection("foo","foopass")</code>,
1271 while a request in the <code>/bar</code> gets passed straight through.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1272 </blockquote></td></tr></table>
1273
1274 <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>
1275
1276 <p>You can declare the characteristics of the UserTransaction
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1277 to be returned for JNDI lookup for <code>java:comp/UserTransaction</code>.
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1278 You <strong>MUST</strong> define an object factory class to instantiate
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1279 this object as well as the needed resource parameters as attributes of the
1280 <code>Transaction</code>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1281 element, and the properties used to configure that object factory.</p>
1282
1283 <p>The valid attributes for the <code>&lt;Transaction&gt;</code> element
1284 are as follows:</p>
1285
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1286 <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">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1287 <p>The class name for the JNDI object factory.</p>
1288 </td></tr></table>
1289
1290 </blockquote></td></tr></table>
1291
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1292 <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>
1293 <p>During development it may be more productive to avoid copying files (static
1294 resources, JSPs, classes, jars...) and configure tomcat to use files from their
1295 source locations. To do that, several customisations of the context configuration are
1296 required:</p>
1297 <ul>
1298 <li>The <code>VirtualDirContext</code> implementation of
1299 <a href="resources.html">Resources</a></li>
1300 <li>The <code>VirtualWebappLoader</code> implementation of
1301 <a href="loader.html">Loader</a></li>
1302 <li><code>scanAllDirectories="true"</code> on the <a href="jar-scanner.html">JarScanner</a></li>
1303 </ul>
1304 <p>To illustrate this feature, here is an example of a standard maven webapp source tree:</p>
1305
1306<div class="codeBox"><pre><code>mywebapp/
1307 src/
1308 main/
1309 java/
1310 resources/
1311 webapp/
1312 WEB-INF/
1313 classes/
1314 target/
1315 classes/
1316</code></pre></div>
1317
1318 <p>To deploy such an application (assuming it also uses the log4j maven artefact),
1319 the context configuration looks like:</p>
1320
1321<div class="codeBox"><pre class="wrap"><code>&lt;Context path="/mywebapp" docBase="/Users/theuser/mywebapp/src/main/webapp"&gt;
1322 &lt;Resources className="org.apache.naming.resources.VirtualDirContext"
1323 extraResourcePaths="/WEB-INF/classes=/Users/theuser/mywebapp/target/classes" /&gt;
1324 &lt;Loader className="org.apache.catalina.loader.VirtualWebappLoader"
1325 virtualClasspath="/Users/theuser/mywebapp/target/classes;/Users/theuser/.m2/repository/log4j/log4j/1.2.15/log4j-1.2.15.jar" /&gt;
1326 &lt;JarScanner scanAllDirectories="true" /&gt;
1327&lt;/Context&gt;
1328</code></pre></div>
1329
1330 <p>Here is another example where the webapp serves pictures under /pictures and movies
1331 under /movies and also depends on another maven project mylib that would normally
1332 produce a jar to be packaged in WEB-INF/lib:</p>
1333
1334<div class="codeBox"><pre><code>mylib/
1335 src/
1336 main/
1337 java/
1338 resources/
1339 META-INF/
1340 resources/
1341 target/
1342 classes/
1343mymovies/
1344mypictures/
1345mywebapp/
1346 src/
1347 main/
1348 java/
1349 resources/
1350 webapp/
1351 WEB-INF/
1352 classes/
1353 target/
1354 classes/
1355</code></pre></div>
1356
1357 <p>The configuration is:</p>
1358
1359<div class="codeBox"><pre class="wrap"><code>&lt;Context path="/mywebapp" docBase="/Users/theuser/mywebapp/src/main/webapp"&gt;
1360 &lt;Resources className="org.apache.naming.resources.VirtualDirContext"
1361 extraResourcePaths="/WEB-INF/classes=/Users/theuser/mywebapp/target/classes,/pictures=/Users/theuser/mypictures,/movies=/Users/theuser/mymovies" /&gt;
1362 &lt;Loader className="org.apache.catalina.loader.VirtualWebappLoader"
1363 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" /&gt;
1364 &lt;JarScanner scanAllDirectories="true" /&gt;
1365&lt;/Context&gt;
1366</code></pre></div>
1367
1368 <p>Note that resources in mylib/target/classes/META-INF/resources/ are mapped to / as
1369 required by servlet 3 specification.</p>
1370 </blockquote></td></tr></table>
1371</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
1372 on improving documentation for Apache Tomcat.<br><br>
1373 If you have trouble and need help, read
1374 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
1375 and ask your question on the tomcat-users
1376 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
1377 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
1378 The Apache Comments System is explained <a href="../comments.html">here</a>.
1379 Comments may be removed by our moderators if they are either
1380 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
1381 var comments_shortname = 'tomcat';
1382 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/config/context.html';
1383 (function(w, d) {
1384 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
1385 d.write('<div id="comments_thread"><\/div>');
1386 var s = d.createElement('script');
1387 s.type = 'text/javascript';
1388 s.async = true;
1389 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
1390 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
1391 }
1392 else {
1393 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
1394 }
1395 })(window, document);
1396 //--><!]]></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>
1397 Copyright &copy; 1999-2017, Apache Software Foundation
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]1398 </em></font></div></td></tr></table></body></html>