Pro Apache Tomcat 5/5.5 (Experts Voice in Java)

You shouldn’t have many dealings with a Web application’s web.xml file, as it’s the realm of the application’s developer. However, certain aspects on the server are definitely your concern, so the following sections will go into the relevant sections in web.xml. They will be illustrated where possible by examples from Tomcat’s default web.xml file.

<distributable>

The <distributable> element, if present, declares that this Web application can be deployed in a distributed servlet container or servlet container executing across multiple JVMs either running on the same host or different hosts. This Boolean value is false by default.

<context-param>

The <context-param> element declares a context initialization parameter, much as the previous <Parameter> element does. It contains the following:

• A <param-name> element containing the parameter’s name

• A <param-value> element containing the parameter’s value

• An optional <description> element

<filter>

The <filter> element declares a filter. A filter is a Java class that preprocesses the request data received from clients. This preprocessing may include decryption, formatting, or other processes. This element contains the following:

• An optional <icon> element

• A <filter-name> element containing the filter’s name

• An optional <display-name> element

• An optional <description> element

• A <filter-class> element containing the filter’s class name

• Zero or more <init-param> elements containing initialization parameters for the filter

Each <init-param> element contains the following:

• A <param-name> element containing the parameter name

• A <param-value> element containing the parameter value

• An optional <description> element

Listing 5-1.

Listing 5-1: An Entry for a Filter

<filter> <filter-name>requestFilter</filter-name> <filter-class>com.apress.admin.filters.RequestFilter</filter-class> <init-param> <param-name>allow</param-name> <param-value></param-value> </init-param> <init-param> <param-name>deny</param-name> <param-value>127.0.0.1</param-value> </init-param> <init-param> <param-name>blockPage</param-name> <param-value>/blocked.html</param-value> </init-param> </filter>

<filter-mapping>

The <filter-mapping> element maps a filter to a servlet or a set of URLs. It contains the following:

• A <filter-name> element containing the name of a filter declared by a <filter> element.

• Either a <url-pattern> element containing a URL pattern to match or a <servlet-name> element containing the name of a servlet declared by a <servlet> element.

• Zero to four <dispatcher> elements; it can have one of the following values: FORWARD, REQUEST, INCLUDE, and ERROR. FORWARD applies the filter to RequestDispatcher.forward() calls, REQUEST applies the filter to ordinary client calls to the path or servlet, INCLUDE applies the filter to RequestDispatcher.include() calls, and ERROR applies the filter to the error page mechanism.

If the <dispatcher> element is omitted, the default value is REQUEST.

The previous filter would have the filter mapping as shown in Listing 5-2.

Listing 5-2: An Example Filter Mapping

<filter-mapping> <filter-name>requestFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>

This maps all requests in the Web application to the filter.

<servlet>

Because you’ve already seen the <servlet> element in action, I won’t discuss it in detail here. It contains the following:

• An optional <icon> element

• A <servlet-name> element containing the servlet’s name

• An optional <display-name> element

• An optional <description> element

• Either a <servlet-class> element containing the listener’s class name or a <jsp-file> element containing the location within the Web application of a JSP file

• <init-param> elements

• An optional <load-on-startup> element indicating that the servlet should be loaded when the Web application starts up and containing an optional positive integer value that indicates the order in which servlets should be started. If a <jsp-file> was specified, then the JSP should be precompiled and loaded.

• <security-role-ref> elements

• An optional <run-as> element that specifies the identity under which the servlet should run

Each <init-param> element contains the following:

• A <param-name> element containing the parameter name

• A <param-value> element containing the parameter value

• An optional <description> element

A <security-role-ref> element maps a role name called from within the servlet and maps the name of a security role defined for the Web application. It contains the following:

• An optional <description> element

• A <role-name> element containing the role name used within the servlet

• An optional <role-link> element containing the name of a role defined in a <security-role> element

Tomcat’s default web.xml file contains many <servlet> entries. The first is for the default servlet, as shown in Listing 5-3.

Listing 5-3: The Default Servlet <servlet> Setting

<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> <load-on-startup>1</load-on-startup> </servlet>

<servlet-mapping>

The <servlet-mapping> element maps a servlet to a URL pattern. It contains the following:

• A <servlet-name> element containing the name of a servlet declared by a <servlet> element

