Configuring Contexts

In the past, you may have configured contexts in server.xml, but this is no longer recommended. The main reason is that Tomcat reads server.xml only when it starts and doesn’t reload it at any point of the server’s life. This means that any changes, including new context definitions, won’t be registered.

The new procedure requires you to use the same context definition as before but this time in its own XML file in the CATALINA_HOME/conf/[Engine_name]/[Host_name] directory. For the default setup, this is CATALINA_HOME/conf/Catalina/localhost.

The XML file may be called whatever you want and has the <Context> element as its root element. The name of this file is important in Tomcat 5.5 because it’s used to name the Web application that the context XML file describes.

Configuring Default Contexts

Before you see how to configure a context, I’ll discuss how Tomcat deploys contexts and how this affects the default settings. Tomcat uses a set sequence when it automatically deploys Web applications at startup (configured with the host’s deployOnStartup attribute). To start with, it reads any context XML files in the CATALINA_HOME/conf/[Engine_name]/[Host_name] directory for each host. The docBase attribute of the <Context> element (see Table 5-1 in the next section) points to a WAR or directory where the application files are located. Tomcat then deploys this Web application using the settings in the context XML file.

Table 5-1: The Attributes of the Standard <Context> Element

Attribute	Description	Required?
allowLinking (*)	If true, symlinks pointing to resources outside the Web application base path are allowed for this Web application. This flag shouldn’t be set to true on Windows, as it will disable case-sensitivity checks, allowing JSP source code disclosure, among other security problems. The default is false.	No
backgroundProcessorDelay	The delay in seconds between the invocation of the backgroundProcess() method on this context and its child containers, including all wrappers. Child containers will be invoked if their delay value is negative (which would mean they’re using their own processing thread). Setting this to a positive value will cause a thread to be spawned. 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. The default is -1, which means the context will rely on the background processing thread of its parent host.	No
cacheMaxSize (*)	Maximum size of the static resource cache in kilobytes. The default is 10240.	No
cacheTTL (*)	Time in milliseconds between cache entries revalidation. The default is 5000.	No
cachingAllowed (*)	If true, the cache for static resources will be used. The default is true.	No
caseSensitive (*)	If true, all case-sensitivity checks will be disabled. This flag shouldn’t be set to true on Windows, as it will disable case-sensitivity checks, allowing JSP source code disclosure, among other security problems. The default value is true.	No
className	Class name of the implementation to use. The default is org.apache.catalina.core.StandardContext.	No
cookies (*)	Set to true if you want cookies to be used to identify sessions (if supported by the client). Set to false if you want to disable the use of cookies for session identification and rely only on URL rewriting. The default is true.	No
crossContext (*)	Set to true if you want calls within this application to ServletContext.getContext() to successfully return a request dispatcher for other Web applications running on this virtual host. Set to false in security-conscious environments. The default is false.	No
debug	Tomcat 5.0.x only. The level of debugging for this context. The levels are 1 (errors), 2 (warnings), 3 (information), and 4 (debug). These correspond to the levels of debugging in the logger component. This is an attribute of the standard implementation and may change if you’re using another implementation. The default is zero, meaning no debugging (though the associated logger will still log fatal messages).	No
docBase	The document base (or context root) directory for this Web application or the pathname to its WAR file. You can specify an absolute pathname for this directory or WAR file, or you can specify a pathname that’s relative to the appBase directory of the owning host.	Yes
managerChecksFrequency (*)	Tomcat 5.0.x only. Frequency of the session expiration and related manager operations. Manager operations will be carried out once for the specified amount of backgroundProcess() calls (that is, the lower the amount, the more frequent the checks). The minimum value is 1. The default is 6.	No
override	In Tomcat 5.0.x, set to true to have explicit settings in this context override any corresponding settings in the <DefaultContext> element associated with the owning host. In Tomcat 5.5 this setting overrides the settings in all three default context files. The default is false.	No
privileged	Set to true to allow this context to use container servlets, like the manager servlet. The default is false.	No
path	The context path of this Web application, which is matched against the beginning of each request URI. All the context paths within a particular host must be unique. If you specify an empty string (""), you’re defining the default Web application for this host, which will process all requests not assigned to other contexts. In Tomcat 5.5, the path of a Web application is inferred from the name of the context XML file or the file specified in docBase. Therefore, you shouldn’t need to set a value for this attribute.	Yes (Tomcat 5.0.x) No (Tomcat 5.5)
processTlds	Specify whether the context should process TLDs on startup. false is intended for special cases where you know in advance that TLDs aren’t part of the Web application. The default is true.	No
reloadable (*)	Set to true if you want Tomcat to monitor classes in /WEB-INF/classes and /WEB-INF/lib for changes and automatically reload the Web application if a change is detected. This feature is useful during development, but it requires significant runtime overhead and isn’t recommended for use on deployed production applications. Use the manager application to reload applications if this is required. The default is false.	No
swallowOutput (*)	If true, the output to System.out and System.err will be redirected to the Web application logger. The default is false.	No
tldNamespaceAware	If true, XML validation of TLDs will be namespace aware. If you turn this flag on, you should also turn tldValidation on, though setting it to true will incur a performance penalty. The default is false.	No
tldValidation	If true, TLDs will be XML validated on context startup. Setting it to true will incur a performance penalty. The default is false.	No
useNaming (*)	Set to true to have Tomcat enable a JNDI InitialContext for this Web application. The default is true.	No
workDir	The pathname to a scratch directory to be provided by this context for temporary read-write use by servlets. This directory is visible to servlets through a servlet context attribute (of type java.io.File) named javax.servlet.context.tempdir as described in the Servlet specification. The default is a suitable directory underneath CATALINA_HOME/work.	No
wrapperClass (*)	The Java class name of the org.apache.catalina.Wrapper implementation class that will be used for servlets managed by this context. The default is org.apache.catalina.core.StandardWrapper.	No

