WAR Configuration Options

There are a number of different elements that might appear in the web.xml file. Although most of them are discussed here, a number of them are discussed in earlier hours, where it is easier to understand their use in the context of the examples. Here, we'll address those options that generally apply to servlets and JSPs.

General Application Options

The general application options deal with the parts of the application that are above a servlet, such as the application's description, the initial startup file, and the various error pages to use.

display-name

The display-name option is a short description of the application. It is intended to be the kind of name you would expect to see in a GUI tool.

icon

This option allows you to associate a large and small icon with your application, servlet, JSP, or other resource. Some tools make use of the icons. Here is an example of how you do this:

<icon>
   <small-icon>/icons.small.jpg</small-icon>
   <large-icon>/icons/large.jpg</large-icon>
</icon>

description

The description option is the long description of the application. When this option is a direct child of <web-app>, it describes the application; otherwise, it describes the item of which it is a child. That is, other things can have a description, so when you see a <description> tag, don't assume that it's a description of the application. Here is an example:

<description>
This application demonstrates how you use a WAR file to deploy 
an application in different Web servers.
</description

distributable

The distributable option indicates that this application might be distributed across multiple containers (servlet engines). One of the things you must ensure when you create a distributable application is that all the items you place in a session must implement the java.io.Serializable interface, indicating that they can be serialized. The container might need to copy objects from one session object to another if a browser session accesses a different server, such as in the following example:

<distributable/>

context-param

The context-param option enables you to set initialization parameters that are accessible through the ServletContext class. Use the <param-name> and <param-value> tags to set the parts of the context parameter. You can also include an optional description tag. Here is an example:

<context-param>
    <param-name>initParam1</param-name>
    <param-value>Foo!</param-value>
    <description>A simple init parameter</description>
</context-param>

mime-mapping

You might find it odd that you can set mime mappings for files in a WAR file, because most of the time you set content types in a servlet or a JSP. If you forward to a non-servlet, non-JSP resource, however, the content type for the response is the mime type of the resource you are returning. The mime-mapping option enables you to control those content types. Here is an example:

<mime-mapping>
    <extension>wml</extension>
    <mime-type>text/vnd.wap.wml>
</mime-mapping>

welcome-file-list

When you access a Web site, you rarely enter a filename. For instance, you might enter http://www.slashdot.org without entering a filename such as index.html or default.html. The welcome-file-list option lets you specify the possible names for the default application file. In other words, if the application is named example and you go to http://localhost/example, the welcome file list indicates the possible files that you might run. If the list includes index.html, index.htm, and default.jsp, and if the only file in the application is default.jsp, that's what you see. Here is an example:

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

error-page

The error-page option enables you to specify the pages that handle various errors that might occur. You can map HTTP errors to specific error pages and also map Java exceptions to specific error pages. To map an HTTP error, use the <error-code> tag and specify the error number, such as 404. To map a Java exception, make sure you use the exception's fully qualified classname, such as java.lang.NullPointerException.

Here is an example of how to use error-page:

<error-page>
    <error-code>404</error-code>
    <location>Handle404Error.jsp</location>
</error-page>
<error-page>
    <exception-type>java.lang.NullPointerException
        </exception-type>
    <location>HandleNullPointerServlet</location>
</error-page>

session-config

The session-config option lets you change various settings related to sessions created by the application. Under the current servlet specification, the only option you can change is the session timeout, which is specified in minutes. The following session-config option sets the session timeout to 120 minutes (2 hours).

<session-config>
   <session-timeout>120</session-timeout>
</session-config>

Servlet Options

Servlet options enable you to change the options at the servlet level. Although there are several servlet options, they are all specified within one of two tags: either <servlet> or <servlet-mapping>.

servlet

The servlet option is the main option for changing a servlet's attributes. You can specify a servlet's name, class, description, initialization parameters, and startup information.

The <servlet-name> tag lets you specify the servlet's name. This name can be used in the <servlet-mapping> tag to create a URL mapping for the servlet. The servlet name alone is not enough to specify the name you use to access the servlet.

The <servlet-class> tag specifies the fully qualified pathname for the servlet. Instead of a servlet class, you might specify the name of a JSP file for this servlet by using the <jsp-file> tag.

Only the <servlet-name> and either <servlet-class> or <jsp-file> tags are required for the <servlet> tag; all others are optional.

The <display-name> tag specifies the short name of the servlet and might be used in a GUI tool. Likewise, the <description> tag specifies the long description of the servlet.

The <init-param> tag enables you to specify any number of initialization parameters for the servlet, which are passed in to the servlet via the ServletConfig class. The <init-param> tag must contain a single <param-name> and a single <param-value> tag and might optionally contain a <description> tag.

