| <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 | |
| <Context> elements directly in the server.xml file.</b> This | |
| is because it makes modifying the <strong>Context</strong> configuration | |
| more invasive since the main <code>conf/server.xml</code> file cannot be | |
| reloaded without restarting Tomcat.</p> | |
| <p>Individual <strong>Context</strong> elements may be explicitly defined: | |
| </p> | |
| <ul> | |
| <li>In an individual file at <code>/META-INF/context.xml</code> inside the | |
| application files. In Tomcat 6 this file is automatically copied to | |
| <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. <Resource> 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> | |
| <Context> | |
| ... | |
| <Valve className="org.apache.catalina.valves.AccessLogValve" | |
| prefix="localhost_access_log." suffix=".txt" | |
| pattern="common"/> | |
| ... | |
| </Context> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <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><Parameter></code> elements inside this element. For | |
| example, you can create an initialization parameter like this:</p> | |
| <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre> | |
| <Context> | |
| ... | |
| <Parameter name="companyName" value="My Company, Incorporated" | |
| override="false"/> | |
| ... | |
| </Context> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <p>This is equivalent to the inclusion of the following element in the | |
| web application deployment descriptor (<code>/WEB-INF/web.xml</code>): | |
| </p> | |
| <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre> | |
| <context-param> | |
| <param-name>companyName</param-name> | |
| <param-value>My Company, Incorporated</param-value> | |
| </context-param> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <p>but does <em>not</em> require modification of the deployment descriptor | |
| to customize this value.</p> | |
| <p>The valid attributes for a <code><Parameter></code> element | |
| are as follows:</p> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>description</code></td><td align="left" valign="center"> | |
| <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><context-param></code> for the same parameter name, | |
| found in the web application deployment descriptor, to override the | |
| value specified here. By default, overrides are allowed.</p> | |
| </td></tr><tr><td align="left" valign="center"><strong><code>value</code></strong></td><td align="left" valign="center"> | |
| <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><Environment></code> entries inside this element. For | |
| example, you can create an environment entry like this:</p> | |
| <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre> | |
| <Context> | |
| ... | |
| <Environment name="maxExemptions" value="10" | |
| type="java.lang.Integer" override="false"/> | |
| ... | |
| </Context> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <p>This is equivalent to the inclusion of the following element in the | |
| web application deployment descriptor (<code>/WEB-INF/web.xml</code>): | |
| </p> | |
| <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre> | |
| <env-entry> | |
| <env-entry-name>maxExemptions</env-entry-name> | |
| <env-entry-value>10</env-entry-value> | |
| <env-entry-type>java.lang.Integer</env-entry-type> | |
| </env-entry> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <p>but does <em>not</em> require modification of the deployment descriptor | |
| to customize this value.</p> | |
| <p>The valid attributes for an <code><Environment></code> element | |
| are as follows:</p> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>description</code></td><td align="left" valign="center"> | |
| <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><env-entry></code> for the same environment entry name, | |
| found in the web application deployment descriptor, to override the | |
| value specified here. By default, overrides are allowed.</p> | |
| </td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center"> | |
| <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><env-entry-type></code> in the web application deployment | |
| descriptor: <code>java.lang.Boolean</code>, | |
| <code>java.lang.Byte</code>, <code>java.lang.Character</code>, | |
| <code>java.lang.Double</code>, <code>java.lang.Float</code>, | |
| <code>java.lang.Integer</code>, <code>java.lang.Long</code>, | |
| <code>java.lang.Short</code>, or <code>java.lang.String</code>.</p> | |
| </td></tr><tr><td align="left" valign="center"><strong><code>value</code></strong></td><td align="left" valign="center"> | |
| <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> | |
| <Context> | |
| ... | |
| <Listener className="com.mycompany.mypackage.MyListener" ... > | |
| ... | |
| </Context> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <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> | |
| <Context> | |
| ... | |
| <Valve className="org.apache.catalina.valves.RemoteHostValve" | |
| allow=".*\.mycompany\.com|www\.yourcompany\.com"/> | |
| <Valve className="org.apache.catalina.valves.RemoteAddrValve" | |
| deny="192\.168\.1\.\d+"/> | |
| ... | |
| </Context> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <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><resource-ref></code> and | |
| <code><resource-env-ref></code> elements in the web application | |
| deployment descriptor. You <strong>MUST</strong> also define | |
| the needed resource parameters as attributes of the <code>Resource</code> | |
| element, to configure the object factory to be used (if not known to Tomcat | |
| already), and the properties used to configure that object factory.</p> | |
| <p>For example, you can create a resource definition like this:</p> | |
| <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre> | |
| <Context> | |
| ... | |
| <Resource name="jdbc/EmployeeDB" auth="Container" | |
| type="javax.sql.DataSource" | |
| description="Employees Database for HR Applications"/> | |
| ... | |
| </Context> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <p>This is equivalent to the inclusion of the following element in the | |
| web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p> | |
| <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre> | |
| <resource-ref> | |
| <description>Employees Database for HR Applications</description> | |
| <res-ref-name>jdbc/EmployeeDB</res-ref-name> | |
| <res-ref-type>javax.sql.DataSource</res-ref-type> | |
| <res-auth>Container</res-auth> | |
| </resource-ref> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <p>but does <em>not</em> require modification of the deployment | |
| descriptor to customize this value.</p> | |
| <p>The valid attributes for a <code><Resource></code> element | |
| are as follows:</p> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>auth</code></td><td align="left" valign="center"> | |
| <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><resource-ref></code> element in the web | |
| application deployment descriptor, but is optional if the | |
| application uses a <code><resource-env-ref></code> instead.</p> | |
| </td></tr><tr><td align="left" valign="center"><code>description</code></td><td align="left" valign="center"> | |
| <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> | |
| <Context> | |
| ... | |
| <ResourceLink name="linkToGlobalResource" | |
| global="simpleValue" | |
| type="java.lang.Integer" | |
| ... | |
| </Context> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <p>The valid attributes for a <code><ResourceLink></code> element | |
| are as follows:</p> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>global</code></strong></td><td align="left" valign="center"> | |
| <p>The name of the linked global resource in the | |
| 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> | |
| <GlobalNamingResources> | |
| ... | |
| <Resource name="sharedDataSource" | |
| global="sharedDataSource" | |
| type="javax.sql.DataSource" | |
| factory="org.apache.tomcat.jdbc.pool.DataSourceFactory" | |
| alternateUsernameAllowed="true" | |
| username="bar" | |
| password="barpass" | |
| ... | |
| ... | |
| </GlobalNamingResources> | |
| <Context path="/foo"...> | |
| ... | |
| <ResourceLink | |
| name="appDataSource" | |
| global="sharedDataSource" | |
| type="javax.sql.DataSource" | |
| factory="org.apache.naming.factory.DataSourceLinkFactory" | |
| username="foo" | |
| password="foopass" | |
| ... | |
| </Context> | |
| <Context path="/bar"...> | |
| ... | |
| <ResourceLink | |
| name="appDataSource" | |
| global="sharedDataSource" | |
| type="javax.sql.DataSource" | |
| ... | |
| </Context> | |
| </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div> | |
| <p>When a request for <code>getConnection()</code> is made in the <code>/foo</code> context, the request is translated into | |
| <code>getConnection("foo","foopass")</code>, while a request in the <code>/bar</code> gets passed straight through.</p> | |
| </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><Transaction></code> element | |
| are as follows:</p> | |
| <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>factory</code></strong></td><td align="left" valign="center"> | |
| <p>The class name for the JNDI object factory.</p> | |
| </td></tr></table> | |
| </blockquote></td></tr></table> | |
| </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em> | |
| Copyright © 1999-2014, Apache Software Foundation | |
| </em></font></div></td></tr></table></body></html> |