• A <url-pattern> element containing a URL pattern to match

The previous default servlet has a corresponding <servlet-mapping> entry, as shown in Listing 5-4.

Listing 5-4: The Default Servlet <servlet-mapping> Setting

<servlet-mapping> <servlet-name>default</servlet-name> <url-pattern>/</url-pattern> </servlet-mapping>

<session-config>

An administrator should be aware of the session settings of a Web application because it can have performance and security implications. A huge number of long-lasting sessions may cause problems for performance, but a session that never expires means that a user is always recognized. The latter means that any user who has access to the original user’s machine can access the Web application as that user.

The <session-config> element contains the following:

• An optional <session-timeout> element containing the default session timeout for this Web application, which must be a whole number of minutes. The default behavior of the container without this attribute is never to time out.

Listing 5-5 shows the default session setting from Tomcat’s default web.xml file.

Listing 5-5: The Default Session Setting for Tomcat

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

<mime-mapping>

Browsers use MIME types to recognize the file type returned by the server so that the browser can handle the response correctly. That is, the browser chooses whether to display it (HTML, plain text, images), send it to a plug-in (such as Flash), or prompt the user to save it locally.

As you saw in Chapter 4, CATALINA_HOME/conf/web.xml comes with many MIME mappings set. However, you can configure additional MIME mappings in each Web application with the <mime-mapping> element.

The <mime-mapping> element contains the following:

• An <extension> element containing a filename extension

• A <mime-type> element containing a defined MIME type

Tomcat has many MIME mappings set, one of which is shown in Listing 5-6. This tells Tomcat to treat *.bmp files as the image/bmp type.

Listing 5-6: A Default Tomcat MIME Mapping

<mime-mapping> <extension>bmp</extension> <mime-type>image/bmp</mime-type> </mime-mapping>

<welcome-file-list>

The <welcome-file-list> element defines an ordered list of welcome files to display if no filename is specified. It contains the following:

• One or more <welcome-file> elements containing a filename to use as a welcome file

Tomcat has a default setting for welcome files, as shown in Listing 5-7.

Listing 5-7: Tomcat’s Default Welcome Files

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

These files are checked in the order they appear.

<error-page>

Web application developers can configure error pages to provide a user-friendly mechanism for informing the users about any problems and allowing them to continue using the application. The errors are mapped to the HTTP specification error mappings: a code for a resource that can’t be found, a malfunctioning server, authentication issues, resource issues, and so on.

In addition, since there are no one-to-one correspondences between HTTP errors and Java exceptions, the exception class type may be specified; this allows error pages that are generic and follows good programming practice. Someone without an understanding of the application’s internals can configure them.

The <error-page> element contains the following:

• Either an <error-code> element containing an HTTP error code or an <exception-type> element containing the class name of a Java exception type

• A <location> element containing the location of the error page resource within the Web application

Listing 5-8 shows an example of an error page setting. In this case any 404 errors generated by Tomcat will return the myError.jsp page to the client.

Listing 5-8: An Error Page Configuration

<error-page> <error-code>404</error-code> <location>/myError.jsp</location> </error-page>

<resource-env-ref>

The <resource-env-ref> element declares that the Web application references an administered object such as a user database. This is defined in the <GlobalNamingResources> element of the server component. It contains the following:

• An optional <description> element

• A <resource-env-ref-name> element containing the name of the resource environment

• A <resource-env-ref-type> element containing the type of the resource environment reference

The manager application configures a reference to a global resource, as shown in Listing 5-9.

Listing 5-9: The Manager Web Application’s <resource-env-ref> Setting

<resource-env-ref> <description> Link to the UserDatabase instance from which we request lists of defined role names. Typically, this will be connected to the global user database with a ResourceLink element in server.xml or the context configuration file for the manager Web application. </description> <resource-env-ref-name>users</resource-env-ref-name> <resource-env-ref-type> org.apache.catalina.UserDatabase </resource-env-ref-type> </resource-env-ref>

<resource-ref>

The <resource-ref> element declares that the Web application references an external resource such as a data source reference. This is typically configured in a context entry using the <Resource> element. It contains the following:

• An optional <description> element.

• A <res-ref-name> element containing the name of the resource factory reference.

• A <res-type> element specifying the type of the data source.

