The Java(TM) Web Services Tutorial

The Java^TM Web Services Tutorial

Web Application Deployment Descriptors

The following sections give a brief introduction to the Web application deployment descriptor elements you will usually want to specify. A number of security parameters can be specified but this release of the tutorial does not cover them. For a complete listing and description of the elements, see the Java Servlet specification. The simpler applications discussed in Creating the Getting Started Application, Updating Web Applications, and What is a JSP Page? (page 430) do not need a Web application deployment descriptor, but all the others are distributed with a descriptor.

Note: Descriptor elements must appear in the deployment descriptor in the following order: icon, display-name, description, distributable, context-param, filter, filter-mapping, listener, servlet, servlet-mapping, session-config, mime-mapping, welcome-file-list, error-page, taglib, resource-env-ref, resource-ref, security-constraint, login-config, security-role, env-entry.

Prolog

The prolog of the Web application deployment descriptor is as follows:
<?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/j2ee/dtds/web-
app_2_3.dtd"> 
 
Context Parameters

The Web components in a WAR share an object that represents their Web context (see Accessing the Web Context (page 421)). To pass initialization parameters to the context, you must add a context-param element to the Web application deployment descriptor. Here is the element used to declare a context parameter that sets the resource bundle used in the example discussed in JavaServer Pages Standard Tag Library (page 497):
<context-param>	
   <param-name>	
      javax.servlet.jsp.jstl.i18n.basename	
   </param-name>	
   <param-value>messages.BookstoreMessages</param-value>	
</context-param> 
 
Filter Mappings

A Web container uses filter mapping declarations to decide which filters to apply to a request, and in what order (see Specifying Filter Mappings (page 415)). The container matches the request URI to a servlet as described in Alias Paths. To determine which filters to apply, it matches filter mapping declarations by servlet name or URL pattern. The order in which filters are invoked is the order in which filter mapping declarations that match a request URI for a servlet appear in the filter mapping list.

To specify a filter mapping you must add an filter and filter-mapping elements to the Web application deployment descriptor. Here is the element use to declare the order filter and map it to the ReceiptServlet discussed in Java Servlet Technology (page 393):
<filter>	
   <filter-name>OrderFilter<filter-name>	
   <filter-class>filters.OrderFilter<filter-class>	
</filter>	
<filter-mapping>	
   <filter-name>OrderFilter</filter-name>	
   <url-pattern>ReceiptServlet</url-pattern>	
</filter-mapping>
 
Event Listeners

To add an event listener class (described in Handling Servlet Life Cycle Events (page 397)), you must add a listener element to the Web application deployment descriptor. Here is the element use to declare the listener class used in Java Servlet Technology (page 393) and JavaServer Pages Standard Tag Library (page 497):
<listener>	
   <listener-class>listeners.ContextListener</listener-class>	
</listener>
 
Alias Paths

When a request is received by Tomcat it must determine which Web component should handle the request. It does so by mapping the URL path contained in the request to a Web component. A URL path contains the context root (described in Running Web Applications) and an alias path:
http://<host>:8080/context root/alias path
 
Before a servlet can be accessed, the Web container must have least one alias path for the component. The alias path must start with a '/' and end with a string or a wildcard expression with an extension (*.jsp for example). Since Web containers automatically map an alias path that ends with *.jsp, you do not have to specify an alias path for a JSP page unless you wish to refer to the page by a name other than its file name. In the example discussed in Updating Web Applications, the page greeting.jsp has an alias, /greeting, but the page response.jsp is referenced by its file name within greeting.jsp.

To set up the mappings for the servlet version of the Hello application you must add the following servlet and servlet-mapping elements to the Web application deployment descriptor:
<servlet>	
   <servlet-name>greeting</servlet-name>	
   <display-name>greeting</display-name>	
   <description>no description</description>	
   <servlet-class>GreetingServlet</servlet-class>	
</servlet>	
<servlet>	
   <servlet-name>response</servlet-name>	
   <display-name>response</display-name>	
   <description>no description</description>	
   <servlet-class>ResponseServlet</servlet-class>	
</servlet>	
<servlet-mapping>	
   <servlet-name>greeting</servlet-name>	
   <url-pattern>/greeting</url-pattern>	
</servlet-mapping>	
<servlet-mapping>	
   <servlet-name>response</servlet-name>	
   <url-pattern>/response</url-pattern>	
</servlet-mapping>
 
Error Mappings

You can specify a mapping between the status code returned in an HTTP response or a Java programming language exception returned by any Web component and a Web resource (see Handling Errors (page 399)). To set up the mapping, you must add an <error-page> element to the deployment descriptor. Here is the element use to map OrderException to the page errorpage.html used in Java Servlet Technology (page 393):
<error-page>	
   <exception-type>exception.OrderException</exception-type>	
   <location>/errorpage.html</location>	
</error-page>
 
Note: You can also define error pages for a JSP page contained in a WAR. If error pages are defined for both the WAR and a JSP page, the JSP page's error page takes precedence.

References to Environment Entries, Resource Environment Entries, or Resources

If your Web components reference environment entries, resource environment entries, or resources such as databases, you must declare the references with <env-entry>, <resource-env-ref>, or <resource-ref> elements. Here is the element use to declare a reference to the data source used in the Web technology chapters in this tutorial:
<resource-ref>	
   <res-ref-name>jdbc/BookDB</res-ref-name>	
   <res-type>javax.sql.DataSource</res-type>	
   <res-auth>Container</res-auth>	
</resource-ref>
 

Home
TOC