Recipe 1.5 Creating the Deployment Descriptor

Problem

You want to create the deployment descriptor for your application.

Solution

Name the XML file web.xml and place it in the WEB-INF directory of your web application. If you do not have an existing example of web.xml, then cut and paste the examples given in the servlet v2.3 or 2.4 specifications and start from there.

Discussion

The deployment descriptor is a very important part of your web application. It conveys the requirements for your web application in a concise format that is readable by most XML editors. The web.xml file is where you:

Register and create URL mappings for your servlets
Register or specify any of the application's filters and listeners
Specify context init parameter name/value pairs
Configure error pages
Specify your application's welcome files
Configure session timeouts
Specifiy security settings that control who can request which web components

This is just a subset of the configurations that you can use with web.xml. While a number of chapters in this book contain detailed examples of web.xml (refer to the "See Also" section), this recipe shows simplified versions of the servlet v2.3 and v2.4 deployment descriptors.

Example 1-3 shows a simple web application with a servlet, a filter, a listener, and a session-config element, as well as an error-page configuration. The web.xml in Example 1-3 uses the servlet v2.3 Document Type Definition (DTD). The main difference between the deployment descriptors of 2.3 and 2.4 is that 2.3 uses a DTD and 2.4 is based on an XML schema. You'll notice that the old version of web.xml has the DOCTYPE declaration at the top of the file, while the 2.4 version uses the namespace attributes of the web-app element to refer to the XML schema. The XML elements of Example 1-3 have to be in the same order as specified by the DTD.

Example 1-3. The deployment descriptor for servlet API 2.3

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
           "http://java.sun.com/dtd/web-application_2_3.dtd"
>

<web-app>

  <display-name>Servlet 2.3 deployment descriptor</display-name>

  <filter>
    <filter-name>RequestFilter</filter-name>
    <filter-class>com.jspservletcookbook.RequestFilter</filter-class>
  </filter>

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


  <listener>
    <listener-class>com.jspservletcookbook.ReqListener</listener-class>
  </listener>

  <servlet>
    <servlet-name>MyServlet</servlet-name>
    <servlet-class>com.jspservletcookbook.MyServlet</servlet-class>
   </servlet>

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

  <session-config>
    <session-timeout>15</session-timeout>
  </session-config>

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

</web-app>

Example 1-3 shows the web.xml file for an application that has just one servlet, accessed at the path <context path>/myservlet. Sessions time out in 15 minutes with this application. If a client requests a URL that cannot be found, the web container forwards the request to the /err404.jsp page, based on the error-page configuration. The filter named RequestFilter applies to all requests for static and dynamic content in this context. At startup, the web container creates an instance of the listener class com.jspservletcookbook.ReqListener.

Everything about Example 1-4 is the same as Example 1-3, except that the web-app element at the top of the file refers to an XML schema with its namespace attributes. In addition, elements can appear in arbitrary order with the servlet v2.4 deployment descriptor. For instance, if you were so inclined you could list your servlets and mappings before your listeners and filters.

Example 1-4. A servlet v2.4 deployment descriptor

<?xml version="1.0" encoding="ISO-8859-1"?>

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=
    "http://java.sun.com/xml/ns/j2ee 
      http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">

<!-- the rest of the file is the same as Example 1-3 after the web-app opening tag -->

</web-app>

The servlet 2.4 version of the deployment descriptor also contains definitions for various elements that are not included in the servlet 2.3 web.xml version: jsp-config, message-destination, message-destination-ref, and service-ref. The syntax for these elements appears in the specifications for JSP v2.0 and J2EE v1.4.