• A <res-auth> element indicating whether the application code signs onto the resource programmatically or whether the container should sign on based on information supplied by the application deployer. Contents must be either Application or Container.

• An optional <res-sharing-scope> element specifying whether connections can be shared. Contents must be either Shareable (the default) or Unshareable.

Listing 5-10 shows an example.

Listing 5-10: A Reference to a JDBC Data Source

<resource-ref> <description> Resource reference to a factory for java.sql.Connection instances that may be used for talking to a particular database that is configured in the tomcatBook.xml file. </description> <res-ref-name> jdbc/CatalogDB </res-ref-name> <res-type> javax.sql.DataSource </res-type> <res-auth> SERVLET </res-auth> </resource-ref>

<security-constraint>

Web resources may be associated with some security constraints for user authentication and access control. The constraints limit access to the resource according to user roles, such as manager, administrator, user, and guest, and by transport guarantee, which can include SSL secure data transmission, guaranteeing delivery and noninterference.

The <security-constraint> element contains the following:

• An optional <display-name> element

• One or more <web-resource-collection> elements

• An optional <auth-constraint> element

• An optional <user-data-constraint> element

A <web-resource-collection> element identifies a set of resources within the application; it can be qualified by specifying particular HTTP method(s) such as GET or POST. (By default, the security constraint applies to all HTTP methods.) It contains the following:

• A <web-resource-name> element containing the name of the Web resource collection

• An optional <description> element

• One or more <url-pattern> elements, each containing a URL pattern to match

• Zero or more <http-method> elements, each containing the name of an HTTP method

An <auth-constraint> element indicates that certain user roles should be permitted to access these Web resources. It contains the following:

• An optional <description> element

• Zero or more <role-name> elements, each containing a role referenced in a <security-role-ref> element or the special name * that indicates all roles in this application

A <user-data-constraint> element indicates how data transmitted between the client and the application should be protected. It contains the following:

• An optional <description> element

• A <transport-guarantee> (can have one of the three values in Table 5-6)

The manager Web application contains a security constraint on all its resources, as shown in Listing 5-11.

Listing 5-11: The Manager Web Application’s Security Constraint

<security-constraint> <web-resource-collection> <web-resource-name>HTMLManager and Manager command</web-resource-name> <url-pattern>/jmxproxy/*</url-pattern> <url-pattern>/html/*</url-pattern> <url-pattern>/list</url-pattern> <url-pattern>/sessions</url-pattern> <url-pattern>/start</url-pattern> <url-pattern>/stop</url-pattern> <url-pattern>/install</url-pattern> <url-pattern>/remove</url-pattern> <url-pattern>/deploy</url-pattern> <url-pattern>/undeploy</url-pattern> <url-pattern>/reload</url-pattern> <url-pattern>/save</url-pattern> <url-pattern>/serverinfo</url-pattern> <url-pattern>/status/*</url-pattern> <url-pattern>/roles</url-pattern> <url-pattern>/resources</url-pattern> </web-resource-collection> <auth-constraint> <!-- NOTE: This role isn't present in the default users' file --> <role-name>manager</role-name> </auth-constraint> </security-constraint>

<login-config>

The <login-config> element configures the authentication mechanism for this application. It contains the following:

• An optional <auth-method> element specifying the authentication mechanism; it must contain the text BASIC, DIGEST, FORM, or CLIENT-CERT. They’re plain text, digested text, HTML form, and certificate based, respectively.

• An optional <realm-name> element specifying the realm name for HTTP basic authorization.

• An optional <form-login-config> element to configure form-based authentication. It contains a <form-login-page> element specifying the login page and a <form-error-page> element specifying the error page used if login is unsuccessful.

The manager application defines a <login-config> to go along with the security constraint described previously (see Listing 5-12).

Listing 5-12: The Manager Web Application’s Login Configuration

<login-config> <auth-method>BASIC</auth-method> <realm-name>Tomcat Manager Application</realm-name> </login-config>

<security-role>

The <security-role> element declares a security role used in the Web application’s security-constraints. It contains the following:

• An optional <description> element

• A <role-name> element containing the name of the role

The manager application defines a security role to go along with the security constraint described previously (see Listing 5-13).

Listing 5-13: The Manager Web Application’s Security Role

<security-role> <description> The role that is required to log in to the Manager Application </description> <role-name>manager</role-name> </security-role>