<?xml version="1.0"?> <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <!DOCTYPE document [ <!ENTITY project SYSTEM "project.xml"> ]> <document url="context.html"> &project; <properties> <author email="craigmcc@apache.org">Craig R. McClanahan</author> <title>The Context Container</title> </properties> <body> <section name="Table of Contents"> <toc/> </section> <section name="Introduction"> <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. 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> <p><b>For Tomcat 6, unlike Tomcat 4.x, 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><strong>Context</strong> elements may be explicitly defined: <ul> <li>In the <code>$CATALINA_BASE/conf/context.xml</code> file: the Context element information will be loaded by all webapps.</li> <li>In the <code>$CATALINA_BASE/conf/[enginename]/[hostname]/context.xml.default</code> file: the Context element information will be loaded by all webapps of that host.</li> <li>In individual files (with a ".xml" extension) in the <code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> directory. The name of the file (less the .xml extension) will be used as the context path. Multi-level context paths may be defined using #, e.g. <code>foo#bar.xml</code> for a context path of <code>/foo/bar</code>. The default web application may be defined by using a file called <code>ROOT.xml</code>.</li> <li>Only if a context file does not exist for the application in the <code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code>, in an individual file at <code>/META-INF/context.xml</code> inside the application files. If the web application is packaged as a WAR then <code>/META-INF/context.xml</code> will be copied to <code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> and renamed to match the application's context path. Once this file exists, it will not be replaced if a new WAR with a newer <code>/META-INF/context.xml</code> is placed in the host's appBase.</li> <li>Inside a <a href="host.html">Host</a> element in the main <code>conf/server.xml</code>.</li> </ul> </p> <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> </section> <section name="Attributes"> <subsection name="Common Attributes"> <p>All implementations of <strong>Context</strong> support the following attributes:</p> <attributes> <attribute name="backgroundProcessorDelay" required="false"> <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> </attribute> <attribute name="className" required="false"> <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> </attribute> <attribute name="cookies" required="false"> <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> </attribute> <attribute name="crossContext" required="false"> <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> </attribute> <attribute name="disableURLRewriting" required="false"> <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> </attribute> <attribute name="docBase" required="true"> <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 when the Context is configured using a <code>META-INF/context.xml</code> file as it will be inferred by the automatic deployment process.</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> </attribute> <attribute name="override" required="false"> <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> </attribute> <attribute name="privileged" required="false"> <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> </attribute> <attribute name="path" required="false"> <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> </attribute> <attribute name="reloadable" required="false"> <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> </attribute> <attribute name="sessionCookieDomain" required="false"> <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> </attribute> <attribute name="sessionCookieName" required="false"> <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> </attribute> <attribute name="sessionCookiePath" required="false"> <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> </attribute> <attribute name="wrapperClass" required="false"> <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> </attribute> <attribute name="useHttpOnly" required="false"> <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> </attribute> </attributes> </subsection> <subsection name="Standard Implementation"> <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> <attributes> <attribute name="allowLinking" required="false"> <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> </attribute> <attribute name="antiJARLocking" required="false"> <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> </attribute> <attribute name="antiResourceLocking" required="false"> <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> </attribute> <attribute name="cacheMaxSize" required="false"> <p>Maximum size of the static resource cache in kilobytes. If not specified, the default value is <code>10240</code> (10 megabytes).</p> </attribute> <attribute name="cacheObjectMaxSize" required="false"> <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> </attribute> <attribute name="cacheTTL" required="false"> <p>Amount of time in milliseconds between cache entries revalidation. If not specified, the default value is <code>5000</code> (5 seconds).</p> </attribute> <attribute name="cachingAllowed" required="false"> <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> </attribute> <attribute name="caseSensitive" required="false"> <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> </attribute> <attribute name="clearReferencesHttpClientKeepAliveThread" required = "false"> <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> </attribute> <attribute name="clearReferencesStopThreads" required = "false"> <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> </attribute> <attribute name="clearReferencesStopTimerThreads" required = "false"> <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> </attribute> <attribute name="clearReferencesThreadLocals" required="false"> <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> </attribute> <attribute name="processTlds" required="false"> <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> </attribute> <attribute name="swallowOutput" required="false"> <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> </attribute> <attribute name="tldNamespaceAware" required="false"> <p>If the value of this flag is <code>true</code>, the TLD files XML validation will be namespace-aware. If you turn this flag on, you should probably also turn <code>tldValidation</code> on. The default value for this flag is <code>false</code>, and setting it to true will incur a performance penalty. </p> </attribute> <attribute name="tldValidation" required="false"> <p>If the value of this flag is <code>true</code>, the TLD files will be XML validated on context startup. The default value for this flag is <code>false</code>, and setting it to true will incur a performance penalty.</p> </attribute> <attribute name="unloadDelay" required="false"> <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> </attribute> <attribute name="unpackWAR" required="false"> <p>If true, Tomcat will unpack all compressed web applications before running them. If not specified, the default value is <code>true</code>.</p> </attribute> <attribute name="useNaming" required="false"> <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> </attribute> <attribute name="workDir" required="false"> <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> </attribute> </attributes> </subsection> </section> <section name="Nested Components"> <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> </section> <section name="Special Features"> <subsection name="Logging"> <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> </subsection> <subsection name="Access Logs"> <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> <source> <Context> ... <Valve className="org.apache.catalina.valves.AccessLogValve" prefix="localhost_access_log." suffix=".txt" pattern="common"/> ... </Context> </source> <p>See <a href="valve.html#Access Log Valve">Access Log Valve</a> for more information on the configuration attributes that are supported.</p> </subsection> <subsection name="Automatic Context Configuration"> <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> </subsection> <subsection name="Context Parameters"> <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> <source> <Context> ... <Parameter name="companyName" value="My Company, Incorporated" override="false"/> ... </Context> </source> <p>This is equivalent to the inclusion of the following element in the web application deployment descriptor (<code>/WEB-INF/web.xml</code>): </p> <source> <context-param> <param-name>companyName</param-name> <param-value>My Company, Incorporated</param-value> </context-param> </source> <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> <attributes> <attribute name="description" required="false"> <p>Optional, human-readable description of this context initialization parameter.</p> </attribute> <attribute name="name" required="true"> <p>The name of the context initialization parameter to be created.</p> </attribute> <attribute name="override" required="false"> <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> </attribute> <attribute name="value" required="true"> <p>The parameter value that will be presented to the application when requested by calling <code>ServletContext.getInitParameter()</code>.</p> </attribute> </attributes> </subsection> <subsection name="Environment Entries"> <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> <source> <Context> ... <Environment name="maxExemptions" value="10" type="java.lang.Integer" override="false"/> ... </Context> </source> <p>This is equivalent to the inclusion of the following element in the web application deployment descriptor (<code>/WEB-INF/web.xml</code>): </p> <source> <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> </source> <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> <attributes> <attribute name="description" required="false"> <p>Optional, human-readable description of this environment entry.</p> </attribute> <attribute name="name" required="true"> <p>The name of the environment entry to be created, relative to the <code>java:comp/env</code> context.</p> </attribute> <attribute name="override" required="false"> <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> </attribute> <attribute name="type" required="true"> <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> </attribute> <attribute name="value" required="true"> <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> </attribute> </attributes> </subsection> <subsection name="Lifecycle Listeners"> <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> <source> <Context> ... <Listener className="com.mycompany.mypackage.MyListener" ... > ... </Context> </source> <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> </subsection> <subsection name="Request Filters"> <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> <source> <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> </source> <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> </subsection> <subsection name="Resource Definitions"> <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> <source> <Context> ... <Resource name="jdbc/EmployeeDB" auth="Container" type="javax.sql.DataSource" description="Employees Database for HR Applications"/> ... </Context> </source> <p>This is equivalent to the inclusion of the following element in the web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p> <source> <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> </source> <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> <attributes> <attribute name="auth" required="false"> <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> </attribute> <attribute name="description" required="false"> <p>Optional, human-readable description of this resource.</p> </attribute> <attribute name="name" required="true"> <p>The name of the resource to be created, relative to the <code>java:comp/env</code> context.</p> </attribute> <attribute name="scope" required="false"> <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> </attribute> <attribute name="type" required="true"> <p>The fully qualified Java class name expected by the web application when it performs a lookup for this resource.</p> </attribute> </attributes> </subsection> <subsection name="Resource Links"> <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> <source> <Context> ... <ResourceLink name="linkToGlobalResource" global="simpleValue" type="java.lang.Integer" ... </Context> </source> <p>The valid attributes for a <code><ResourceLink></code> element are as follows:</p> <attributes> <attribute name="global" required="true"> <p>The name of the linked global resource in the global JNDI context.</p> </attribute> <attribute name="name" required="true"> <p>The name of the resource link to be created, relative to the <code>java:comp/env</code> context.</p> </attribute> <attribute name="type" required="true"> <p>The fully qualified Java class name expected by the web application when it performs a lookup for this resource link.</p> </attribute> <attribute name="factory" required="false"> <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> </attribute> </attributes> <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> <attributes> <attribute name="username" required="false"> <p><code>username</code> value for the <code>getConnection(username, password)</code> call on the linked global DataSource. </p> </attribute> <attribute name="password" required="false"> <p><code>password</code> value for the <code>getConnection(username, password)</code> call on the linked global DataSource. </p> </attribute> </attributes> <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> <source> <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> </source> <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> </subsection> <subsection name="Transaction"> <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> <attributes> <attribute name="factory" required="true"> <p>The class name for the JNDI object factory.</p> </attribute> </attributes> </subsection> </section> </body> </document>