The <load-on-startup> tag indicates that you want the servlet to be loaded when the Web server first starts up. The data value associated with the tag is a priority number that enables you to specify an order for servlet startup. Servlets with lower numbers start first.

Listing B.4 shows how these elements are used to define a servlet.

Listing B.4 An Example of How to Declare the Attributes of a Servlet

<servlet>
    <servlet-name>MyServlet</servlet-name>
    <servlet-class>com.wutka.MyServlet</servlet-class>
    <display-name>MyVeryOwnServlet</display-name>
    <description>It's mine, all mine!</description>
    <init-param>
        <param-name>owner</param-name>
        <param-value>me</param-value>
    </init-param>
    <init-param>
        <param-name>belongsTo</param-name>
        <param-value>me</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>.

servlet-mapping

The servlet-mapping option lets you map URLs to servlets. At a minimum, you can use the servlet's name as the URL pattern, like this:

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

You can also map a servlet so that it handles any path that starts with a certain pattern. For example, when a path starts with /servlet, the Web server runs a special invoker servlet that extracts the servlet name from the rest of the path and executes it. The <servlet-mapping> definition for the invoker looks like this:

<servlet-mapping>
    <url-pattern>/servlet/*</url-pattern>
    <servlet-name>invoker</servlet-name>
</servlet-mapping>

In development environments, the invoker servlet is often enabled in the default application descriptor to make it easier to deploy and test servlets. However, it's a better idea to create appropriate deployment descriptors for your application. Because of the security risks, Tomcat does not enable the invoker by default.

JSP Options

Most options for JSPs are available to the Web application developer through two elements, <jsp-file> and <jsp-config>.

jsp-file

Often, you'll want to use a JSP by referring to it using a mapping, in the same way that you do a servlet.

The <jsp-file> element is used to associate configuration properties with a JSP. For example, if you wanted to keep your JSPs in a separate folder and without complicating the URI, you can use a mapping like this:

<servlet>
   <servlet-name>myJsp</servlet-name>
   <jsp-file>/jsps/myJsp.jsp</jsp-file>
   <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
   <servlet-name>myJsp</servlet-name>
   <url-pattern>/myJsp.jsp</url-pattern>
</servlet-mapping>

As you can see, the <jsp-file> element is similar to the <servlet-class> element discussed earlier.

jsp-config

Global configuration information for JSPs is provided through jsp-config. Tag libraries are declared in this element with the subelement taglib. For JSP 2.0, you have an additional option, the jsp-property-group.

jsp-property-group

The most significant change to the deployment descriptor for JSP 2.0 comes with the introduction of jsp-property-group. With jsp-property-group, you can define characteristics for groups of JSPs. Several property groups may apply to a single page. In this case, the property groups are applied in the order they appear in web.xml.

A group of JavaServer Pages is defined by using <url-pattern> in the same way that you define the url-pattern for servlet mapping.

The <el-ignored> tag sets the isELIgnored property of a group of JSP pages. It's enabled by default for Web applications using a Servlet 2.4 or greater web.xml. Otherwise, it's disabled.

The <page-encoding> tag allows you to declare the page encoding for a group of JSPs using the same values as those of the page-encoding directive. You must make certain that you declare page encodings that are consistent within a page; in other words, you can't declare a page encoding using a directive and then redeclare it to something else using this configuration element.

If you want to prohibit scripting for a group of JSPs, you can use <scripting-invalid>.

JSPs can now be defined as valid XML documents. By setting the value for the <is-xml> element to "true," you're declaring that this group of resources must be interpreted as XML documents.

Two new tags, <include-prelude> and <include-coda>, allow you to include resources available to the Web application at the beginning or end of each page. It's equivalent to using include directives. If more than include-prelude or include-coda appears in a property group, they're included in the order they appear.

Listing B.5 demonstrates how to declare attributes for a group of JSPs.

Listing B.5 An Example of How to Use jsp-property-group

<jsp-config>
  <jsp-property-group>
    <display-name>A Property Group</display-name>
    <url-pattern>*.jsp</url-pattern>
    <el-ignored>false</el-ignored>
    <scripting-invalid>false</scripting-invalid>
    <is-xml>false</is-xml>
    <include-prelude>/templates/prelude.jspf</include-prelude>
    <include-coda>/templates/coda.jspf</include-coda>
  </jsp-property-group>
</jsp-config>

Others

There are other config options dealing with servlet filters, listeners, security, and custom tag libraries. These are covered in detail in the earlier hours of the book.