The root element of this XML deployment descriptor is web-app; its top-level elements are shown in Table 7-42. There are no required elements, but you should always have at least a display-name element for identification. As of the Servlet specification version 2.4, the elements nested directly under the web-app element may be listed in any order. In cases where more than one of the same element is used and it is unclear which element takes precedence, the servlet container will use them in the order they are listed in the web.xml file.

These three elements provide alternate representations of a given web application. For example, the Manager application uses only the display-name, whereas the Admin application uses both display-name and description. Neither currently uses the icon element, but some commercial tools do.

Both display-name and description are self-explanatory in nature; icon must be a pathname to a file containing a graphical icon in GIF or JPEG format.

Additionally, this path must be relative to the web application root. Here is an example:

<web-app>
    <icon>
        <small-icon>/images/tomcat_tdg16x16.jpg</small-icon>
        <large-icon>/images/tomcat_tdg32x32.jpg</large-icon>
    </icon>
    <display-name>Ian Darwin's Tomcat Book Site</display-name>
    <description>This is the site containing all the examples
    from the book Tomcat: The Definitive Guide.
    </description>
    ...

The distributable element, if specified in a web application's web.xml file, indicates that the web application has been programmed in a way that will allow it to be deployed into a distributed servlet container, that is, one that distributes servlets and sessions across multiple instances of the servlet container. Tomcat is a distributed servlet container when the <Cluster> element is properly configured in the server.xml file. This element has no attributes and appears like this:

<distributable/>

There are no subelements that can be specified; simply the presence or absence of this element determines whether your web application is distributable.

For more details about running clustered (distributed) Tomcat instances, see Chapter 10.

It is often necessary to pass parameters into a servlet or JSP. Parameters may include such information as database connection parameters, filenames, or the site name. Usually the documentation for servlets you are using will tell you what parameters must be specified.

Notice that there are two kinds of initialization parameters: those that apply to the entire Context and those that apply only to a particular servlet or JSP. The Context initialization parameters are set using the context-param element in web.xml:

<web-app>
    <display-name>My Great Web App</display-name>

    <context-param>
    <param-name>some-paramater-name</param-name>
    <param-value>come-parameter-value</param-value>
    </context-param>

    <!-- Other elements -->
</web-app>

For example:

<web-app>
  <display-name>E-Mailing web application</display-name>

  <!-- EMail constants -->
    <!-- outgoing mail server -->
    <context-param>
      <param-name>mail.server.smtp</param-name>
      <param-value>server.acmewidgets.com</param-value>
    </context-param>
    <!-- Incoming mail server -->
    <context-param>
      <param-name>mail.server.pop</param-name>
      <param-value>pop-server.acmewidgets.com</param-value>
    </context-param>

</web-app>

It is less common to have initialization parameters that apply only to one servlet. Any parameters that do apply only to one servlet or JSP are set in that servlet's servlet element in web.xml as seen here:

<servlet>
    <servlet-name>servlet-name</servlet-name>
    <servlet-class>com.myapp.servlets.MyServlet</servlet-class>
    <init-param>
    <param-name>specific-servlet-parameter-name</param-name>
    <param-value>specific-servlet-parameter-value</param-value>
    </init-param>
</servlet>

For example:

 <servlet>
        <servlet-name>InitParams</servlet-name>
        <servlet-class>InitParams</servlet-class>
        <init-param>
            <param-name>address-preamble</param-name>
            <param-value>Four-score and seven years ago...</param-value>
        </init-param>
    </servlet>

To summarize, context-wide parameters are context-params and go near the top of the web.xml files; per-servlet parameters are init-params and go inside the servlet element, after the servlet name and class have been specified.

Filters are a new mechanism, recently added to the servlet API, which allows you to pipeline several programs together. Filters allow specific URL patterns to be processed by pieces of code before being handed off to the target servlet and also after the servlet runs. The filter element has several subelements, as shown in Table 7-43.

Before a filter can be used, it must also be mapped to a URL pattern or patterns, as well as a servlet. This mapping is accomplished through the filter-mapping element (which takes a filter-name) and either a url-pattern or a servlet-name to map it to. If url-pattern is used, all incoming URLs that match the pattern are applied to the filter. If servlet-name is used, the output of the filter is fed to the specified servlet. The URL pattern takes the same rules as the much more common servlet-mapping, as shown here:

