Download FAQ History |  | API Search Feedback

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

> #### Setting the Context Root

> A context root identifies a Web application. A context root must start with a forward slash `/`, and end with a string. You set the context root of the `hello1` application 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>
>       <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>

> ### 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 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 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 must add an `<error-page>` element to the Web application deployment descriptor. Here is the element use 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 Data Source with JNDI.

Download FAQ History |  | API Search Feedback

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.