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.

To package and deploy the example using asant, follow these steps:

  1. Run asant create-bookstore-war.
  2. Run asant deploy-war.

To learn how to configure the example, use deploytool to package and deploy it:

  1. Start deploytool.
  2. Create a web application called hello2 by running the New Web Component wizard. Select FileRight ArrowNewRight ArrowWeb Component.
  3. In the New Web Component wizard:
    1. Select the Create New Stand-Alone WAR Module radio button.
    2. In the WAR File field, enter <INSTALL>/j2eetutorial14/examples/web/hello2/hello2.war. The WAR Display Name field will show hello2.
    3. In the Context Root field, enter /hello2.
    4. Click Edit Contents to add the content files.
    5. 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.
    6. Click Next.
    7. Select the Servlet radio button and click Next.
    8. Select GreetingServlet from the Servlet Class combo box.
    9. Click Finish.
  4. Select FileRight ArrowNewRight ArrowWeb 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 and click Next.
    4. Select ResponseServlet from the Servlet Class combo box and 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 FileRight ArrowSave.

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.