| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame^] | 1 | <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">
|
| 2 | .noPrint {display: none;}
|
| 3 | td#mainBody {width: 100%;}
|
| 4 | </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="
|
| 5 | The Apache Tomcat Servlet/JSP Container
|
| 6 | " 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>
|
| 7 | <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>
|
| 8 | </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>
|
| 9 |
|
| 10 | <blockquote><em>
|
| 11 | <p>The description below uses the variable name $CATALINA_BASE to refer the
|
| 12 | base directory against which most relative paths are resolved. If you have
|
| 13 | not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE
|
| 14 | directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
|
| 15 | the directory into which you have installed Tomcat 6.</p>
|
| 16 | </em></blockquote>
|
| 17 |
|
| 18 | <p>The <strong>Context</strong> element represents a <em>web
|
| 19 | application</em>, which is run within a particular virtual host.
|
| 20 | Each web application is based on a <em>Web Application Archive</em>
|
| 21 | (WAR) file, or a corresponding directory containing the corresponding
|
| 22 | unpacked contents, as described in the Servlet Specification (version
|
| 23 | 2.2 or later). For more information about web application archives,
|
| 24 | you can download the
|
| 25 | <a href="http://wiki.apache.org/tomcat/Specifications">Servlet
|
| 26 | Specification</a>, and review the Tomcat
|
| 27 | <a href="../appdev/index.html">Application Developer's Guide</a>.</p>
|
| 28 |
|
| 29 | <p>The web application used to process each HTTP request is selected
|
| 30 | by Catalina based on matching the longest possible prefix of the
|
| 31 | Request URI against the <em>context path</em> of each defined Context.
|
| 32 | Once selected, that Context will select an appropriate servlet to
|
| 33 | process the incoming request, according to the servlet mappings defined
|
| 34 | in the <em>web application deployment descriptor</em> file (which MUST
|
| 35 | be located at <code>/WEB-INF/web.xml</code> within the web app's
|
| 36 | directory hierarchy).</p>
|
| 37 |
|
| 38 | <p>You may define as many <strong>Context</strong> elements as you
|
| 39 | wish. Each such Context MUST have a unique context path within a virtual
|
| 40 | host. In
|
| 41 | addition, a Context must be present with a context path equal to
|
| 42 | a zero-length string. This Context becomes the <em>default</em>
|
| 43 | web application for this virtual host, and is used to process all
|
| 44 | requests that do not match any other Context's context path.</p>
|
| 45 |
|
| 46 | <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>
|
| 47 | <p>When <code>autoDeploy</code> or <code>deployOnStartup</code> operations
|
| 48 | are performed by a Host, the web application is specified by a context XML
|
| 49 | file in <a href="host.html">Host</a>'s <code>xmlBase</code>
|
| 50 | directory or by a WAR file or a directory file in Host's
|
| 51 | <code>appBase</code> directory.
|
| 52 | In this case the context path is derived from the name of the file that
|
| 53 | is being deployed. Consequently, the context path <strong>may not</strong>
|
| 54 | be defined in a <code>META-INF/context.xml</code> embedded in
|
| 55 | the application. There is, therefore, a close relationship between the
|
| 56 | <em>context path</em> and
|
| 57 | the <em>base file name</em> (the name minus <code>.war</code> or
|
| 58 | <code>.xml</code> extension) of the file.</p>
|
| 59 |
|
| 60 | <p>Let us assume that you want to deploy your application to respond to
|
| 61 | requests to URIs starting with certain context path. According to the
|
| 62 | Servlet specification, the context path may be an empty string, or a
|
| 63 | string starting with '/'. The rules to define the names for this context
|
| 64 | path are the following:</p>
|
| 65 |
|
| 66 | <ul>
|
| 67 | <li>If the context path is a zero length string, the <em>base name</em> is
|
| 68 | <code>"ROOT"</code> (uppercase)</li>
|
| 69 | <li>If the context path is not a zero length string, the <em>base
|
| 70 | name</em> is the context path with the leading '/' removed and any
|
| 71 | remaining '/' characters in the path replaced with '#'.</li>
|
| 72 | </ul>
|
| 73 |
|
| 74 | <p>To help clarify these rules, some examples are given in the following
|
| 75 | table.</p>
|
| 76 |
|
| 77 | <table class="detail-table">
|
| 78 | <tr>
|
| 79 | <td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Context Path</font></td>
|
| 80 | <td bgcolor="#039acc" valign="top"><font color="#000000" size="-1" face="arial,helvetica,sanserif">Base File Name</font></td>
|
| 81 | </tr>
|
| 82 | <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>
|
| 83 | <tr>
|
| 84 | <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>
|
| 85 | </tr>
|
| 86 | <tr>
|
| 87 | <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif"><i>Empty String</i></font></td>
|
| 88 | <td bgcolor="#a0ddf0" valign="top" align="left"><font color="#000000" size="-1" face="arial,helvetica,sanserif">ROOT</font></td>
|
| 89 | </tr>
|
| 90 | </table>
|
| 91 |
|
| 92 | <p>If you want to deploy a WAR file or a directory using a context path that
|
| 93 | is not related to the base file name then one of the following options must
|
| 94 | be used to prevent double-deployment:
|
| 95 | </p>
|
| 96 | <ul>
|
| 97 | <li>Disable autoDeploy and deployOnStartup and define all
|
| 98 | <strong>Context</strong>s in server.xml</li>
|
| 99 | <li>Locate the WAR and/or directory outside of the Host's appBase and use
|
| 100 | a context.xml file with a docBase attribute to define it.</li>
|
| 101 | </ul>
|
| 102 | </blockquote></td></tr></table>
|
| 103 |
|
| 104 | <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>
|
| 105 | <p><b>It is NOT recommended to place
|
| 106 | <Context> elements directly in the server.xml file.</b> This
|
| 107 | is because it makes modifying the <strong>Context</strong> configuration
|
| 108 | more invasive since the main <code>conf/server.xml</code> file cannot be
|
| 109 | reloaded without restarting Tomcat.</p>
|
| 110 |
|
| 111 | <p>Individual <strong>Context</strong> elements may be explicitly defined:
|
| 112 | </p>
|
| 113 | <ul>
|
| 114 | <li>In an individual file at <code>/META-INF/context.xml</code> inside the
|
| 115 | application files. In Tomcat 6 this file is automatically copied to
|
| 116 | <code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> and renamed to
|
| 117 | application's base file name plus a ".xml" extension.
|
| 118 | (This automated copying became optional in Tomcat 7).
|
| 119 | </li>
|
| 120 | <li>In individual files (with a ".xml" extension) in the
|
| 121 | <code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> directory.
|
| 122 | The context path will be derived from the base name of the file
|
| 123 | (the file name less the .xml extension). This file will always take precedence
|
| 124 | over any context.xml file packaged in the web application's META-INF
|
| 125 | directory.</li>
|
| 126 | <li>Inside a <a href="host.html">Host</a> element in the main
|
| 127 | <code>conf/server.xml</code>.</li>
|
| 128 | </ul>
|
| 129 |
|
| 130 | <p>Default <strong>Context</strong> elements may be defined that apply to
|
| 131 | multiple web applications. Configuration for an individual web application
|
| 132 | will override anything configured in one of these defaults. Any nested
|
| 133 | elements, e.g. <Resource> elements, that are defined in a default
|
| 134 | <strong>Context</strong> will be created once for each
|
| 135 | <strong>Context</strong> to which the default applies. They will <b>not</b> be
|
| 136 | shared between <strong>Context</strong> elements.
|
| 137 | </p>
|
| 138 | <ul>
|
| 139 | <li>In the <code>$CATALINA_BASE/conf/context.xml</code> file:
|
| 140 | the Context element information will be loaded by all web applications.</li>
|
| 141 | <li>In the
|
| 142 | <code>$CATALINA_BASE/conf/[enginename]/[hostname]/context.xml.default</code>
|
| 143 | file: the Context element information will be loaded by all web applications
|
| 144 | of that host.</li>
|
| 145 | </ul>
|
| 146 |
|
| 147 | <p>With the exception of server.xml, files that define <strong>Context
|
| 148 | </strong> elements may only define a single <strong>Context</strong> element.
|
| 149 | </p>
|
| 150 |
|
| 151 | <p>In addition to explicitly specified Context elements, there are
|
| 152 | several techniques by which Context elements can be created automatically
|
| 153 | for you. See <a href="host.html#Automatic_Application_Deployment">
|
| 154 | Automatic Application Deployment</a> and
|
| 155 | <a href="host.html#User_Web_Applications">User Web Applications</a>
|
| 156 | for more information.</p>
|
| 157 |
|
| 158 | <p>To define multiple contexts that use a single WAR file or directory,
|
| 159 | use one of the options described in the <a href="#Naming">Naming</a>
|
| 160 | section above for creating a <strong>Context</strong> that has a path
|
| 161 | that is not related to the base file name.</p>
|
| 162 | </blockquote></td></tr></table>
|
| 163 |
|
| 164 | </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>
|
| 165 |
|
| 166 | <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>
|
| 167 |
|
| 168 | <p>All implementations of <strong>Context</strong>
|
| 169 | support the following attributes:</p>
|
| 170 |
|
| 171 | <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">
|
| 172 | <p>This value represents the delay in seconds between the
|
| 173 | invocation of the backgroundProcess method on this context and
|
| 174 | its child containers, including all wrappers.
|
| 175 | Child containers will not be invoked if their delay value is not
|
| 176 | negative (which would mean they are using their own processing
|
| 177 | thread). Setting this to a positive value will cause
|
| 178 | a thread to be spawn. After waiting the specified amount of time,
|
| 179 | the thread will invoke the backgroundProcess method on this host
|
| 180 | and all its child containers. A context will use background
|
| 181 | processing to perform session expiration and class monitoring for
|
| 182 | reloading. If not specified, the default value for this attribute is
|
| 183 | -1, which means the context will rely on the background processing
|
| 184 | thread of its parent host.</p>
|
| 185 | </td></tr><tr><td align="left" valign="center"><code>className</code></td><td align="left" valign="center">
|
| 186 | <p>Java class name of the implementation to use. This class must
|
| 187 | implement the <code>org.apache.catalina.Context</code> interface.
|
| 188 | If not specified, the standard value (defined below) will be used.</p>
|
| 189 | </td></tr><tr><td align="left" valign="center"><code>cookies</code></td><td align="left" valign="center">
|
| 190 | <p>Set to <code>true</code> if you want cookies to be used for
|
| 191 | session identifier communication if supported by the client (this
|
| 192 | is the default). Set to <code>false</code> if you want to disable
|
| 193 | the use of cookies for session identifier communication, and rely
|
| 194 | only on URL rewriting by the application.</p>
|
| 195 | </td></tr><tr><td align="left" valign="center"><code>crossContext</code></td><td align="left" valign="center">
|
| 196 | <p>Set to <code>true</code> if you want calls within this application
|
| 197 | to <code>ServletContext.getContext()</code> to successfully return a
|
| 198 | request dispatcher for other web applications running on this virtual
|
| 199 | host. Set to <code>false</code> (the default) in security
|
| 200 | conscious environments, to make <code>getContext()</code> always
|
| 201 | return <code>null</code>.</p>
|
| 202 | </td></tr><tr><td align="left" valign="center"><code>disableURLRewriting</code></td><td align="left" valign="center">
|
| 203 | <p>Set to <code>true</code> to disable support for using URL rewriting
|
| 204 | to track session IDs for clients of this Context. URL rewriting is an
|
| 205 | optional component of the servlet 2.5 specification but disabling URL
|
| 206 | rewriting will result in non-compliant behaviour since the specification
|
| 207 | requires that there <em>must</em> be a way to retain sessions if the
|
| 208 | client doesn't allow session cookies. If not specified, the
|
| 209 | specification compliant default value of <code>false</code> will be
|
| 210 | used.</p>
|
| 211 | </td></tr><tr><td align="left" valign="center"><strong><code>docBase</code></strong></td><td align="left" valign="center">
|
| 212 | <p>The <em>Document Base</em> (also known as the <em>Context
|
| 213 | Root</em>) directory for this web application, or the pathname
|
| 214 | to the web application archive file (if this web application is
|
| 215 | being executed directly from the WAR file). You may specify
|
| 216 | an absolute pathname for this directory or WAR file, or a pathname
|
| 217 | that is relative to the <code>appBase</code> directory of the
|
| 218 | owning <a href="host.html">Host</a>.</p>
|
| 219 | <p>The value of this field must not be set unless the Context element is
|
| 220 | defined in server.xml or the <code>docBase</code> is not located under
|
| 221 | the <a href="host.html">Host</a>'s <code>appBase</code>.</p>
|
| 222 | <p>If a symbolic link is used for docBase then changes to the
|
| 223 | symbolic link will only be effective after a Tomcat restart or
|
| 224 | by undeploying and redeploying the context. A context reload is not
|
| 225 | sufficient.</p>
|
| 226 | </td></tr><tr><td align="left" valign="center"><code>override</code></td><td align="left" valign="center">
|
| 227 | <p>Set to <code>true</code> to have explicit settings in this
|
| 228 | Context element override any corresponding settings in either the global
|
| 229 | or <a href="host.html">Host</a> default contexts. By default, settings
|
| 230 | from a default context will be used.</p>
|
| 231 | </td></tr><tr><td align="left" valign="center"><code>privileged</code></td><td align="left" valign="center">
|
| 232 | <p>Set to <code>true</code> to allow this context to use container
|
| 233 | servlets, like the manager servlet. Use of the <code>privileged</code>
|
| 234 | attribute will change the context's parent class loader to be the
|
| 235 | <em>Server</em> class loader rather than the <em>Shared</em> class
|
| 236 | loader. Note that in a default installation, the <em>Common</em> class
|
| 237 | loader is used for both the <em>Server</em> and the <em>Shared</em>
|
| 238 | class loaders.</p>
|
| 239 | </td></tr><tr><td align="left" valign="center"><code>path</code></td><td align="left" valign="center">
|
| 240 | <p>The <em>context path</em> of this web application, which is
|
| 241 | matched against the beginning of each request URI to select the
|
| 242 | appropriate web application for processing. All of the context paths
|
| 243 | within a particular <a href="host.html">Host</a> must be unique.
|
| 244 | If you specify a context path of an empty string (""), you are
|
| 245 | defining the <em>default</em> web application for this Host, which
|
| 246 | will process all requests not assigned to other Contexts.</p>
|
| 247 | <p>This attribute must only be used when statically defining a Context
|
| 248 | in server.xml. In all other circumstances, the path will be inferred
|
| 249 | from the filenames used for either the .xml context file or the docBase.
|
| 250 | </p>
|
| 251 | <p>Even when statically defining a Context in server.xml, this attribute
|
| 252 | must not be set unless either the docBase is not located under the
|
| 253 | <a href="host.html">Host</a>'s <code>appBase</code> or both
|
| 254 | <code>deployOnStartup</code> and <code>autoDeploy</code> are false. If
|
| 255 | this rule is not followed, double deployment is likely to result.</p>
|
| 256 | </td></tr><tr><td align="left" valign="center"><code>reloadable</code></td><td align="left" valign="center">
|
| 257 | <p>Set to <code>true</code> if you want Catalina to monitor classes in
|
| 258 | <code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
|
| 259 | changes, and automatically reload the web application if a change
|
| 260 | is detected. This feature is very useful during application
|
| 261 | development, but it requires significant runtime overhead and is
|
| 262 | not recommended for use on deployed production applications. That's
|
| 263 | why the default setting for this attribute is <i>false</i>. You
|
| 264 | can use the <a href="../manager-howto.html">Manager</a> web
|
| 265 | application, however, to trigger reloads of deployed applications
|
| 266 | on demand.</p>
|
| 267 | </td></tr><tr><td align="left" valign="center"><code>sessionCookieDomain</code></td><td align="left" valign="center">
|
| 268 | <p>The domain to be used for all session cookies created for this
|
| 269 | Context. If not set, no domain will be specified for session cookies.
|
| 270 | </p>
|
| 271 | </td></tr><tr><td align="left" valign="center"><code>sessionCookieName</code></td><td align="left" valign="center">
|
| 272 | <p>The name to be used for all session cookies created for this
|
| 273 | Context. If not set, the default of JSESSIONID will be used. Note that
|
| 274 | this default will be overridden by the
|
| 275 | <strong>org.apache.catalina.SESSION_COOKIE_NAME</strong> system
|
| 276 | property.</p>
|
| 277 | </td></tr><tr><td align="left" valign="center"><code>sessionCookiePath</code></td><td align="left" valign="center">
|
| 278 | <p>The path to be used for all session cookies created for this
|
| 279 | Context. If not set, the context path will be used. Note that this will
|
| 280 | be overridden by the <strong>emptySessionPath</strong> attribute on the
|
| 281 | connector used to access this Context.</p>
|
| 282 | </td></tr><tr><td align="left" valign="center"><code>tldValidation</code></td><td align="left" valign="center">
|
| 283 | <p>If the value of this flag is <code>true</code>, the TLD files
|
| 284 | will be XML validated on context startup. If the
|
| 285 | <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
|
| 286 | <a href="systemprops.html">system property</a> is set to
|
| 287 | <code>true</code>, the default value of this attribute will be
|
| 288 | <code>true</code>, else the default value will be <code>false</code>.
|
| 289 | Setting this attribute to <code>true</code> will incur a performance
|
| 290 | penalty.</p>
|
| 291 | </td></tr><tr><td align="left" valign="center"><code>useHttpOnly</code></td><td align="left" valign="center">
|
| 292 | <p>Should the HttpOnly flag be set on session cookies to prevent client
|
| 293 | side script from accessing the session ID? Defaults to
|
| 294 | <code>false</code>.</p>
|
| 295 | </td></tr><tr><td align="left" valign="center"><code>wrapperClass</code></td><td align="left" valign="center">
|
| 296 | <p>Java class name of the <code>org.apache.catalina.Wrapper</code>
|
| 297 | implementation class that will be used for servlets managed by this
|
| 298 | Context. If not specified, a standard default value will be used.</p>
|
| 299 | </td></tr><tr><td align="left" valign="center"><code>xmlBlockExternal</code></td><td align="left" valign="center">
|
| 300 | <p>If the value of this flag is <code>true</code>, the parsing of
|
| 301 | <code>web.xml</code>, <code>web-fragment.xml</code>, <code>*.tld</code>,
|
| 302 | <code>*.jspx</code>, <code>*.tagx</code> and <code>tagPlugins.xml</code>
|
| 303 | files for this web application will not permit external entities to be
|
| 304 | loaded. If a <code>SecurityManager</code> is configured then the default
|
| 305 | value of this attribute will be <code>true</code>, else the default
|
| 306 | value will be <code>false</code>.</p>
|
| 307 | </td></tr><tr><td align="left" valign="center"><code>xmlNamespaceAware</code></td><td align="left" valign="center">
|
| 308 | <p>If the value of this flag is <code>true</code>, the parsing of the
|
| 309 | <code>web.xml</code> file for this web application will be
|
| 310 | namespace-aware. Note that <code>*.tld</code>, <code>*.jspx</code> and
|
| 311 | <code>*.tagx</code> files are always parsed using a namespace-aware
|
| 312 | parser and that the <code>tagPlugins.xml</code> file (if any) is never
|
| 313 | parsed using a namespace-aware parser. Note also that if you turn this
|
| 314 | flag on, you should probably also turn <code>xmlValidation</code> on. If
|
| 315 | the <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
|
| 316 | <a href="systemprops.html">system property</a> is set to
|
| 317 | <code>true</code>, the default value of this attribute will be
|
| 318 | <code>true</code>, else the default value will be <code>false</code>.
|
| 319 | Setting this attribute to <code>true</code> will incur a performance
|
| 320 | penalty.</p>
|
| 321 | </td></tr><tr><td align="left" valign="center"><code>xmlValidation</code></td><td align="left" valign="center">
|
| 322 | <p>If the value of this flag is <code>true</code>, the parsing of the
|
| 323 | <code>web.xml</code> file for this web application will use a validating
|
| 324 | parser. If the
|
| 325 | <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
|
| 326 | <a href="systemprops.html">system property</a> is set to
|
| 327 | <code>true</code>, the default value of this attribute will be
|
| 328 | <code>true</code>, else the default value will be <code>false</code>.
|
| 329 | Setting this attribute to <code>true</code> will incur a performance
|
| 330 | penalty.</p>
|
| 331 | </td></tr></table>
|
| 332 |
|
| 333 | </blockquote></td></tr></table>
|
| 334 |
|
| 335 |
|
| 336 | <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>
|
| 337 |
|
| 338 | <p>The standard implementation of <strong>Context</strong> is
|
| 339 | <strong>org.apache.catalina.core.StandardContext</strong>.
|
| 340 | It supports the following additional attributes (in addition to the
|
| 341 | common attributes listed above):</p>
|
| 342 |
|
| 343 | <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">
|
| 344 | <p>If the value of this flag is <code>true</code>, symlinks will be
|
| 345 | allowed inside the web application, pointing to resources outside the
|
| 346 | web application base path. If not specified, the default value
|
| 347 | of the flag is <code>false</code>.</p>
|
| 348 | <p><b>NOTE: This flag MUST NOT be set to true on the Windows platform
|
| 349 | (or any other OS which does not have a case sensitive filesystem),
|
| 350 | as it will disable case sensitivity checks, allowing JSP source code
|
| 351 | disclosure, among other security problems.</b></p>
|
| 352 | </td></tr><tr><td align="left" valign="center"><code>antiJARLocking</code></td><td align="left" valign="center">
|
| 353 | <p>If true, the Tomcat classloader will take extra measures to avoid
|
| 354 | JAR file locking when resources are accessed inside JARs through URLs.
|
| 355 | This will impact startup time of applications, but could prove to be
|
| 356 | useful on platforms or configurations where file locking can occur.
|
| 357 | If not specified, the default value is <code>false</code>.</p>
|
| 358 |
|
| 359 | <p><code>antiJARLocking</code> is a subset of
|
| 360 | <code>antiResourceLocking</code> and therefore, to prevent duplicate
|
| 361 | work and possible issues, only one of these attributes should be set
|
| 362 | to <code>true</code> at any one time.</p>
|
| 363 | </td></tr><tr><td align="left" valign="center"><code>antiResourceLocking</code></td><td align="left" valign="center">
|
| 364 | <p>If true, Tomcat will prevent any file locking.
|
| 365 | This will significantly impact startup time of applications,
|
| 366 | but allows full webapp hot deploy and undeploy on platforms
|
| 367 | or configurations where file locking can occur.
|
| 368 | If not specified, the default value is <code>false</code>.</p>
|
| 369 |
|
| 370 | <p><code>antiJARLocking</code> is a subset of
|
| 371 | <code>antiResourceLocking</code> and therefore, to prevent duplicate
|
| 372 | work and possible issues, only one of these attributes should be set
|
| 373 | to <code>true</code> at any one time.</p>
|
| 374 |
|
| 375 | <p>Please note that setting this to <code>true</code> has some side
|
| 376 | effects, including the disabling of JSP reloading in a running server:
|
| 377 | see <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=37668">
|
| 378 | Bugzilla 37668</a>.</p>
|
| 379 |
|
| 380 | <p>Please note that setting this flag to true in applications that are
|
| 381 | outside the appBase for the Host (the <code>webapps</code> directory
|
| 382 | by default) will cause the application to be <strong>deleted</strong> on
|
| 383 | Tomcat shutdown. You probably don't want to do this, so think twice
|
| 384 | before setting antiResourceLocking=true on a webapp that's outside the
|
| 385 | appBase for its Host.</p>
|
| 386 | </td></tr><tr><td align="left" valign="center"><code>cacheMaxSize</code></td><td align="left" valign="center">
|
| 387 | <p>Maximum size of the static resource cache in kilobytes.
|
| 388 | If not specified, the default value is <code>10240</code>
|
| 389 | (10 megabytes).</p>
|
| 390 | </td></tr><tr><td align="left" valign="center"><code>cacheObjectMaxSize</code></td><td align="left" valign="center">
|
| 391 | <p>Maximum size of the static resource that will be placed in the cache.
|
| 392 | If not specified, the default value is <code>512</code>
|
| 393 | (512 kilobytes). If this value is greater than
|
| 394 | <code>cacheMaxSize/20</code> it will be reduced to
|
| 395 | <code>cacheMaxSize/20</code>.</p>
|
| 396 | </td></tr><tr><td align="left" valign="center"><code>cacheTTL</code></td><td align="left" valign="center">
|
| 397 | <p>Amount of time in milliseconds between cache entries revalidation.
|
| 398 | If not specified, the default value is <code>5000</code>
|
| 399 | (5 seconds).</p>
|
| 400 | </td></tr><tr><td align="left" valign="center"><code>cachingAllowed</code></td><td align="left" valign="center">
|
| 401 | <p>If the value of this flag is <code>true</code>, the cache for static
|
| 402 | resources will be used. If not specified, the default value
|
| 403 | of the flag is <code>true</code>.</p>
|
| 404 | </td></tr><tr><td align="left" valign="center"><code>caseSensitive</code></td><td align="left" valign="center">
|
| 405 | <p><strong>Deprecated.</strong> This option is removed in Tomcat 7
|
| 406 | onwards where the default of <code>true</code> is always used.</p>
|
| 407 | <p>If the value of this flag is <code>false</code>, all case sensitivity
|
| 408 | checks will be disabled. If not
|
| 409 | specified, the default value of the flag is <code>true</code>.</p>
|
| 410 | <p><b>NOTE: This flag MUST NOT be set to false on the Windows platform
|
| 411 | (or any other OS which does not have a case sensitive filesystem),
|
| 412 | as it will disable case sensitivity checks, allowing JSP source code
|
| 413 | disclosure, among other security problems.</b></p>
|
| 414 | </td></tr><tr><td align="left" valign="center"><code>clearReferencesHttpClientKeepAliveThread</code></td><td align="left" valign="center">
|
| 415 | <p>If <code>true</code> and an <code>sun.net.www.http.HttpClient</code>
|
| 416 | keep-alive timer thread has been started by this web application and is
|
| 417 | still running, Tomcat will change the context class loader for that
|
| 418 | thread from the current <code>WebappClassLoader</code> to
|
| 419 | <code>WebappClassLoader#parent</code> to prevent a memory leak. Note
|
| 420 | that the keep-alive timer thread will stop on its own once the
|
| 421 | keep-alives all expire however, on a busy system that might not happen
|
| 422 | for some time. If not specified, the default value of
|
| 423 | <code>true</code> will be used.</p>
|
| 424 | </td></tr><tr><td align="left" valign="center"><code>clearReferencesStopThreads</code></td><td align="left" valign="center">
|
| 425 | <p>If <code>true</code>, Tomcat attempts to terminate threads that have
|
| 426 | been started by the web application. Stopping threads is performed via
|
| 427 | the deprecated (for good reason) <code>Thread.stop()</code> method and
|
| 428 | is likely to result in instability. As such, enabling this should be
|
| 429 | viewed as an option of last resort in a development environment and is
|
| 430 | not recommended in a production environment. If not specified, the
|
| 431 | default value of <code>false</code> will be used.</p>
|
| 432 | </td></tr><tr><td align="left" valign="center"><code>clearReferencesStopTimerThreads</code></td><td align="left" valign="center">
|
| 433 | <p>If <code>true</code>, Tomcat attempts to terminate
|
| 434 | <code>java.util.Timer</code> threads that have been started by the web
|
| 435 | application. Unlike standard threads, timer threads can be stopped
|
| 436 | safely although there may still be side-effects for the application. If
|
| 437 | not specified, the default value of <code>false</code> will be used.</p>
|
| 438 | </td></tr><tr><td align="left" valign="center"><code>clearReferencesThreadLocals</code></td><td align="left" valign="center">
|
| 439 | <p>If <code>true</code>, Tomcat attempts to clear any ThreadLocal
|
| 440 | objects that are instances of classes loaded by this class loader.
|
| 441 | Failure to remove any such objects will result in a memory leak on web
|
| 442 | application stop, undeploy or reload. If not specified, the default
|
| 443 | value of <code>false</code> will be used since the clearing of the
|
| 444 | ThreadLocal objects is not performed in a thread-safe manner.</p>
|
| 445 | </td></tr><tr><td align="left" valign="center"><code>processTlds</code></td><td align="left" valign="center">
|
| 446 | <p>Whether the context should process TLDs on startup. The default
|
| 447 | is true. The false setting is intended for special cases
|
| 448 | that know in advance TLDs are not part of the webapp.</p>
|
| 449 | </td></tr><tr><td align="left" valign="center"><code>swallowOutput</code></td><td align="left" valign="center">
|
| 450 | <p>If the value of this flag is <code>true</code>, the bytes output to
|
| 451 | System.out and System.err by the web application will be redirected to
|
| 452 | the web application logger. If not specified, the default value
|
| 453 | of the flag is <code>false</code>.</p>
|
| 454 | </td></tr><tr><td align="left" valign="center"><code>unloadDelay</code></td><td align="left" valign="center">
|
| 455 | <p>Number of ms that the container will wait for servlets to unload.
|
| 456 | If not specified, the default value is <code>2000</code> ms.</p>
|
| 457 | </td></tr><tr><td align="left" valign="center"><code>unpackWAR</code></td><td align="left" valign="center">
|
| 458 | <p>If true, Tomcat will unpack all compressed web applications before
|
| 459 | running them.
|
| 460 | If not specified, the default value is <code>true</code>.</p>
|
| 461 | </td></tr><tr><td align="left" valign="center"><code>useNaming</code></td><td align="left" valign="center">
|
| 462 | <p>Set to <code>true</code> (the default) to have Catalina enable a
|
| 463 | JNDI <code>InitialContext</code> for this web application that is
|
| 464 | compatible with Java2 Enterprise Edition (J2EE) platform
|
| 465 | conventions.</p>
|
| 466 | </td></tr><tr><td align="left" valign="center"><code>workDir</code></td><td align="left" valign="center">
|
| 467 | <p>Pathname to a scratch directory to be provided by this Context
|
| 468 | for temporary read-write use by servlets within the associated web
|
| 469 | application. This directory will be made visible to servlets in the
|
| 470 | web application by a servlet context attribute (of type
|
| 471 | <code>java.io.File</code>) named
|
| 472 | <code>javax.servlet.context.tempdir</code> as described in the
|
| 473 | Servlet Specification. If not specified, a suitable directory
|
| 474 | underneath <code>$CATALINA_BASE/work</code> will be provided.</p>
|
| 475 | </td></tr></table>
|
| 476 |
|
| 477 | </blockquote></td></tr></table>
|
| 478 |
|
| 479 |
|
| 480 | </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>
|
| 481 |
|
| 482 | <p>You can nest at most one instance of the following utility components
|
| 483 | by nesting a corresponding element inside your <strong>Context</strong>
|
| 484 | element:</p>
|
| 485 | <ul>
|
| 486 | <li><a href="loader.html"><strong>Loader</strong></a> -
|
| 487 | Configure the web application class loader that will be used to load
|
| 488 | servlet and bean classes for this web application. Normally, the
|
| 489 | default configuration of the class loader will be sufficient.</li>
|
| 490 | <li><a href="manager.html"><strong>Manager</strong></a> -
|
| 491 | Configure the session manager that will be used to create, destroy,
|
| 492 | and persist HTTP sessions for this web application. Normally, the
|
| 493 | default configuration of the session manager will be sufficient.</li>
|
| 494 | <li><a href="realm.html"><strong>Realm</strong></a> -
|
| 495 | Configure a realm that will allow its
|
| 496 | database of users, and their associated roles, to be utilized solely
|
| 497 | for this particular web application. If not specified, this web
|
| 498 | application will utilize the Realm associated with the owning
|
| 499 | <a href="host.html">Host</a> or <a href="engine.html">Engine</a>.</li>
|
| 500 | <li><a href="resources.html"><strong>Resources</strong></a> -
|
| 501 | Configure the resource manager that will be used to access the static
|
| 502 | resources associated with this web application. Normally, the
|
| 503 | default configuration of the resource manager will be sufficient.</li>
|
| 504 | <li><strong>WatchedResource</strong> - The auto deployer will monitor the
|
| 505 | specified static resource of the web application for updates, and will
|
| 506 | reload the web application if is is updated. The content of this element
|
| 507 | must be a string.</li>
|
| 508 | </ul>
|
| 509 |
|
| 510 | </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>
|
| 511 |
|
| 512 |
|
| 513 | <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>
|
| 514 |
|
| 515 | <p>A context is associated with the
|
| 516 | <code>org.apache.catalina.core.ContainerBase.[enginename].[hostname].[path]</code>
|
| 517 | log category. Note that the brackets are actually part of the name, don't omit them.</p>
|
| 518 |
|
| 519 | </blockquote></td></tr></table>
|
| 520 |
|
| 521 |
|
| 522 | <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>
|
| 523 |
|
| 524 | <p>When you run a web server, one of the output files normally generated
|
| 525 | is an <em>access log</em>, which generates one line of information for
|
| 526 | each request processed by the server, in a standard format. Catalina
|
| 527 | includes an optional <a href="valve.html">Valve</a> implementation that
|
| 528 | can create access logs in the same standard format created by web servers,
|
| 529 | or in any number of custom formats.</p>
|
| 530 |
|
| 531 | <p>You can ask Catalina to create an access log for all requests
|
| 532 | processed by an <a href="engine.html">Engine</a>,
|
| 533 | <a href="host.html">Host</a>, or <a href="context.html">Context</a>
|
| 534 | by nesting a <a href="valve.html">Valve</a> element like this:</p>
|
| 535 |
|
| 536 | <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>
|
| 537 | <Context>
|
| 538 | ...
|
| 539 | <Valve className="org.apache.catalina.valves.AccessLogValve"
|
| 540 | prefix="localhost_access_log." suffix=".txt"
|
| 541 | pattern="common"/>
|
| 542 | ...
|
| 543 | </Context>
|
| 544 | </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>
|
| 545 |
|
| 546 | <p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
|
| 547 | for more information on the configuration attributes that are
|
| 548 | supported.</p>
|
| 549 |
|
| 550 | </blockquote></td></tr></table>
|
| 551 |
|
| 552 |
|
| 553 | <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>
|
| 554 |
|
| 555 | <p>If you use the standard <strong>Context</strong> implementation,
|
| 556 | the following configuration steps occur automatically when Catalina
|
| 557 | is started, or whenever this web application is reloaded. No special
|
| 558 | configuration is required to enable this feature.</p>
|
| 559 |
|
| 560 | <ul>
|
| 561 | <li>If you have not declared your own <a href="loader.html">Loader</a>
|
| 562 | element, a standard web application class loader will be configured.
|
| 563 | </li>
|
| 564 | <li>If you have not declared your own <a href="manager.html">Manager</a>
|
| 565 | element, a standard session manager will be configured.</li>
|
| 566 | <li>If you have not declared your own <a href="resources.html">Resources</a>
|
| 567 | element, a standard resources manager will be configured.</li>
|
| 568 | <li>The web application properties listed in <code>conf/web.xml</code>
|
| 569 | will be processed as defaults for this web application. This is used
|
| 570 | to establish default mappings (such as mapping the <code>*.jsp</code>
|
| 571 | extension to the corresponding JSP servlet), and other standard
|
| 572 | features that apply to all web applications.</li>
|
| 573 | <li>The web application properties listed in the
|
| 574 | <code>/WEB-INF/web.xml</code> resource for this web application
|
| 575 | will be processed (if this resource exists).</li>
|
| 576 | <li>If your web application has specified security constraints that might
|
| 577 | require user authentication, an appropriate Authenticator that
|
| 578 | implements the login method you have selected will be configured.</li>
|
| 579 | </ul>
|
| 580 |
|
| 581 | </blockquote></td></tr></table>
|
| 582 |
|
| 583 |
|
| 584 | <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>
|
| 585 |
|
| 586 | <p>You can configure named values that will be made visible to the
|
| 587 | web application as servlet context initialization parameters by nesting
|
| 588 | <code><Parameter></code> elements inside this element. For
|
| 589 | example, you can create an initialization parameter like this:</p>
|
| 590 | <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>
|
| 591 | <Context>
|
| 592 | ...
|
| 593 | <Parameter name="companyName" value="My Company, Incorporated"
|
| 594 | override="false"/>
|
| 595 | ...
|
| 596 | </Context>
|
| 597 | </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>
|
| 598 |
|
| 599 | <p>This is equivalent to the inclusion of the following element in the
|
| 600 | web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
|
| 601 | </p>
|
| 602 | <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>
|
| 603 | <context-param>
|
| 604 | <param-name>companyName</param-name>
|
| 605 | <param-value>My Company, Incorporated</param-value>
|
| 606 | </context-param>
|
| 607 | </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>
|
| 608 | <p>but does <em>not</em> require modification of the deployment descriptor
|
| 609 | to customize this value.</p>
|
| 610 |
|
| 611 | <p>The valid attributes for a <code><Parameter></code> element
|
| 612 | are as follows:</p>
|
| 613 |
|
| 614 | <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">
|
| 615 | <p>Optional, human-readable description of this context
|
| 616 | initialization parameter.</p>
|
| 617 | </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
|
| 618 | <p>The name of the context initialization parameter to be created.</p>
|
| 619 | </td></tr><tr><td align="left" valign="center"><code>override</code></td><td align="left" valign="center">
|
| 620 | <p>Set this to <code>false</code> if you do <strong>not</strong> want
|
| 621 | a <code><context-param></code> for the same parameter name,
|
| 622 | found in the web application deployment descriptor, to override the
|
| 623 | value specified here. By default, overrides are allowed.</p>
|
| 624 | </td></tr><tr><td align="left" valign="center"><strong><code>value</code></strong></td><td align="left" valign="center">
|
| 625 | <p>The parameter value that will be presented to the application
|
| 626 | when requested by calling
|
| 627 | <code>ServletContext.getInitParameter()</code>.</p>
|
| 628 | </td></tr></table>
|
| 629 |
|
| 630 | </blockquote></td></tr></table>
|
| 631 |
|
| 632 |
|
| 633 | <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>
|
| 634 |
|
| 635 | <p>You can configure named values that will be made visible to the
|
| 636 | web application as environment entry resources, by nesting
|
| 637 | <code><Environment></code> entries inside this element. For
|
| 638 | example, you can create an environment entry like this:</p>
|
| 639 | <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>
|
| 640 | <Context>
|
| 641 | ...
|
| 642 | <Environment name="maxExemptions" value="10"
|
| 643 | type="java.lang.Integer" override="false"/>
|
| 644 | ...
|
| 645 | </Context>
|
| 646 | </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>
|
| 647 |
|
| 648 | <p>This is equivalent to the inclusion of the following element in the
|
| 649 | web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
|
| 650 | </p>
|
| 651 | <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>
|
| 652 | <env-entry>
|
| 653 | <env-entry-name>maxExemptions</env-entry-name>
|
| 654 | <env-entry-value>10</env-entry-value>
|
| 655 | <env-entry-type>java.lang.Integer</env-entry-type>
|
| 656 | </env-entry>
|
| 657 | </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>
|
| 658 | <p>but does <em>not</em> require modification of the deployment descriptor
|
| 659 | to customize this value.</p>
|
| 660 |
|
| 661 | <p>The valid attributes for an <code><Environment></code> element
|
| 662 | are as follows:</p>
|
| 663 |
|
| 664 | <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">
|
| 665 | <p>Optional, human-readable description of this environment entry.</p>
|
| 666 | </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
|
| 667 | <p>The name of the environment entry to be created, relative to the
|
| 668 | <code>java:comp/env</code> context.</p>
|
| 669 | </td></tr><tr><td align="left" valign="center"><code>override</code></td><td align="left" valign="center">
|
| 670 | <p>Set this to <code>false</code> if you do <strong>not</strong> want
|
| 671 | an <code><env-entry></code> for the same environment entry name,
|
| 672 | found in the web application deployment descriptor, to override the
|
| 673 | value specified here. By default, overrides are allowed.</p>
|
| 674 | </td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
|
| 675 | <p>The fully qualified Java class name expected by the web application
|
| 676 | for this environment entry. Must be one of the legal values for
|
| 677 | <code><env-entry-type></code> in the web application deployment
|
| 678 | descriptor: <code>java.lang.Boolean</code>,
|
| 679 | <code>java.lang.Byte</code>, <code>java.lang.Character</code>,
|
| 680 | <code>java.lang.Double</code>, <code>java.lang.Float</code>,
|
| 681 | <code>java.lang.Integer</code>, <code>java.lang.Long</code>,
|
| 682 | <code>java.lang.Short</code>, or <code>java.lang.String</code>.</p>
|
| 683 | </td></tr><tr><td align="left" valign="center"><strong><code>value</code></strong></td><td align="left" valign="center">
|
| 684 | <p>The parameter value that will be presented to the application
|
| 685 | when requested from the JNDI context. This value must be convertable
|
| 686 | to the Java type defined by the <code>type</code> attribute.</p>
|
| 687 | </td></tr></table>
|
| 688 |
|
| 689 | </blockquote></td></tr></table>
|
| 690 |
|
| 691 |
|
| 692 | <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>
|
| 693 |
|
| 694 | <p>If you have implemented a Java object that needs to know when this
|
| 695 | <strong>Context</strong> is started or stopped, you can declare it by
|
| 696 | nesting a <strong>Listener</strong> element inside this element. The
|
| 697 | class name you specify must implement the
|
| 698 | <code>org.apache.catalina.LifecycleListener</code> interface, and
|
| 699 | the class must be packaged in a jar and placed in the
|
| 700 | <code>$CATALINA_HOME/lib</code> directory.
|
| 701 | It will be notified about the occurrence of the corresponding
|
| 702 | lifecycle events. Configuration of such a listener looks like this:</p>
|
| 703 |
|
| 704 | <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>
|
| 705 | <Context>
|
| 706 | ...
|
| 707 | <Listener className="com.mycompany.mypackage.MyListener" ... >
|
| 708 | ...
|
| 709 | </Context>
|
| 710 | </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>
|
| 711 |
|
| 712 | <p>Note that a Listener can have any number of additional properties
|
| 713 | that may be configured from this element. Attribute names are matched
|
| 714 | to corresponding JavaBean property names using the standard property
|
| 715 | method naming patterns.</p>
|
| 716 |
|
| 717 | </blockquote></td></tr></table>
|
| 718 |
|
| 719 |
|
| 720 | <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>
|
| 721 |
|
| 722 | <p>You can ask Catalina to check the IP address, or host name, on every
|
| 723 | incoming request directed to the surrounding
|
| 724 | <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
|
| 725 | <a href="context.html">Context</a> element. The remote address or name
|
| 726 | will be checked against a configured list of "accept" and/or "deny"
|
| 727 | filters, which are defined using <code>java.util.regex</code> Regular
|
| 728 | Expression syntax. Requests that come from locations that are
|
| 729 | not accepted will be rejected with an HTTP "Forbidden" error.
|
| 730 | Example filter declarations:</p>
|
| 731 |
|
| 732 | <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>
|
| 733 | <Context>
|
| 734 | ...
|
| 735 | <Valve className="org.apache.catalina.valves.RemoteHostValve"
|
| 736 | allow=".*\.mycompany\.com|www\.yourcompany\.com"/>
|
| 737 | <Valve className="org.apache.catalina.valves.RemoteAddrValve"
|
| 738 | deny="192\.168\.1\.\d+"/>
|
| 739 | ...
|
| 740 | </Context>
|
| 741 | </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>
|
| 742 |
|
| 743 | <p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
|
| 744 | and <a href="valve.html#Remote Host Filter">Remote Host Filter</a> for
|
| 745 | more information about the configuration options that are supported.</p>
|
| 746 |
|
| 747 | </blockquote></td></tr></table>
|
| 748 |
|
| 749 |
|
| 750 | <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>
|
| 751 |
|
| 752 | <p>You can declare the characteristics of the resource
|
| 753 | to be returned for JNDI lookups of <code><resource-ref></code> and
|
| 754 | <code><resource-env-ref></code> elements in the web application
|
| 755 | deployment descriptor. You <strong>MUST</strong> also define
|
| 756 | the needed resource parameters as attributes of the <code>Resource</code>
|
| 757 | element, to configure the object factory to be used (if not known to Tomcat
|
| 758 | already), and the properties used to configure that object factory.</p>
|
| 759 |
|
| 760 | <p>For example, you can create a resource definition like this:</p>
|
| 761 | <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>
|
| 762 | <Context>
|
| 763 | ...
|
| 764 | <Resource name="jdbc/EmployeeDB" auth="Container"
|
| 765 | type="javax.sql.DataSource"
|
| 766 | description="Employees Database for HR Applications"/>
|
| 767 | ...
|
| 768 | </Context>
|
| 769 | </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>
|
| 770 |
|
| 771 | <p>This is equivalent to the inclusion of the following element in the
|
| 772 | web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
|
| 773 | <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>
|
| 774 | <resource-ref>
|
| 775 | <description>Employees Database for HR Applications</description>
|
| 776 | <res-ref-name>jdbc/EmployeeDB</res-ref-name>
|
| 777 | <res-ref-type>javax.sql.DataSource</res-ref-type>
|
| 778 | <res-auth>Container</res-auth>
|
| 779 | </resource-ref>
|
| 780 | </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>
|
| 781 |
|
| 782 | <p>but does <em>not</em> require modification of the deployment
|
| 783 | descriptor to customize this value.</p>
|
| 784 |
|
| 785 | <p>The valid attributes for a <code><Resource></code> element
|
| 786 | are as follows:</p>
|
| 787 |
|
| 788 | <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">
|
| 789 | <p>Specify whether the web Application code signs on to the
|
| 790 | corresponding resource manager programatically, or whether the
|
| 791 | Container will sign on to the resource manager on behalf of the
|
| 792 | application. The value of this attribute must be
|
| 793 | <code>Application</code> or <code>Container</code>. This
|
| 794 | attribute is <strong>required</strong> if the web application
|
| 795 | will use a <code><resource-ref></code> element in the web
|
| 796 | application deployment descriptor, but is optional if the
|
| 797 | application uses a <code><resource-env-ref></code> instead.</p>
|
| 798 | </td></tr><tr><td align="left" valign="center"><code>description</code></td><td align="left" valign="center">
|
| 799 | <p>Optional, human-readable description of this resource.</p>
|
| 800 | </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
|
| 801 | <p>The name of the resource to be created, relative to the
|
| 802 | <code>java:comp/env</code> context.</p>
|
| 803 | </td></tr><tr><td align="left" valign="center"><code>scope</code></td><td align="left" valign="center">
|
| 804 | <p>Specify whether connections obtained through this resource
|
| 805 | manager can be shared. The value of this attribute must be
|
| 806 | <code>Shareable</code> or <code>Unshareable</code>. By default,
|
| 807 | connections are assumed to be shareable.</p>
|
| 808 | </td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
|
| 809 | <p>The fully qualified Java class name expected by the web
|
| 810 | application when it performs a lookup for this resource.</p>
|
| 811 | </td></tr></table>
|
| 812 |
|
| 813 |
|
| 814 | </blockquote></td></tr></table>
|
| 815 |
|
| 816 |
|
| 817 | <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>
|
| 818 |
|
| 819 | <p>This element is used to create a link to a global JNDI resource. Doing
|
| 820 | a JNDI lookup on the link name will then return the linked global
|
| 821 | resource.</p>
|
| 822 |
|
| 823 | <p>For example, you can create a resource link like this:</p>
|
| 824 | <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>
|
| 825 | <Context>
|
| 826 | ...
|
| 827 | <ResourceLink name="linkToGlobalResource"
|
| 828 | global="simpleValue"
|
| 829 | type="java.lang.Integer"
|
| 830 | ...
|
| 831 | </Context>
|
| 832 | </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>
|
| 833 |
|
| 834 | <p>The valid attributes for a <code><ResourceLink></code> element
|
| 835 | are as follows:</p>
|
| 836 |
|
| 837 | <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">
|
| 838 | <p>The name of the linked global resource in the
|
| 839 | global JNDI context.</p>
|
| 840 | </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
|
| 841 | <p>The name of the resource link to be created, relative to the
|
| 842 | <code>java:comp/env</code> context.</p>
|
| 843 | </td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
|
| 844 | <p>The fully qualified Java class name expected by the web
|
| 845 | application when it performs a lookup for this resource link.</p>
|
| 846 | </td></tr><tr><td align="left" valign="center"><code>factory</code></td><td align="left" valign="center">
|
| 847 | <p>The fully qualified Java class name for the class creating these objects.
|
| 848 | This class should implement the <code>javax.naming.spi.ObjectFactory</code> interface.</p>
|
| 849 | </td></tr></table>
|
| 850 |
|
| 851 | <p>When the attribute <code>factory="org.apache.naming.factory.DataSourceLinkFactory"</code> the resource link can be used with
|
| 852 | two additional attributes to allow a shared data source to be used with different credentials.
|
| 853 | When these two additional attributes are used in combination with the <code>javax.sql.DataSource</code>
|
| 854 | type, different contexts can share a global data source with different credentials.
|
| 855 | 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>
|
| 856 | 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)">
|
| 857 | <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,
|
| 858 | yet be able to control connections (or pools) in the global configuration.
|
| 859 | </p>
|
| 860 | <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">
|
| 861 | <p><code>username</code> value for the <code>getConnection(username, password)</code>
|
| 862 | call on the linked global DataSource.
|
| 863 | </p>
|
| 864 | </td></tr><tr><td align="left" valign="center"><code>password</code></td><td align="left" valign="center">
|
| 865 | <p><code>password</code> value for the <code>getConnection(username, password)</code>
|
| 866 | call on the linked global DataSource.
|
| 867 | </p>
|
| 868 | </td></tr></table>
|
| 869 | <p>Shared Data Source Example:</p>
|
| 870 | <p><strong>Warning:</strong> This feature works only if the global DataSource
|
| 871 | supports <code>getConnection(username, password)</code> method.
|
| 872 | <a href="http://commons.apache.org/dbcp/">Apache Commons DBCP</a> pool that
|
| 873 | Tomcat uses by default does not support it. See its Javadoc for
|
| 874 | <code>BasicDataSource</code> class.
|
| 875 | <a href="http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html">Apache Tomcat JDBC pool</a>
|
| 876 | (included with Tomcat 7 and later) does support it,
|
| 877 | but by default this support is disabled and can be enabled by
|
| 878 | <code>alternateUsernameAllowed</code> attribute. See its documentation
|
| 879 | for details. The example below uses Apache Tomcat JDBC pool.</p>
|
| 880 | <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>
|
| 881 | <GlobalNamingResources>
|
| 882 | ...
|
| 883 | <Resource name="sharedDataSource"
|
| 884 | global="sharedDataSource"
|
| 885 | type="javax.sql.DataSource"
|
| 886 | factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
|
| 887 | alternateUsernameAllowed="true"
|
| 888 | username="bar"
|
| 889 | password="barpass"
|
| 890 | ...
|
| 891 | ...
|
| 892 | </GlobalNamingResources>
|
| 893 |
|
| 894 | <Context path="/foo"...>
|
| 895 | ...
|
| 896 | <ResourceLink
|
| 897 | name="appDataSource"
|
| 898 | global="sharedDataSource"
|
| 899 | type="javax.sql.DataSource"
|
| 900 | factory="org.apache.naming.factory.DataSourceLinkFactory"
|
| 901 | username="foo"
|
| 902 | password="foopass"
|
| 903 | ...
|
| 904 | </Context>
|
| 905 | <Context path="/bar"...>
|
| 906 | ...
|
| 907 | <ResourceLink
|
| 908 | name="appDataSource"
|
| 909 | global="sharedDataSource"
|
| 910 | type="javax.sql.DataSource"
|
| 911 | ...
|
| 912 | </Context>
|
| 913 | </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>
|
| 914 | <p>When a request for <code>getConnection()</code> is made in the <code>/foo</code> context, the request is translated into
|
| 915 | <code>getConnection("foo","foopass")</code>, while a request in the <code>/bar</code> gets passed straight through.</p>
|
| 916 | </blockquote></td></tr></table>
|
| 917 |
|
| 918 | <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>
|
| 919 |
|
| 920 | <p>You can declare the characteristics of the UserTransaction
|
| 921 | to be returned for JNDI lookup for <code>java:comp/UserTransaction</code>.
|
| 922 | You <strong>MUST</strong> define an object factory class to instantiate
|
| 923 | this object as well as the needed resource parameters as attributes of the
|
| 924 | <code>Transaction</code>
|
| 925 | element, and the properties used to configure that object factory.</p>
|
| 926 |
|
| 927 | <p>The valid attributes for the <code><Transaction></code> element
|
| 928 | are as follows:</p>
|
| 929 |
|
| 930 | <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">
|
| 931 | <p>The class name for the JNDI object factory.</p>
|
| 932 | </td></tr></table>
|
| 933 |
|
| 934 | </blockquote></td></tr></table>
|
| 935 |
|
| 936 | </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>
|
| 937 | Copyright © 1999-2014, Apache Software Foundation
|
| 938 | </em></font></div></td></tr></table></body></html> |