The JavaTM Web Services Tutorial
Home
TOC
Index 		PREV TOP NEXT
Divider

Configuring Web Applications

Web applications are configured via elements contained in Web application deployment descriptors. You can either manually create descriptors using a text editor or use deploytool to generate descriptors for you. The following sections give a brief introduction to the Web application features you will usually want to configure. A number of security parameters can be specified; these are covered in Web Application Security. For a complete listing and description of the features, see the Java Servlet specification.

In the following sections, some examples demonstrate procedures for configuring the Hello, World application. If Hello,World does not use a specific configuration feature, the section gives uses other examples for illustrating the deployment descriptor element and describes generic procedures for specifying the feature using deploytool. Extended examples that demonstrate how to use deploytool are in The Example Servlets and The Example JSP Pages.

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

Since the deployment descriptor is an XML document, it requires a 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/dtd/web-
app_2_3.dtd">

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 Installing 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 greeting page has an alias but response.jsp is referenced by its file name.

To set up the mappings servlet version of the Hello application in the Web deployment descriptor, you must add the following servlet and servlet-mapping elements to the Web application deployment descriptor. To define an alias for a JSP page, you must replace the servlet-class subelement with a jsp-file subelement in the servlet element. 

<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>

To set up the mappings for the servlet version of the Hello application in deploytool:

  1. Select the hello1 WAR.
  2. Select the GreetingServlet Web component.
  3. Select the Aliases tab.
  4. Click Add to add a new mapping.
  5. Type /greeting in the aliases list.
  6. Select the ResponseServlet Web component.
  7. Click Add.
  8. Type /response in the aliases list.

Context and Initialization Parameters

The Web components in a WAR share an object that represents their application context (see Accessing the Web Context). You can pass parameters to the context or Web component. To do so you must add a context-param or init-param element to the Web application deployment descriptor. context-param is a subelement of the top-level web-app element. init-param is a subelement of the servlet element. Here is the element used to declare a context parameter that sets the resource bundle used in the example discussed in Chapter 16: 

<web-app>
  <context-param>
    <param-name>
      javax.servlet.jsp.jstl.fmt.localizationContext
    </param-name>
    <param-value>messages.BookstoreMessages</param-value>
  </context-param>
  ...
</web-app>

To add a context parameter in deploytool:

  1. Select the WAR.
  2. Select the Context tab.
  3. Click Add.

To add an initialization parameter in deploytool:

  1. Select the Web component.
  2. Select the Init Param. tab.
  3. Click Add.

Event Listeners

To add an event listener class (described in Handling Servlet Life Cycle Events), you must add a listener element to the Web application deployment descriptor. Here is the element that declares the listener class used in chapters 12 and 16: 

<listener>
  <listener-class>listeners.ContextListener</listener-class>
</listener>

To add an event listener in deploytool:

  1. Select the WAR.
  2. Select the Event Listeners tab.
  3. Click Add.
  4. Select the listener class from the new field in the Event Listener Classes pane.

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). 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 used to declare the order filter and map it to the ReceiptServlet discussed in Chapter 12: 

<filter>
  <filter-name>OrderFilter<filter-name>
  <filter-class>filters.OrderFilter<filter-class>
</filter>
<filter-mapping>
  <filter-name>OrderFilter</filter-name>
  <url-pattern>/receipt</url-pattern>
</filter-mapping>

To add a filter in deploytool:

  1. Select the WAR.
  2. Select the Filter Mapping tab.
  3. Add a filter.
    1. Click Edit Filter List.
    2. Click Add.
    3. Select the filter class.
    4. Enter a filter name.
    5. Add any filter initialization parameters.
    6. Click OK.
  4. Map the filter.
    1. Click Add.
    2. Select the filter name.
    3. Select the target type. A filter can be mapped to a specific servlet or to all servlets that match a given URL pattern.
    4. Specify the target. If the target is a servlet, select the servlet from the drop-down list. If the target is a URL pattern, enter the pattern.

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). 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 Chapter 12: 

<error-page>
  <exception-type>exception.OrderException</exception-type>
  <location>/errorpage.html</location>
</error-page>

To add an error mapping in deploytool:

  1. Select the WAR.
  2. Select the File Refs tab.
  3. Click Add in the Error Mapping pane.
  4. Enter the HTTP status code (see HTTP Responses) or fully-qualified class name of an exception in the Error/Exception field.
  5. Enter the name of a resource to be invoked when the status code or exception is returned. The name should have a leading forward slash /.
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 in the Web application deployment descriptor. Here is the element used 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>

To add a reference in deploytool:

  1. Select the WAR.
  2. Select the Environment, Enterprise Bean Refs, Resource Env. Refs, or Resource Refs tab.
  3. Click Add in the pane to add a new reference.
Divider
Home
TOC
Index 		PREV TOP NEXT
Divider

This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.

All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.