The next step in the sequence is to expand any WAR files in the application base directory that don’t have a corresponding directory (assuming the host’s unpackWARs attribute is true). This means you have to remove any expanded Web applications if you add a new WAR file.

The final step in Web application deployment is the one that’s most relevant to this section. Any expanded directories and WARs in the application base directory that don’t have a corresponding context XML file are given a default implicit <Context> element. You configure this default element differently depending on the version of Tomcat you’re using.

Tomcat 5.0.x has a <DefaultContext> element in server.xml that you use to define default context settings. This element uses a subset of the <Context> element’s attributes. These are marked with an asterisk in Table 5-1.

Tomcat 5.5 uses an external default context XML file, which has the <Context> element as its root element. The default file for the entire server is CATALINA_HOME/conf/context.xml, and the default file for a host is CATALINA_HOME/conf/[Engine_name]/[Host_name]/context.xml.default. You may also place a context.xml file in a Web application’s META-INF directory, though this is read only if there’s no application context file as described previously. This file will apply only to that Web application.

The settings in context.xml override any in context.xml.default and META-INF/context.xml, even if you explicitly set the override attribute described in Table 5-1. However, override works for application context XML files. Figure 5-1 shows this process.

Figure 5-1: The context file hierarchy in Tomcat 5.5

These rules also apply to applications that are deployed after startup. That is, they apply to directories and WAR files that you drop into the Web application base directory, assuming autodeployment is enabled with the host’s autoDeploy attribute. If autodeployment is disabled, then you can use tools such as the manager application and Ant to deploy applications, and the same process occurs.

Web applications are also restarted and redeployed if their web.xml file is changed, their WAR is updated, or their context XML file is updated, though you can also configure the web.xml reload using the <WatchedResource> element as described in the “Configuring a Watched Resource” section.

The Context Element

Tomcat’s standard <Context> element has the attributes described in Table 5-1. Those marked with an asterisk are available to the Tomcat 5.0.x <DefaultContext> element.

Tomcat 5.5 introduces a number of new attributes to the context element (see Table 5-2).

