Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / fd5ee81fec460cbe9ad65f300b0faf1bf03c19bc / . / tomcat-cas / webapps / docs / config / context.html
blob: d9a3f8cc65abf140b320d45f83b97120306d1dfb [file] [log] [blame]
<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference (6.0.39) - The Context Container</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
.noPrint {display: none;}
td#mainBody {width: 100%;}
</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
The Apache Tomcat Servlet/JSP Container
" border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.39, Jan 27 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>Other</strong></p><ul><li><a href="filter.html">Filter</a></li><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Tomcat Configuration Reference</h1><h2>The Context Container</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
<ul><li><a href="#Introduction">Introduction</a><ol><li><a href="#Naming">Naming</a></li><li><a href="#Defining_a_context">Defining a context</a></li></ol></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Standard_Implementation">Standard Implementation</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a><ol><li><a href="#Logging">Logging</a></li><li><a href="#Access_Logs">Access Logs</a></li><li><a href="#Automatic_Context_Configuration">Automatic Context Configuration</a></li><li><a href="#Context_Parameters">Context Parameters</a></li><li><a href="#Environment_Entries">Environment Entries</a></li><li><a href="#Lifecycle_Listeners">Lifecycle Listeners</a></li><li><a href="#Request_Filters">Request Filters</a></li><li><a href="#Resource_Definitions">Resource Definitions</a></li><li><a href="#Resource_Links">Resource Links</a></li><li><a href="#Transaction">Transaction</a></li></ol></li></ul>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
<blockquote><em>
<p>The description below uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
the directory into which you have installed Tomcat 6.</p>
</em></blockquote>
<p>The <strong>Context</strong> element represents a <em>web
application</em>, which is run within a particular virtual host.
Each web application is based on a <em>Web Application Archive</em>
(WAR) file, or a corresponding directory containing the corresponding
unpacked contents, as described in the Servlet Specification (version
2.2 or later). For more information about web application archives,
you can download the
<a href="http://wiki.apache.org/tomcat/Specifications">Servlet
Specification</a>, and review the Tomcat
<a href="../appdev/index.html">Application Developer's Guide</a>.</p>
<p>The web application used to process each HTTP request is selected
by Catalina based on matching the longest possible prefix of the
Request URI against the <em>context path</em> of each defined Context.
Once selected, that Context will select an appropriate servlet to
process the incoming request, according to the servlet mappings defined
in the <em>web application deployment descriptor</em> file (which MUST
be located at <code>/WEB-INF/web.xml</code> within the web app's
directory hierarchy).</p>
<p>You may define as many <strong>Context</strong> elements as you
wish. Each such Context MUST have a unique context path within a virtual
host. In
addition, a Context must be present with a context path equal to
a zero-length string. This Context becomes the <em>default</em>
web application for this virtual host, and is used to process all
requests that do not match any other Context's context path.</p>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Naming"><strong>Naming</strong></a></font></td></tr><tr><td><blockquote>
<p>When <code>autoDeploy</code> or <code>deployOnStartup</code> operations
are performed by a Host, the web application is specified by a context XML
file in <a href="host.html">Host</a>'s <code>xmlBase</code>
directory or by a WAR file or a directory file in Host's
<code>appBase</code> directory.
In this case the context path is derived from the name of the file that
is being deployed. Consequently, the context path <strong>may not</strong>
be defined in a <code>META-INF/context.xml</code> embedded in
the application. There is, therefore, a close relationship between the
<em>context path</em> and
the <em>base file name</em> (the name minus <code>.war</code> or
<code>.xml</code> extension) of the file.</p>
<p>Let us assume that you want to deploy your application to respond to
requests to URIs starting with certain context path. According to the
Servlet specification, the context path may be an empty string, or a
string starting with '/'. The rules to define the names for this context
path are the following:</p>
<ul>
<li>If the context path is a zero length string, the <em>base name</em> is
<code>"ROOT"</code> (uppercase)</li>
<li>If the context path is not a zero length string, the <em>base
name</em> is the context path with the leading '/' removed and any
remaining '/' characters in the path replaced with '#'.</li>
</ul>
<p>To help clarify these rules, some examples are given in the following
table.</p>
<table class="detail-table">
<tr>
<td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Context Path</font></td>
<td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Base File Name</font></td>
</tr>
<tr><td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo</font></td><td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo</font></td></tr>
<tr>
<td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">/foo/bar</font></td><td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">foo#bar</font></td>
</tr>
<tr>
<td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>Empty String</i></font></td>
<td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">ROOT</font></td>
</tr>
</table>
<p>If you want to deploy a WAR file or a directory using a context path that
is not related to the base file name then one of the following options must
be used to prevent double-deployment:
</p>
<ul>
<li>Disable autoDeploy and deployOnStartup and define all
<strong>Context</strong>s in server.xml</li>
<li>Locate the WAR and/or directory outside of the Host's appBase and use
a context.xml file with a docBase attribute to define it.</li>
</ul>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Defining a context"><!--()--></a><a name="Defining_a_context"><strong>Defining a context</strong></a></font></td></tr><tr><td><blockquote>
<p><b>It is NOT recommended to place
&lt;Context&gt; elements directly in the server.xml file.</b> This
is because it makes modifying the <strong>Context</strong> configuration
more invasive since the main <code>conf/server.xml</code> file cannot be
reloaded without restarting Tomcat.</p>
<p>Individual <strong>Context</strong> elements may be explicitly defined:
</p>
<ul>
<li>In an individual file at <code>/META-INF/context.xml</code> inside the
application files. In Tomcat 6 this file is automatically copied to
<code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> and renamed to
application's base file name plus a ".xml" extension.
(This automated copying became optional in Tomcat 7).
</li>
<li>In individual files (with a ".xml" extension) in the
<code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> directory.
The context path will be derived from the base name of the file
(the file name less the .xml extension). This file will always take precedence
over any context.xml file packaged in the web application's META-INF
directory.</li>
<li>Inside a <a href="host.html">Host</a> element in the main
<code>conf/server.xml</code>.</li>
</ul>
<p>Default <strong>Context</strong> elements may be defined that apply to
multiple web applications. Configuration for an individual web application
will override anything configured in one of these defaults. Any nested
elements, e.g. &lt;Resource&gt; elements, that are defined in a default
<strong>Context</strong> will be created once for each
<strong>Context</strong> to which the default applies. They will <b>not</b> be
shared between <strong>Context</strong> elements.
</p>
<ul>
<li>In the <code>$CATALINA_BASE/conf/context.xml</code> file:
the Context element information will be loaded by all web applications.</li>
<li>In the
<code>$CATALINA_BASE/conf/[enginename]/[hostname]/context.xml.default</code>
file: the Context element information will be loaded by all web applications
of that host.</li>
</ul>
<p>With the exception of server.xml, files that define <strong>Context
</strong> elements may only define a single <strong>Context</strong> element.
</p>
<p>In addition to explicitly specified Context elements, there are
several techniques by which Context elements can be created automatically
for you. See <a href="host.html#Automatic_Application_Deployment">
Automatic Application Deployment</a> and
<a href="host.html#User_Web_Applications">User Web Applications</a>
for more information.</p>
<p>To define multiple contexts that use a single WAR file or directory,
use one of the options described in the <a href="#Naming">Naming</a>
section above for creating a <strong>Context</strong> that has a path
that is not related to the base file name.</p>
</blockquote></td></tr></table>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>
<p>All implementations of <strong>Context</strong>
support the following attributes:</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>backgroundProcessorDelay</code></td><td align="left" valign="center">
<p>This value represents the delay in seconds between the
invocation of the backgroundProcess method on this context and
its child containers, including all wrappers.
Child containers will not be invoked if their delay value is not
negative (which would mean they are using their own processing
thread). Setting this to a positive value will cause
a thread to be spawn. After waiting the specified amount of time,
the thread will invoke the backgroundProcess method on this host
and all its child containers. A context will use background
processing to perform session expiration and class monitoring for
reloading. If not specified, the default value for this attribute is
-1, which means the context will rely on the background processing
thread of its parent host.</p>
</td></tr><tr><td align="left" valign="center"><code>className</code></td><td align="left" valign="center">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Context</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</td></tr><tr><td align="left" valign="center"><code>cookies</code></td><td align="left" valign="center">
<p>Set to <code>true</code> if you want cookies to be used for
session identifier communication if supported by the client (this
is the default). Set to <code>false</code> if you want to disable
the use of cookies for session identifier communication, and rely
only on URL rewriting by the application.</p>
</td></tr><tr><td align="left" valign="center"><code>crossContext</code></td><td align="left" valign="center">
<p>Set to <code>true</code> if you want calls within this application
to <code>ServletContext.getContext()</code> to successfully return a
request dispatcher for other web applications running on this virtual
host. Set to <code>false</code> (the default) in security
conscious environments, to make <code>getContext()</code> always
return <code>null</code>.</p>
</td></tr><tr><td align="left" valign="center"><code>disableURLRewriting</code></td><td align="left" valign="center">
<p>Set to <code>true</code> to disable support for using URL rewriting
to track session IDs for clients of this Context. URL rewriting is an
optional component of the servlet 2.5 specification but disabling URL
rewriting will result in non-compliant behaviour since the specification
requires that there <em>must</em> be a way to retain sessions if the
client doesn't allow session cookies. If not specified, the
specification compliant default value of <code>false</code> will be
used.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>docBase</code></strong></td><td align="left" valign="center">
<p>The <em>Document Base</em> (also known as the <em>Context
Root</em>) directory for this web application, or the pathname
to the web application archive file (if this web application is
being executed directly from the WAR file). You may specify
an absolute pathname for this directory or WAR file, or a pathname
that is relative to the <code>appBase</code> directory of the
owning <a href="host.html">Host</a>.</p>
<p>The value of this field must not be set unless the Context element is
defined in server.xml or the <code>docBase</code> is not located under
the <a href="host.html">Host</a>'s <code>appBase</code>.</p>
<p>If a symbolic link is used for docBase then changes to the
symbolic link will only be effective after a Tomcat restart or
by undeploying and redeploying the context. A context reload is not
sufficient.</p>
</td></tr><tr><td align="left" valign="center"><code>override</code></td><td align="left" valign="center">
<p>Set to <code>true</code> to have explicit settings in this
Context element override any corresponding settings in either the global
or <a href="host.html">Host</a> default contexts. By default, settings
from a default context will be used.</p>
</td></tr><tr><td align="left" valign="center"><code>privileged</code></td><td align="left" valign="center">
<p>Set to <code>true</code> to allow this context to use container
servlets, like the manager servlet. Use of the <code>privileged</code>
attribute will change the context's parent class loader to be the
<em>Server</em> class loader rather than the <em>Shared</em> class
loader. Note that in a default installation, the <em>Common</em> class
loader is used for both the <em>Server</em> and the <em>Shared</em>
class loaders.</p>
</td></tr><tr><td align="left" valign="center"><code>path</code></td><td align="left" valign="center">
<p>The <em>context path</em> of this web application, which is
matched against the beginning of each request URI to select the
appropriate web application for processing. All of the context paths
within a particular <a href="host.html">Host</a> must be unique.
If you specify a context path of an empty string (""), you are
defining the <em>default</em> web application for this Host, which
will process all requests not assigned to other Contexts.</p>
<p>This attribute must only be used when statically defining a Context
in server.xml. In all other circumstances, the path will be inferred
from the filenames used for either the .xml context file or the docBase.
</p>
<p>Even when statically defining a Context in server.xml, this attribute
must not be set unless either the docBase is not located under the
<a href="host.html">Host</a>'s <code>appBase</code> or both
<code>deployOnStartup</code> and <code>autoDeploy</code> are false. If
this rule is not followed, double deployment is likely to result.</p>
</td></tr><tr><td align="left" valign="center"><code>reloadable</code></td><td align="left" valign="center">
<p>Set to <code>true</code> if you want Catalina to monitor classes in
<code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
changes, and automatically reload the web application if a change
is detected. This feature is very useful during application
development, but it requires significant runtime overhead and is
not recommended for use on deployed production applications. That's
why the default setting for this attribute is <i>false</i>. You
can use the <a href="../manager-howto.html">Manager</a> web
application, however, to trigger reloads of deployed applications
on demand.</p>
</td></tr><tr><td align="left" valign="center"><code>sessionCookieDomain</code></td><td align="left" valign="center">
<p>The domain to be used for all session cookies created for this
Context. If not set, no domain will be specified for session cookies.
</p>
</td></tr><tr><td align="left" valign="center"><code>sessionCookieName</code></td><td align="left" valign="center">
<p>The name to be used for all session cookies created for this
Context. If not set, the default of JSESSIONID will be used. Note that
this default will be overridden by the
<strong>org.apache.catalina.SESSION_COOKIE_NAME</strong> system
property.</p>
</td></tr><tr><td align="left" valign="center"><code>sessionCookiePath</code></td><td align="left" valign="center">
<p>The path to be used for all session cookies created for this
Context. If not set, the context path will be used. Note that this will
be overridden by the <strong>emptySessionPath</strong> attribute on the
connector used to access this Context.</p>
</td></tr><tr><td align="left" valign="center"><code>tldValidation</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, the TLD files
will be XML validated on context startup. If the
<code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
<a href="systemprops.html">system property</a> is set to
<code>true</code>, the default value of this attribute will be
<code>true</code>, else the default value will be <code>false</code>.
Setting this attribute to <code>true</code> will incur a performance
penalty.</p>
</td></tr><tr><td align="left" valign="center"><code>useHttpOnly</code></td><td align="left" valign="center">
<p>Should the HttpOnly flag be set on session cookies to prevent client
side script from accessing the session ID? Defaults to
<code>false</code>.</p>
</td></tr><tr><td align="left" valign="center"><code>wrapperClass</code></td><td align="left" valign="center">
<p>Java class name of the <code>org.apache.catalina.Wrapper</code>
implementation class that will be used for servlets managed by this
Context. If not specified, a standard default value will be used.</p>
</td></tr><tr><td align="left" valign="center"><code>xmlBlockExternal</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, the parsing of
<code>web.xml</code>, <code>web-fragment.xml</code>, <code>*.tld</code>,
<code>*.jspx</code>, <code>*.tagx</code> and <code>tagPlugins.xml</code>
files for this web application will not permit external entities to be
loaded. If a <code>SecurityManager</code> is configured then the default
value of this attribute will be <code>true</code>, else the default
value will be <code>false</code>.</p>
</td></tr><tr><td align="left" valign="center"><code>xmlNamespaceAware</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, the parsing of the
<code>web.xml</code> file for this web application will be
namespace-aware. Note that <code>*.tld</code>, <code>*.jspx</code> and
<code>*.tagx</code> files are always parsed using a namespace-aware
parser and that the <code>tagPlugins.xml</code> file (if any) is never
parsed using a namespace-aware parser. Note also that if you turn this
flag on, you should probably also turn <code>xmlValidation</code> on. If
the <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
<a href="systemprops.html">system property</a> is set to
<code>true</code>, the default value of this attribute will be
<code>true</code>, else the default value will be <code>false</code>.
Setting this attribute to <code>true</code> will incur a performance
penalty.</p>
</td></tr><tr><td align="left" valign="center"><code>xmlValidation</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, the parsing of the
<code>web.xml</code> file for this web application will use a validating
parser. If the
<code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
<a href="systemprops.html">system property</a> is set to
<code>true</code>, the default value of this attribute will be
<code>true</code>, else the default value will be <code>false</code>.
Setting this attribute to <code>true</code> will incur a performance
penalty.</p>
</td></tr></table>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standard Implementation"><!--()--></a><a name="Standard_Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote>
<p>The standard implementation of <strong>Context</strong> is
<strong>org.apache.catalina.core.StandardContext</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>allowLinking</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, symlinks will be
allowed inside the web application, pointing to resources outside the
web application base path. If not specified, the default value
of the flag is <code>false</code>.</p>
<p><b>NOTE: This flag MUST NOT be set to true on the Windows platform
(or any other OS which does not have a case sensitive filesystem),
as it will disable case sensitivity checks, allowing JSP source code
disclosure, among other security problems.</b></p>
</td></tr><tr><td align="left" valign="center"><code>antiJARLocking</code></td><td align="left" valign="center">
<p>If true, the Tomcat classloader will take extra measures to avoid
JAR file locking when resources are accessed inside JARs through URLs.
This will impact startup time of applications, but could prove to be
useful on platforms or configurations where file locking can occur.
If not specified, the default value is <code>false</code>.</p>
<p><code>antiJARLocking</code> is a subset of
<code>antiResourceLocking</code> and therefore, to prevent duplicate
work and possible issues, only one of these attributes should be set
to <code>true</code> at any one time.</p>
</td></tr><tr><td align="left" valign="center"><code>antiResourceLocking</code></td><td align="left" valign="center">
<p>If true, Tomcat will prevent any file locking.
This will significantly impact startup time of applications,
but allows full webapp hot deploy and undeploy on platforms
or configurations where file locking can occur.
If not specified, the default value is <code>false</code>.</p>
<p><code>antiJARLocking</code> is a subset of
<code>antiResourceLocking</code> and therefore, to prevent duplicate
work and possible issues, only one of these attributes should be set
to <code>true</code> at any one time.</p>
<p>Please note that setting this to <code>true</code> has some side
effects, including the disabling of JSP reloading in a running server:
see <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=37668">
Bugzilla 37668</a>.</p>
<p>Please note that setting this flag to true in applications that are
outside the appBase for the Host (the <code>webapps</code> directory
by default) will cause the application to be <strong>deleted</strong> on
Tomcat shutdown. You probably don't want to do this, so think twice
before setting antiResourceLocking=true on a webapp that's outside the
appBase for its Host.</p>
</td></tr><tr><td align="left" valign="center"><code>cacheMaxSize</code></td><td align="left" valign="center">
<p>Maximum size of the static resource cache in kilobytes.
If not specified, the default value is <code>10240</code>
(10 megabytes).</p>
</td></tr><tr><td align="left" valign="center"><code>cacheObjectMaxSize</code></td><td align="left" valign="center">
<p>Maximum size of the static resource that will be placed in the cache.
If not specified, the default value is <code>512</code>
(512 kilobytes). If this value is greater than
<code>cacheMaxSize/20</code> it will be reduced to
<code>cacheMaxSize/20</code>.</p>
</td></tr><tr><td align="left" valign="center"><code>cacheTTL</code></td><td align="left" valign="center">
<p>Amount of time in milliseconds between cache entries revalidation.
If not specified, the default value is <code>5000</code>
(5 seconds).</p>
</td></tr><tr><td align="left" valign="center"><code>cachingAllowed</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, the cache for static
resources will be used. If not specified, the default value
of the flag is <code>true</code>.</p>
</td></tr><tr><td align="left" valign="center"><code>caseSensitive</code></td><td align="left" valign="center">
<p><strong>Deprecated.</strong> This option is removed in Tomcat 7
onwards where the default of <code>true</code> is always used.</p>
<p>If the value of this flag is <code>false</code>, all case sensitivity
checks will be disabled. If not
specified, the default value of the flag is <code>true</code>.</p>
<p><b>NOTE: This flag MUST NOT be set to false on the Windows platform
(or any other OS which does not have a case sensitive filesystem),
as it will disable case sensitivity checks, allowing JSP source code
disclosure, among other security problems.</b></p>
</td></tr><tr><td align="left" valign="center"><code>clearReferencesHttpClientKeepAliveThread</code></td><td align="left" valign="center">
<p>If <code>true</code> and an <code>sun.net.www.http.HttpClient</code>
keep-alive timer thread has been started by this web application and is
still running, Tomcat will change the context class loader for that
thread from the current <code>WebappClassLoader</code> to
<code>WebappClassLoader#parent</code> to prevent a memory leak. Note
that the keep-alive timer thread will stop on its own once the
keep-alives all expire however, on a busy system that might not happen
for some time. If not specified, the default value of
<code>true</code> will be used.</p>
</td></tr><tr><td align="left" valign="center"><code>clearReferencesStopThreads</code></td><td align="left" valign="center">
<p>If <code>true</code>, Tomcat attempts to terminate threads that have
been started by the web application. Stopping threads is performed via
the deprecated (for good reason) <code>Thread.stop()</code> method and
is likely to result in instability. As such, enabling this should be
viewed as an option of last resort in a development environment and is
not recommended in a production environment. If not specified, the
default value of <code>false</code> will be used.</p>
</td></tr><tr><td align="left" valign="center"><code>clearReferencesStopTimerThreads</code></td><td align="left" valign="center">
<p>If <code>true</code>, Tomcat attempts to terminate
<code>java.util.Timer</code> threads that have been started by the web
application. Unlike standard threads, timer threads can be stopped
safely although there may still be side-effects for the application. If
not specified, the default value of <code>false</code> will be used.</p>
</td></tr><tr><td align="left" valign="center"><code>clearReferencesThreadLocals</code></td><td align="left" valign="center">
<p>If <code>true</code>, Tomcat attempts to clear any ThreadLocal
objects that are instances of classes loaded by this class loader.
Failure to remove any such objects will result in a memory leak on web
application stop, undeploy or reload. If not specified, the default
value of <code>false</code> will be used since the clearing of the
ThreadLocal objects is not performed in a thread-safe manner.</p>
</td></tr><tr><td align="left" valign="center"><code>processTlds</code></td><td align="left" valign="center">
<p>Whether the context should process TLDs on startup. The default
is true. The false setting is intended for special cases
that know in advance TLDs are not part of the webapp.</p>
</td></tr><tr><td align="left" valign="center"><code>swallowOutput</code></td><td align="left" valign="center">
<p>If the value of this flag is <code>true</code>, the bytes output to
System.out and System.err by the web application will be redirected to
the web application logger. If not specified, the default value
of the flag is <code>false</code>.</p>
</td></tr><tr><td align="left" valign="center"><code>unloadDelay</code></td><td align="left" valign="center">
<p>Number of ms that the container will wait for servlets to unload.
If not specified, the default value is <code>2000</code> ms.</p>
</td></tr><tr><td align="left" valign="center"><code>unpackWAR</code></td><td align="left" valign="center">
<p>If true, Tomcat will unpack all compressed web applications before
running them.
If not specified, the default value is <code>true</code>.</p>
</td></tr><tr><td align="left" valign="center"><code>useNaming</code></td><td align="left" valign="center">
<p>Set to <code>true</code> (the default) to have Catalina enable a
JNDI <code>InitialContext</code> for this web application that is
compatible with Java2 Enterprise Edition (J2EE) platform
conventions.</p>
</td></tr><tr><td align="left" valign="center"><code>workDir</code></td><td align="left" valign="center">
<p>Pathname to a scratch directory to be provided by this Context
for temporary read-write use by servlets within the associated web
application. This directory will be made visible to servlets in the
web application by a servlet context attribute (of type
<code>java.io.File</code>) named
<code>javax.servlet.context.tempdir</code> as described in the
Servlet Specification. If not specified, a suitable directory
underneath <code>$CATALINA_BASE/work</code> will be provided.</p>
</td></tr></table>
</blockquote></td></tr></table>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
<p>You can nest at most one instance of the following utility components
by nesting a corresponding element inside your <strong>Context</strong>
element:</p>
<ul>
<li><a href="loader.html"><strong>Loader</strong></a> -
Configure the web application class loader that will be used to load
servlet and bean classes for this web application. Normally, the
default configuration of the class loader will be sufficient.</li>
<li><a href="manager.html"><strong>Manager</strong></a> -
Configure the session manager that will be used to create, destroy,
and persist HTTP sessions for this web application. Normally, the
default configuration of the session manager will be sufficient.</li>
<li><a href="realm.html"><strong>Realm</strong></a> -
Configure a realm that will allow its
database of users, and their associated roles, to be utilized solely
for this particular web application. If not specified, this web
application will utilize the Realm associated with the owning
<a href="host.html">Host</a> or <a href="engine.html">Engine</a>.</li>
<li><a href="resources.html"><strong>Resources</strong></a> -
Configure the resource manager that will be used to access the static
resources associated with this web application. Normally, the
default configuration of the resource manager will be sufficient.</li>
<li><strong>WatchedResource</strong> - The auto deployer will monitor the
specified static resource of the web application for updates, and will
reload the web application if is is updated. The content of this element
must be a string.</li>
</ul>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Logging"><strong>Logging</strong></a></font></td></tr><tr><td><blockquote>
<p>A context is associated with the
<code>org.apache.catalina.core.ContainerBase.[enginename].[hostname].[path]</code>
log category. Note that the brackets are actually part of the name, don't omit them.</p>
</blockquote></td></tr></table>
<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>
<p>When you run a web server, one of the output files normally generated
is an <em>access log</em>, which generates one line of information for
each request processed by the server, in a standard format. Catalina
includes an optional <a href="valve.html">Valve</a> implementation that
can create access logs in the same standard format created by web servers,
or in any number of custom formats.</p>
<p>You can ask Catalina to create an access log for all requests
processed by an <a href="engine.html">Engine</a>,
<a href="host.html">Host</a>, or <a href="context.html">Context</a>
by nesting a <a href="valve.html">Valve</a> element like this:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Context&gt;
...
&lt;Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="localhost_access_log." suffix=".txt"
pattern="common"/&gt;
...
&lt;/Context&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
for more information on the configuration attributes that are
supported.</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Automatic Context Configuration"><!--()--></a><a name="Automatic_Context_Configuration"><strong>Automatic Context Configuration</strong></a></font></td></tr><tr><td><blockquote>
<p>If you use the standard <strong>Context</strong> implementation,
the following configuration steps occur automatically when Catalina
is started, or whenever this web application is reloaded. No special
configuration is required to enable this feature.</p>
<ul>
<li>If you have not declared your own <a href="loader.html">Loader</a>
element, a standard web application class loader will be configured.
</li>
<li>If you have not declared your own <a href="manager.html">Manager</a>
element, a standard session manager will be configured.</li>
<li>If you have not declared your own <a href="resources.html">Resources</a>
element, a standard resources manager will be configured.</li>
<li>The web application properties listed in <code>conf/web.xml</code>
will be processed as defaults for this web application. This is used
to establish default mappings (such as mapping the <code>*.jsp</code>
extension to the corresponding JSP servlet), and other standard
features that apply to all web applications.</li>
<li>The web application properties listed in the
<code>/WEB-INF/web.xml</code> resource for this web application
will be processed (if this resource exists).</li>
<li>If your web application has specified security constraints that might
require user authentication, an appropriate Authenticator that
implements the login method you have selected will be configured.</li>
</ul>
</blockquote></td></tr></table>
<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>
<p>You can configure named values that will be made visible to the
web application as servlet context initialization parameters by nesting
<code>&lt;Parameter&gt;</code> elements inside this element. For
example, you can create an initialization parameter like this:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Context&gt;
...
&lt;Parameter name="companyName" value="My Company, Incorporated"
override="false"/&gt;
...
&lt;/Context&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>This is equivalent to the inclusion of the following element in the
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;context-param&gt;
&lt;param-name&gt;companyName&lt;/param-name&gt;
&lt;param-value&gt;My Company, Incorporated&lt;/param-value&gt;
&lt;/context-param&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>but does <em>not</em> require modification of the deployment descriptor
to customize this value.</p>
<p>The valid attributes for a <code>&lt;Parameter&gt;</code> element
are as follows:</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>description</code></td><td align="left" valign="center">
<p>Optional, human-readable description of this context
initialization parameter.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
<p>The name of the context initialization parameter to be created.</p>
</td></tr><tr><td align="left" valign="center"><code>override</code></td><td align="left" valign="center">
<p>Set this to <code>false</code> if you do <strong>not</strong> want
a <code>&lt;context-param&gt;</code> for the same parameter name,
found in the web application deployment descriptor, to override the
value specified here. By default, overrides are allowed.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>value</code></strong></td><td align="left" valign="center">
<p>The parameter value that will be presented to the application
when requested by calling
<code>ServletContext.getInitParameter()</code>.</p>
</td></tr></table>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Environment Entries"><!--()--></a><a name="Environment_Entries"><strong>Environment Entries</strong></a></font></td></tr><tr><td><blockquote>
<p>You can configure named values that will be made visible to the
web application as environment entry resources, by nesting
<code>&lt;Environment&gt;</code> entries inside this element. For
example, you can create an environment entry like this:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Context&gt;
...
&lt;Environment name="maxExemptions" value="10"
type="java.lang.Integer" override="false"/&gt;
...
&lt;/Context&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>This is equivalent to the inclusion of the following element in the
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;env-entry&gt;
&lt;env-entry-name&gt;maxExemptions&lt;/env-entry-name&gt;
&lt;env-entry-value&gt;10&lt;/env-entry-value&gt;
&lt;env-entry-type&gt;java.lang.Integer&lt;/env-entry-type&gt;
&lt;/env-entry&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>but does <em>not</em> require modification of the deployment descriptor
to customize this value.</p>
<p>The valid attributes for an <code>&lt;Environment&gt;</code> element
are as follows:</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>description</code></td><td align="left" valign="center">
<p>Optional, human-readable description of this environment entry.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
<p>The name of the environment entry to be created, relative to the
<code>java:comp/env</code> context.</p>
</td></tr><tr><td align="left" valign="center"><code>override</code></td><td align="left" valign="center">
<p>Set this to <code>false</code> if you do <strong>not</strong> want
an <code>&lt;env-entry&gt;</code> for the same environment entry name,
found in the web application deployment descriptor, to override the
value specified here. By default, overrides are allowed.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
<p>The fully qualified Java class name expected by the web application
for this environment entry. Must be one of the legal values for
<code>&lt;env-entry-type&gt;</code> in the web application deployment
descriptor: <code>java.lang.Boolean</code>,
<code>java.lang.Byte</code>, <code>java.lang.Character</code>,
<code>java.lang.Double</code>, <code>java.lang.Float</code>,
<code>java.lang.Integer</code>, <code>java.lang.Long</code>,
<code>java.lang.Short</code>, or <code>java.lang.String</code>.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>value</code></strong></td><td align="left" valign="center">
<p>The parameter value that will be presented to the application
when requested from the JNDI context. This value must be convertable
to the Java type defined by the <code>type</code> attribute.</p>
</td></tr></table>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Lifecycle Listeners"><!--()--></a><a name="Lifecycle_Listeners"><strong>Lifecycle Listeners</strong></a></font></td></tr><tr><td><blockquote>
<p>If you have implemented a Java object that needs to know when this
<strong>Context</strong> is started or stopped, you can declare it by
nesting a <strong>Listener</strong> element inside this element. The
class name you specify must implement the
<code>org.apache.catalina.LifecycleListener</code> interface, and
the class must be packaged in a jar and placed in the
<code>$CATALINA_HOME/lib</code> directory.
It will be notified about the occurrence of the corresponding
lifecycle events. Configuration of such a listener looks like this:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Context&gt;
...
&lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
...
&lt;/Context&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>Note that a Listener can have any number of additional properties
that may be configured from this element. Attribute names are matched
to corresponding JavaBean property names using the standard property
method naming patterns.</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Request Filters"><!--()--></a><a name="Request_Filters"><strong>Request Filters</strong></a></font></td></tr><tr><td><blockquote>
<p>You can ask Catalina to check the IP address, or host name, on every
incoming request directed to the surrounding
<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
<a href="context.html">Context</a> element. The remote address or name
will be checked against a configured list of "accept" and/or "deny"
filters, which are defined using <code>java.util.regex</code> Regular
Expression syntax. Requests that come from locations that are
not accepted will be rejected with an HTTP "Forbidden" error.
Example filter declarations:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Context&gt;
...
&lt;Valve className="org.apache.catalina.valves.RemoteHostValve"
allow=".*\.mycompany\.com|www\.yourcompany\.com"/&gt;
&lt;Valve className="org.apache.catalina.valves.RemoteAddrValve"
deny="192\.168\.1\.\d+"/&gt;
...
&lt;/Context&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
and <a href="valve.html#Remote Host Filter">Remote Host Filter</a> for
more information about the configuration options that are supported.</p>
</blockquote></td></tr></table>
<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>
<p>You can declare the characteristics of the resource
to be returned for JNDI lookups of <code>&lt;resource-ref&gt;</code> and
<code>&lt;resource-env-ref&gt;</code> elements in the web application
deployment descriptor. You <strong>MUST</strong> also define
the needed resource parameters as attributes of the <code>Resource</code>
element, to configure the object factory to be used (if not known to Tomcat
already), and the properties used to configure that object factory.</p>
<p>For example, you can create a resource definition like this:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Context&gt;
...
&lt;Resource name="jdbc/EmployeeDB" auth="Container"
type="javax.sql.DataSource"
description="Employees Database for HR Applications"/&gt;
...
&lt;/Context&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>This is equivalent to the inclusion of the following element in the
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;resource-ref&gt;
&lt;description&gt;Employees Database for HR Applications&lt;/description&gt;
&lt;res-ref-name&gt;jdbc/EmployeeDB&lt;/res-ref-name&gt;
&lt;res-ref-type&gt;javax.sql.DataSource&lt;/res-ref-type&gt;
&lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;/resource-ref&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>but does <em>not</em> require modification of the deployment
descriptor to customize this value.</p>
<p>The valid attributes for a <code>&lt;Resource&gt;</code> element
are as follows:</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>auth</code></td><td align="left" valign="center">
<p>Specify whether the web Application code signs on to the
corresponding resource manager programatically, or whether the
Container will sign on to the resource manager on behalf of the
application. The value of this attribute must be
<code>Application</code> or <code>Container</code>. This
attribute is <strong>required</strong> if the web application
will use a <code>&lt;resource-ref&gt;</code> element in the web
application deployment descriptor, but is optional if the
application uses a <code>&lt;resource-env-ref&gt;</code> instead.</p>
</td></tr><tr><td align="left" valign="center"><code>description</code></td><td align="left" valign="center">
<p>Optional, human-readable description of this resource.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
<p>The name of the resource to be created, relative to the
<code>java:comp/env</code> context.</p>
</td></tr><tr><td align="left" valign="center"><code>scope</code></td><td align="left" valign="center">
<p>Specify whether connections obtained through this resource
manager can be shared. The value of this attribute must be
<code>Shareable</code> or <code>Unshareable</code>. By default,
connections are assumed to be shareable.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
<p>The fully qualified Java class name expected by the web
application when it performs a lookup for this resource.</p>
</td></tr></table>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Resource Links"><!--()--></a><a name="Resource_Links"><strong>Resource Links</strong></a></font></td></tr><tr><td><blockquote>
<p>This element is used to create a link to a global JNDI resource. Doing
a JNDI lookup on the link name will then return the linked global
resource.</p>
<p>For example, you can create a resource link like this:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Context&gt;
...
&lt;ResourceLink name="linkToGlobalResource"
global="simpleValue"
type="java.lang.Integer"
...
&lt;/Context&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>The valid attributes for a <code>&lt;ResourceLink&gt;</code> element
are as follows:</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>global</code></strong></td><td align="left" valign="center">
<p>The name of the linked global resource in the
global JNDI context.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
<p>The name of the resource link to be created, relative to the
<code>java:comp/env</code> context.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
<p>The fully qualified Java class name expected by the web
application when it performs a lookup for this resource link.</p>
</td></tr><tr><td align="left" valign="center"><code>factory</code></td><td align="left" valign="center">
<p>The fully qualified Java class name for the class creating these objects.
This class should implement the <code>javax.naming.spi.ObjectFactory</code> interface.</p>
</td></tr></table>
<p>When the attribute <code>factory="org.apache.naming.factory.DataSourceLinkFactory"</code> the resource link can be used with
two additional attributes to allow a shared data source to be used with different credentials.
When these two additional attributes are used in combination with the <code>javax.sql.DataSource</code>
type, different contexts can share a global data source with different credentials.
Under the hood, what happens is that a call to <a href="http://docs.oracle.com/javase/6/docs/api/javax/sql/DataSource.html#getConnection()"><code>getConnection()</code></a>
is simply translated to a call <a href="http://docs.oracle.com/javase/6/docs/api/javax/sql/DataSource.html#getConnection(java.lang.String,%20java.lang.String)">
<code>getConnection(username, password)</code></a> on the global data source. This is an easy way to get code to be transparent to what schemas are being used,
yet be able to control connections (or pools) in the global configuration.
</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>username</code></td><td align="left" valign="center">
<p><code>username</code> value for the <code>getConnection(username, password)</code>
call on the linked global DataSource.
</p>
</td></tr><tr><td align="left" valign="center"><code>password</code></td><td align="left" valign="center">
<p><code>password</code> value for the <code>getConnection(username, password)</code>
call on the linked global DataSource.
</p>
</td></tr></table>
<p>Shared Data Source Example:</p>
<p><strong>Warning:</strong> This feature works only if the global DataSource
supports <code>getConnection(username, password)</code> method.
<a href="http://commons.apache.org/dbcp/">Apache Commons DBCP</a> pool that
Tomcat uses by default does not support it. See its Javadoc for
<code>BasicDataSource</code> class.
<a href="http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html">Apache Tomcat JDBC pool</a>
(included with Tomcat 7 and later) does support it,
but by default this support is disabled and can be enabled by
<code>alternateUsernameAllowed</code> attribute. See its documentation
for details. The example below uses Apache Tomcat JDBC pool.</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;GlobalNamingResources&gt;
...
&lt;Resource name="sharedDataSource"
global="sharedDataSource"
type="javax.sql.DataSource"
factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
alternateUsernameAllowed="true"
username="bar"
password="barpass"
...
...
&lt;/GlobalNamingResources&gt;
&lt;Context path="/foo"...&gt;
...
&lt;ResourceLink
name="appDataSource"
global="sharedDataSource"
type="javax.sql.DataSource"
factory="org.apache.naming.factory.DataSourceLinkFactory"
username="foo"
password="foopass"
...
&lt;/Context&gt;
&lt;Context path="/bar"...&gt;
...
&lt;ResourceLink
name="appDataSource"
global="sharedDataSource"
type="javax.sql.DataSource"
...
&lt;/Context&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>When a request for <code>getConnection()</code> is made in the <code>/foo</code> context, the request is translated into
<code>getConnection("foo","foopass")</code>, while a request in the <code>/bar</code> gets passed straight through.</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Transaction"><strong>Transaction</strong></a></font></td></tr><tr><td><blockquote>
<p>You can declare the characteristics of the UserTransaction
to be returned for JNDI lookup for <code>java:comp/UserTransaction</code>.
You <strong>MUST</strong> define an object factory class to instantiate
this object as well as the needed resource parameters as attributes of the
<code>Transaction</code>
element, and the properties used to configure that object factory.</p>
<p>The valid attributes for the <code>&lt;Transaction&gt;</code> element
are as follows:</p>
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>factory</code></strong></td><td align="left" valign="center">
<p>The class name for the JNDI object factory.</p>
</td></tr></table>
</blockquote></td></tr></table>
</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
Copyright &copy; 1999-2014, Apache Software Foundation
</em></font></div></td></tr></table></body></html>