<filter>
        <filter-name>Example Filter</filter-name>
        <filter-class>examples.ExampleFilter</filter-class>
        <init-param>
                <param-name>firstLine</param-name>
                <param-value>Once upon a midnight dreary, ...</param-value>
        </init-param>
</filter>

<filter-mapping>
        <filter-name>Example Filter</filter-name>
        <servlet-name>com.fredonia.smith</servlet-name>
</filter-mapping>

<filter-mapping>
        <filter-name>Example Filter</filter-name>
        <url-pattern>/servlet/*</url-pattern>
</filter-mapping>

Normally the web developers will inform you of any filters that are required for a web application, as well as the required parameters for this file.

As of the servlet 2.5 specification, you may use multiple url-patterns in a single filter-mapping element, mapping more than one pattern to the filter. You must declare your webapp a servlet 2.5 webapp (at the top of the webapp's WEB-INF/web.xml file) in order to take advantage of this feature.

Java developers implementing a web application may require use of listener classes, programs that get notified as certain events (such as creation or deletion) happen to the overall web application or to a particular HTTP session within it. If listeners are required, the developers will provide you with the list of class names required for deployment. For each class, put a listener element in the WEB-INF/web.xml file:

<listener>
  <listener-class>com.darwinsys.MainContextListener</listener-class>
</listener>

The servlet element lets you assign a name to a servlet or JSP that can be used in servlet-mapping and other elements that refer to a servlet.

To name a servlet, you have to give it a local name and list its full Java class name:

    <servlet>
        <servlet-name>InitParams</servlet-name>
        <servlet-class>com.darwinsys.InitParams</servlet-class>
    </servlet>

In this example, a servlet whose Java class name is com.darwinsys.InitParams is given the name InitParams. Then, other elements in the web.xml file may refer to the servlet simply using InitParams. You saw an example of this in the section on initialization parameters, earlier in this chapter.

The servlet element may also contain several subelements. The full list of subelements is shown in Table 7-44.

By default, a request for a servlet must contain the servlet's fully qualified class name; however, it is often desirable to use a URI alias for a servlet, which is both more convenient and hides the actual Java class name. This mapping can be accomplished using a servlet-mapping element in the servlet application's WEB-INF/web.xml file. You can easily map them to any URI pattern or name you wish, using a servlet-mapping. For example, suppose you wish to map the InitParams servlet to the URI /ParamsServlet. Assuming you already have a servlet tag for the InitParams servlet, you need only add the following servlet-mapping entry:

 <servlet-mapping>
        <servlet-name>InitParams</servlet-name>
        <url-pattern>/ParamsServlet</url-pattern>
 </servlet-mapping>

The servlet is then accessible under the new name (sometimes called an alias or servlet alias), relative to the web application's Context path.

The url-pattern in the preceding example shows a specific URI being mapped to the servlet. However, the URI can also include a pattern with wildcards. For example, the url-pattern element for the JspServlet, the part of Tomcat that compiles and runs all JSPs, is as follows:

    <servlet-mapping>
        <servlet-name>jsp</servlet-name>
        <url-pattern>*.jsp
</url-pattern>
    </servlet-mapping>

These lines indicate that any filename ending in the string .jsp will be processed by the JspServlet, that is, treated as a JSP.

As of the servlet 2.5 specification, you may use multiple url-patterns in a single servlet-mapping element, mapping more than one pattern to the servlet. You must declare your webapp a Servlet 2.5 webapp (at the top of the webapp's WEB-INF/web.xml file) in order to take advantage of this feature.

Alternately, you can map URLs to a given JSP by defining a servlet element with a jsp-file element and referencing the JSP with a servlet-mapping element. Suppose you want to catch any requests to a given Context whose URI had been changed, and map those requests to a JSP that prints out the updated URI. This is different from a conventional redirection page in that it dynamically calculates the precise link for the new Context. Here is the relevant mapping:

<web-app>
  <servlet>
    <servlet-name>Redirector</servlet-name>
    <jsp-file>/redirector.jsp</jsp-file>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <!-- Map everything to the Redirector servlet -->
  <servlet-mapping>
    <servlet-name>Redirector</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

If you specify the jsp-file inside the servlet definition and a load-on-startup value, Tomcat will precompile the JSP at startup time so that even the first request to this JSP runs quickly. If you leave out the load-on-startup element, the JSP is still mapped as a servlet but compiled on the first request. In either case, any requests to this Context are handled by the redirector.jsp file.

Idle shopping carts can be real memory hogs on e-commerce sites. These carts, which contain items that have been selected but will never actually be bought, are a real problem for even medium-sized sites. In fact, statistics place the percentage of online shopping carts that actually make it through the checkout stage at only 5 to 10 percent, which can make for a large amount of wasted RAM. This is a perfect case for using a servlet container's session timeout feature.

Tomcat keeps track of the time when the given user visits any page in the context that created the session. If the user is no longer visiting the page, the session should be discarded and the memory reclaimed. Tomcat lets you control how long a session can be idle before being discarded. Set this value too low, and you have unhappy users; set it too high, and you can waste a lot of memory. You set this timeout value in the session-timeout element in the web.xml file. The Tomcat-wide web.xml file includes the following setting, indicating that sessions timeout after 30 minutes of inactivity:

 <session-config>
        <session-timeout>30</session-timeout>
 </session-config>

If you change the time in conf/web.xml, sessions in all contexts will have the new default value. Alternately, you can provide this setting in any web application's WEB-INF/web.xml file and affect only that one Context.

MIME is the Multi-purpose Internet Mail Exchange standard, originally developed to allow for the exchange of attachments among different mail programs. MIME types have been used since the very early days of the Web. A web server sends a Content-Type header to the browser to identify the type of file it is sending so that the browser will know how to format and/or display the file. Static files being served by Tomcat are identified by their filename extension, which is looked up in a table in the web server.

The list of mappings from filename extensions to MIME types is specified in the web.xml file. If you have any nonstandard filename extensions that you wish to map to a given MIME type, you can add a mime-mapping entry either to Tomcat's or your web application's web.xml file.

For example, to map filenames matching *.foo to the MIME-type application/x-ian-test-file, you could add the following mime-mapping element:

    <mime-mapping>
        <extension>foo</extension>
        <mime-type>application/x-ian-test-file</mime-type>
    </mime-mapping>

Of course, if the browser doesn't know how to interpret this MIME type, it will ask the user to save the file to disk for later inspection. You can add as many MIME-type mappings as you wish, either on a global basis or in a given web application.

When you have a directory of files that are not web pages but, for example, binary programs for people to download, it may be convenient to omit an index page; users visiting this directory will then get an automatically written index page that is just the list of filenames, similar to what you see when you visit an FTP server in a browser. However, in other directories, this kind of listing can reveal information that might compromise your system or application's security.

The simplest way to disable file listings in a given directory is to provide an index file. The index file can have any name, but is index.html, by long-established web convention. Tomcat will normally look for the JSP version of that, index.jsp, followed by the conventional index.html and the historical (i.e., Windows 3.1) index.htm. You can remove these defaults, or add additional default index page names. This is configured in Tomcat's global web.xml file as shown here; you can override this in an application's web.xml, in which case, the complete list is replaced by what you specify:

  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.htm</welcome-file>
    <welcome-file>index.jsp</welcome-file>
  </welcome-file-list>

You can also disable all directory listings for Tomcat (but not for a single Context) by setting the listings parameter on the DefaultServlet to false. Look for this entry:

<servlet>
    <servlet-name>default</servlet-name>
    <servlet-class>
      org.apache.catalina.servlets.DefaultServlet
    </servlet- class>
    <init-param>
      <param-name>debug</param-name>
      <param-value>0</param-value>
    </init-param>
    <init-param>
      <param-name>listings</param-name>
      <param-value>true</param-value>
    </init-param>
    ...

Change the param-value for listings to false, and restart Tomcat. Lo and behold—no more directory listings.

The error-page directive lets you specify a custom error-handling page, either by HTTP result code or by Java exception type. The HTTP errors (specified by HTTP result codes) can be formatted using an HTML page, or a JSP, or any other component you choose to use. Java errors (specified by exception type) are best handled by a JavaServer Page; a single JSP can handle any number of different exception types. The error page must be an absolute path within the web Context. This example shows one of each:

    <error-page>
        <error-code>404</error-code>
        <location>/errors/404.html</location>
    </error-page>
    <error-page>
        <exception-type>java.lang.NullPointerException</exception-type>
        <location>/errors/prog-error.jsp</location>
    </error-page>

The web.xml file allows some items to be configured globally for all JSP pages in the webapp: tag libraries and JSP properties. Under the jsp-config element, you may define zero or more taglib elements and zero or more jsp-property-group elements.

In versions of the JSP specification below version 2.0, the taglib element was nested just under web-app—that is, at the same level that jsp-config is now nested. Tomcat still supports older web.xml files, so the taglib element can be nested either under jsp-config or at the same level as jsp-config.

The taglib element specifies the location of a Tag Library Description (TLD) file, which in turn specifies the names and Java class names for JSP custom tags. This tag is often omitted; if the JSP contains a <%@page taglib="..."> directive, Tomcat will happily find the TLD without a taglib element in web.xml.

The taglib element has two subelements, taglib-uri and taglib-location. The names are a bit confusing; taglib-uri actually refers to a (usually) short URL that will be used to refer to the TLD, whereas taglib-location refers to the actual location of the TLD file, relative to the web root. The TLD files can be stored anywhere in your web application directory, but it is customary to put them under WEB-INF or WEB-INF/tld to avoid cluttering the web site and to prevent the TLD from being directly viewed by a web browser. This example is from the JSTL tag library demonstration programs:

<taglib>
    <taglib-uri>http://java.sun.com/jstl/core</taglib-uri>
    <taglib-location>/WEB-INF/c.tld</taglib-location>
</taglib>

The taglib-uri shown in this example does not refer to an actual directory; it is more like an arbitrary namespace. If you try to access the URL in a web browser, you will get a 404 error. The intention is to associate the TLD with Sun's web site. The critical information is the taglib-location, which must refer to a valid TLD file, provided with the tag library. A more common use of taglib is to provide a shorter, more convenient URI:

 <taglib>
        <taglib-uri>/MyTags</taglib-uri>
        <taglib-location>/WEB-INF/c.tld</taglib-location>
</taglib>

This would then be used in a JSP to refer to the tag library:

<%@page taglib="/MyTags" prefix="c" %>

The jsp-property-group element is also nestable under jsp-config. The purpose of jsp-property-group is to allow configuring the JSP behavior of a set of the resources of the webapp to be different than the global settings.

Table 7-45 shows the subelements of jsp-property-group. None of these elements have subelements. Only url-pattern is required, and if there is a url-pattern element, there must also be one of the other elements.

The resource-env-ref element allows servlets and JSPs to use JNDI to find an administered object, such as a Java Messaging Queue. Administered objects are those set up administratively (of course), typically using the administration console in a MQ-type software product, or by directly editing configuration files. You may give a description for the resource, and must give the environment reference name and the class name of the administered object. Assuming you used JMS in your web application, you might use the following:

<resource-env-ref>
    <description>The JMS queue for the stock quote service</description>
    <resource-env-ref-name>jms/StockQueue</resource-env-ref-name>
    <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>

See Chapter 2 for more information about how to configure JNDI resource references.

The resource-ref element sets up a JNDI factory for objects to be used by servlets and JSPs. You must specify the name, type, and authorization type. The res-ref-name is a name to be looked up in the JNDI java:comp/env environment naming context (ENC) specified by the Java Enterprise Edition. The res-type element specifies the class of object to be returned. The res-auth (authorization type) element's value can be set to either container or application:

    <resource-ref>
        <description> Define a a factory for javax.mail.Session objects.
        </description>
        <res-ref-name> mail/Session</res-ref-name>
        <res-type>javax.mail.Session</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>

Suppose you want to set up a restricted area of your web site. A security-constraint element specifies that authorization is required to access the given resource, typically a directory. You normally use this element to protect a particular subdirectory of a web application. You may specify a display-name, and must give one or more web-resource-collection elements, followed by an auth-constraint and/or a user-data-constraint element:

 <!-- Define the Members-only area  -->
  <security-constraint>
  <display-name>My Club Members-Only Area</display-name>
    <web-resource-collection>
      <web-resource-name>Members-only Area</web-resource-name>
      <url-pattern>/members/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
       <role-name>member</role-name>
    </auth-constraint>
  </security-constraint>

This will usually be followed by a login-config element (detailed in the next section) to tell Tomcat what sort of login/password scheme to use in controlling access to the protected area.

There are several schemes for Tomcat to ask the user for the necessary security credentials to access a protected resource. There is BASIC authorization, in which the browser puts up a dialog box asking for the password. There is also FORM authentication, where the web application provides a web form for the login, but the container manages the security aspects of controlling access once the user fills in the form. There are also DIGEST and CLIENT-CERT. All of these are login-configs that Tomcat supports.

A security-constraint element will usually be followed by a login-config, indicating which of these security methods to use for providing access to the protected area. This configuration must give at least the auth-method and the realm-name; the latter specifies the name that a client's browser will display in the login dialog box when you try to access the protected area:

<login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>My Club Members-only Area</realm-name>
</login-config>

A security-role element, if present, describes a security role used in your web application. It requires a description and a role name; the role-name usually matches a role used in an auth-constraint element. The security-role element is optional and is largely for documentation purposes. Without it, Tomcat would figure out any needed roles from the auth-constraint elements, and an administrative application simply would not have any textual description for those roles. However, these tools are a lot more useful, and your files a lot more descriptive, if you do explicitly define these roles:

    <security-role>
        <description>
          This role includes all paid-up club members.
        </description>
        <role-name>member</role-name>
    </security-role>

An env-entry element is one of several ways of passing parameters into the Java code in a web application; these parameters will be looked up by application code using JNDI. Each consists of an optional description, an env-entry-name, an optional env-entry-value, and the env-entry-type. The env-entry-name is the name used in the application, the env-entry-value is obviously the value, and the env-entry-type must be a fully qualified Java class name, either String or one of the wrapper classes (java.lang.Integer, java.lang.Double, etc.):

<env-entry>
     <description>Membership rates</description>
     <env-entry-name>membership-rate</env-entry-name>
     <env-entry-value>75.00</env-entry-value>
     <env-entry-type>java.lang.Float</env-entry-type>
</env-entry>

Enterprise JavaBeans are another Java EE mechanism, aimed at providing a framework for building and using Java components to provide large-scale business processing and database access. The ejb-ref and ejb-local-ref elements are used when servlets and JSPs need to access an Enterprise JavaBean.

The local version of this element is used when running the servlet and the EJB in the same Java Virtual Machine. These examples are taken from the examples web application distributed with Tomcat:

    <!-- EJB Reference -->
    <ejb-ref>
      <description>Example EJB Reference</description>
      <ejb-ref-name>ejb/Account</ejb-ref-name>
      <ejb-ref-type>Entity</ejb-ref-type>
      <home>com.mycompany.mypackage.AccountHome</home>
      <remote>com.mycompany.mypackage.Account</remote>
    </ejb-ref>

    <!-- Local EJB Reference -->
    <ejb-local-ref>
      <description>Example Local EJB Reference</description>
      <ejb-ref-name>ejb/ProcessOrder</ejb-ref-name>
      <ejb-ref-type>Session</ejb-ref-type>
      <local-home>com.mycompany.mypackage.ProcessOrderHome</local-home>
      <local>com.mycompany.mypackage.ProcessOrder</local>
    </ejb-local-ref>

The servlet or the JSP will look up the value of the ejb-ref-name in the JNDI context, relative to java:comp/env, and the ejb-ref-name is suggested to begin with ejb/. This is how the servlet or JSP gets its initial access to the EJB's home or local interface to create or find a bean instance. The home and remote (or local-home and local) are Java interfaces; implementations of each will be provided by the EJB server or its deployment tool and will need to be added to Tomcat's classpath if necessary (typically in the WEB-INF/lib directory).

Servlet containers that are not part of a Java EE implementation are not required to implement the service-ref element, but Tomcat version 6.0.10 and higher does implement it. It configures a reference to a web service.

Table 7-46 shows the subelements of service-ref. None of these elements have subelements. Only service-ref-name and service-interface are required.

This element declares a reference to a message destination, such as a JMS queue. Table 7-47 shows the subelements of message-destination-ref. None of these elements have subelements.

This element declares a message destination, such as a Java Message Service (JMS) queue. Table 7-48 shows the subelements of message-destination. None of these elements have subelements.

The locale-encoding-mapping-list element specifies a mapping between locales and character encodings. This list is local to the webapp in which it is listed, and does not affect other webapps running in the same servlet container.

Here is an example:

<locale-encoding-mapping-list>
    <locale-encoding-mapping>
        <locale>ja</locale>
        <encoding>Shift_JIS</encoding>
    </locale-encoding-mapping>
</locale-encoding-mapping-list>