Table 5-2: The New Attributes of Tomcat 5.5’s Standard <Context> Element

Attribute	Description	Required?
antiJARLocking	If true, Tomcat’s class loader will take extra measures to avoid JAR file locking when JARs are accessed through URLs. This will slow application startup times but can prove useful on platforms or configurations where file locking can occur. The default is false.	No
antiResourceLocking	If true, Tomcat will prevent file locking. This will significantly slow application startup time but allows full hot deploy and undeploy on platforms or configurations where file locking can occur. The default is false.	No
unpackWAR	If true, Tomcat will unpack this Web application, if it’s compressed, before running it. If the host’s unpackWARs attribute is false, this setting has no effect. The default is true.	No

A context is a container and can have the nested components described in Table 5-3.

Table 5-3: The Subelements of the <Context> Element

Subelement	Description	Number
Environment	A global variable. See Chapter 4 for details.	Zero or more
Listener	You can add a listener to monitor lifecycle events, such as this host starting or stopping, and to implement user Web applications. See Chapter 4 for details.	Zero or more
Loader	Configures the Web application class loader. It’s unlikely that you’d want to specify your own class loader. See the Tomcat documentation if this is a necessity.	Zero or one
Logger	Tomcat 5.0.x only. A logger to be used with this Web application. This element overrides any logger defined in the enclosing <Host> or <Engine> elements. See Chapter 4 for details.	Zero or one
Manager	A custom session manager to handle session persistence for this Web application. This is a technique used by programmers to overcome HTTP’s stateless nature. It’s unlikely you’d want to specify your own session manager. See the Tomcat documentation if this is a necessity.	Zero or one
Parameter	A value that will be available to the Web application as a named variable.	Zero or more
Realm	An authentication realm to be used within this Web application. This will override any previous realm definitions in the enclosing <Host> or <Engine> definitions. See Chapter 4 for details.	Zero or one
Resource	A JNDI resource. See Chapter 4 for details.	Zero or more
ResourceLink	A link to a global JNDI resource.	Zero or more
ResourceParams	Parameters that go along with the named JBDI resource. See Chapter 4 for details.	Zero or more
Resources	A resource manager for accessing static resources (for serving static Web pages, graphics, and so on) within the Web application. It’s unlikely you’d want to specify your own resource manager. See the Tomcat documentation if this is a necessity.	Zero or one
Valve	You can add a valve to monitor access, filter requests, and implement single sign-on. See Chapter 4 for details.	Zero or more

Configuring a Parameter

You can add servlet context initialization parameters in your context definition. These will be available to servlets throughout the application.

Table 5-4 describes the attributes of the <Parameter> element.

Table 5-4: The Attributes of the <Parameter> Element

Attribute	Description	Required?
description	Human-readable description of this context initialization parameter.	No
name	The name of the context initialization parameter to be created.	Yes
override	Sets whether a <context-param> element in the application’s web.xml file can override the value specified here. The default is true.	No
value	The value that will be available to the application.	Yes

Configuring a Resource Link

A resource link references a global JNDI variable and makes it available under the new name.

Table 5-5 describes the attributes of a <ResourceLink> element.

Table 5-5: The Attributes of the <ResourceLink> Element

Attribute	Description	Required?
global	The name of the global JNDI resource	Yes
name	The name of the variable to be created, relative to the java:comp/env context	Yes
type	The class name expected by the Web application when it performs a lookup for this resource link	Yes

Configuring a Watched Resource (Tomcat 5.5 Only)

Tomcat, if set to autodeploy, will monitor the specified static resource of the Web application for updates and will reload the Web application if it’s updated. The content of this element must be a string, and it has no attributes or subelements. You may have more than one watched resource per Web application as shown in the default server context.xml file.

 <WatchedResource>WEB-INF/web.xml</WatchedResource>  <WatchedResource>META-INF/context.xml</WatchedResource> 

This tells Tomcat to reload the Web application when the specified files are changed. Thus Tomcat reloads a Web application when its individual settings are changed.