Download PDF Home History |  | API Search Feedback FAQ

> ## Configuring Web Applications

> Web applications are configured via elements contained in the Web application deployment descriptor. The `deploytool` utility generates the descriptor when you create a WAR and adds elements when you create Web components and associated classes. You can modify the elements via the inspectors associated with the WAR.

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

> In the following sections, 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 to specify the deployment descriptor element and describes generic procedures for specifying the feature using `deploytool`. Extended examples that demonstrate how to use `deploytool` appear in later tutorial chapters.

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

> The alias identifies the Web component that should handle a request. The alias path must start with a forward slash (`/`) and end with a string or a wildcard expression with an extension (for example, `*.jsp`). 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. To set up the mappings for the servlet version of the `hello` application with `deploytool`, first package it, as described in the following steps.

> 1. In a terminal window, go to `<``INSTALL``>/j2eetutorial14/examples/web/hello2/`.
> 2. Run `asant` `build`. This target will compile the servlets to the `<``INSTALL``>/j2eetutorial14/examples/web/hello2/build/` directory.
> 3. Start `deploytool`.
> 4. Create a Web application called `hello2` by running the New Web Component wizard. Select FileNewWeb Component.
> 5. In the New Web Component wizard:
> 1. Select the Create New Stand-Alone WAR Module radio button.
> 2. In the WAR Location field, enter `<``INSTALL``>/j2eetutorial14/examples/web/hello2/hello2.war`.
> 3. In the WAR Name field, enter `hello2`.
> 4. In the Context Root field, enter `/hello2`.
> 5. Click Edit Contents to add the content files.
> 6. In the Edit Contents dialog box, navigate to `<``INSTALL``>/j2eetutorial14/examples/web/hello2/build/`. Select `duke.waving.gif` and the `servlets` package and click Add. Click OK.
> 7. Click Next.
> 8. Select the Servlet radio button.
> 9. Click Next.
> 10. Select `GreetingServlet` from the Servlet Class combo box.
> 11. Click Finish.
> 6. Select FileNewWeb Component.
> 1. Click the Add to Existing WAR Module radio button and select `hello2` from the combo box. Because the WAR contains all the servlet classes, you do not have to add any more content.
> 2. Click Next.
> 3. Select the Servlet radio button.
> 4. Click Next.
> 5. Select `ResponseServlet` from the Servlet Class combo box.
> 6. Click Finish.

> Then, to set the aliases, follow these steps:

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

> To run the application, first deploy the Web module, and then open the URL `http://localhost:8080/hello2/greeting` in a browser.

> ### 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 to the partial request each welcome file in the order specified 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, the Application Server 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`, the Application Server returns a directory listing.

> To specify welcome files with `deploytool`, follow these steps:

> 1. Select the WAR.
> 2. Select the File Ref's tab in the WAR inspector.
> 3. Click Add File in the Welcome Files pane.
> 4. Select the welcome file from the drop-down list.

> The example discussed in Encapsulating Reusable Content Using Tag Files has a welcome file.

> ### 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 add a context parameter with `deploytool`, follow these steps:

> 1. Select the WAR.
> 2. Select the Context tab in the WAR inspector.
> 3. Click Add.

> For a sample context parameter, see the example discussed in The Example JSP Pages.

> To add a Web component initialization parameter with `deploytool`, follow these steps:

> 1. Select the Web component.
> 2. Select the Init. Parameters tab in the Web component inspector.
> 3. Click Add.

> ### Mapping Errors to Error Screens

> When an error occurs during execution of a Web application, you can have the application display a specific error screen according to the type of error. In particular, 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 (see Handling Errors) and any type of error screen. To set up error mappings with `deploytool`:

> 1. Select the WAR.
> 2. Select the File Ref's tab in the WAR inspector.
> 3. Click Add Error in the Error Mapping pane.
> 4. Enter the HTTP status code (see HTTP Responses) or the fully qualified class name of an exception in the Error/Exception field.
> 5. Enter the name of a Web 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 screens for a JSP page contained in a WAR. If error screens are defined for both the WAR and a JSP page, the JSP page's error page takes precedence. See Handling Errors .

> For a sample error page mapping, see the example discussed in The Example Servlets.

> ### Declaring Resource References

> If your Web component uses objects such as databases and enterprise beans, you must declare the references in the Web application deployment descriptor. For a sample resource reference, see Specifying a Web Application's Resource Reference. For a sample enterprise bean reference, see Specifying the Web Client's Enterprise Bean Reference.

Download PDF Home History |  | API Search Feedback FAQ

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