Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

Configuring Web Applications

Web applications are configured via elements contained in the Web application deployment descriptor. You can manually create descriptors using a text editor. 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 Specifying Security Constraints. 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 references to other examples that illustrate how the deployment descriptor element and describes generic procedures for specifying the feature.

Prolog

Since the Web application 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="UTF-8"?>
<web-app version="2.4" 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"> 

Mapping URLs to Web Components

When a request is received by the Web container 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 application and a Web component. A URL path contains the context root and an alias:

http://host:port/context_root/alias 

when you install (see Installing Web Applications) or deploy (Deploying Web Applications) a Web application to Tomcat.

Setting the Component Alias

The alias identifies the Web component that should handle a request. The servlet path must start with a forward slash / and end with a string or a wildcard expression with an extension (*.jsp, for example). Since Web containers automatically map an alias that ends with *.jsp, you do not have to specify an alias for a JSP page unless you wish to refer to the page by a name other than its file name. In the hello2 example, the greeting page has an alias, but response.jsp is called by name.

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

<servlet>
  <display-name>greeting</display-name>
  <servlet-name>GreetingServlet</servlet-name>
  <servlet-class>servlets.GreetingServlet</servlet-class>
</servlet>
<servlet>
  <display-name>ResponseServlet</display-name>
  <servlet-name>ResponseServlet</servlet-name>
  <servlet-class>servlets.ResponseServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>GreetingServlet</servlet-name>
  <url-pattern>/greeting</url-pattern>
</servlet-mapping>
<servlet-mapping>
  <servlet-name>ResponseServlet</servlet-name>
  <url-pattern>/response</url-pattern>
</servlet-mapping> 

Declaring Welcome Files

The welcome files mechanism allows you to specify a list of files that the Web container will use for appending to a request for a URL (called a valid partial request) that is not mapped to a Web component.

For example, suppose you define a welcome file welcome.html. When a client requests a URL such as host:port/webapp/directory, where directory is not mapped to a servlet or JSP page, the file host:port/webapp/directory/welcome.html is returned to the client.

If a Web container receives a valid partial request, the Web container examines the welcome file list and appends each welcome file in the order specified to the partial request and checks whether a static resource or servlet in the WAR is mapped to that request URL. The Web container then sends the request to the first resource in the WAR that matches.

If no welcome file is specified, Tomcat will use a file named index.XXX, where XXX can be html or jsp, as the default welcome file. If there is no welcome file and no file named index.XXX, Tomcat returns a directory listing.

To specify welcome files in the Web application deployment descriptor, you add welcome-file elements in the welcome-file-list element:

<welcome-file-list>
  <welcome-file>greeting.jsp</welcome-file>
</welcome-file-list> 

Setting Initialization Parameters

The Web components in a Web module share an object that represents their application context (see Accessing the Web Context). You can pass initialization parameters to the context or to a Web component. To set initialization parameters, 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 17:

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

For an example context parameter, see The Example JSP Pages.

Specifying 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 add an <error-page> element to the Web application deployment descriptor. Here is the element used to map OrderException to the page errorpage.html used in Chapter 15:

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


For an example error page mapping, see The Example Servlets.

Declaring 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. For an example resource reference, see Configuring the Web Application to Reference a Resource.

Replace host with the name of the host running the application server. If your browser is running on the same host as the application server, you can replace host with localhost.

Replace port with value you specified for the HTTP server port when you installed the Java WSDP. The default value is 8080.

The examples in this tutorial assume that your application server host and port is localhost:8080.

Divider
Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

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