Building J2EE Applications

FIGURE 2-1 shows a web module and the interactions in which it participates. This module is part of a Java 2 Platform, Enterprise Edition (J2EE platform) application, and the interactions shown in the figure are typical for web modules in J2EE applications. The web module interacts with users over HTTP connections (represented in the figure by the arrows labeled #1) and with middle-tier services provided by Enterprise JavaBeans (EJB) modules (represented by the arrows labeled #3). Inside the web module, the web components interact with each other (represented by the arrows labeled #2). This chapter describes this web module and explains how to program the interactions shown in FIGURE 2-1.

FIGURE 2-1 The CatalogWebModule Web Module

[ D ]

---

The Interactions in This Module

This scenario describes one possible use of the web module and interactions that are illustrated in FIGURE 2-1. In this scenario, the module is the front end for a J2EE application that supports a retail web site. The web module contains the web pages that are displayed to online shoppers who visit the site. The module also processes shopper input on those pages. Displaying pages and processing input are typical tasks for a web module in a J2EE application.

From the shopper's point of view, this application is a series of web pages. Shoppers use web browsers to view the application's home page. Shoppers also provide input with the text fields, buttons, and other controls that appear on the web pages. From the developer's point of view, the application is a set of web components that receive HTTP requests and return HTTP responses.

The web module in this scenario contains only a few components and processes only two different requests. Although simple, these components and requests show you how web components provide the necessary interaction between users, web module, and EJB module. The specific interactions that are covered in this scenario are outlined in the following list:

1. An online shopper opens a connection to the application by starting a web browser and opening the application's root URL. This action opens the application's home page. A real-world shopping site's home page displays many options, including requests for displaying items by category, requests for keyword search, requests for information about live customer service, and so on. In this simple example, the home page shows only one option, which is a link to another page that displays the entire catalog.

2. The shopper clicks the link. This action generates a request that is processed by the servlet that is named in the request, AllItemsServlet. AllItemsServlet processes the request by calling a business method of an EJB module, the getAllItems method, which returns the data.

3. AllItemsServlet prepares the data that is returned from the EJB module for display in the shopper's browser. The servlet combines the individual field values that are returned from the EJB module with HTML tags that format the field values. AllItemsServlet writes this combination of field values and HTML tags to an output stream that is returned to the user's web browser. The shopper's web browser processes the HTML output and displays the catalog. In the catalog display, each item name is displayed as an HTML link to detailed information about the item.

4. The shopper browses the displayed catalog and clicks one of the links. This request is processed by another servlet, DetailServlet. DetailServlet calls another business method of the EJB module, getOneItemDetail, for the item detail.

5. DetailServlet processes the data returned from the EJB module for display in the shopper's web browser. Like AllItemsServlet, DetailServlet prepares an output stream that combines field values and HTML tags. The shopper's web browser processes this output stream and displays it as another web page.

The HTML outputs that are written by AllItemsServlet and DetailServlet contain only text. Although simple, these examples show you how web components can process HTTP requests by making remote method calls to obtain data from an EJB module and then writing the data into an HTML output stream. An experienced web designer or web programmer can use this type of operation to write much more complex output.

The interaction between the web module and the EJB module is implemented by Java Remote Method Invocation (RMI) method calls. Java RMI is required by the design of the EJB module. For more information about the design of the EJB module, see The Interactions in This Module.

For instructions on creating the web components, writing enterprise business logic in web components, and similar tasks, see Building Web Components.

---

Programming This Module

TABLE 2-1 summarizes the programming that is required to create the web module that is described in the preceding section and illustrated in FIGURE 2-1.

The sections that follow show you how to perform many of these programming tasks. The method signatures specify the inputs and outputs of each interaction. The procedure sections show you how to connect these inputs and outputs to other components and other modules. Instructions for creating a web module or adding the web components to the module are not included. To learn about these tasks, see the online help or Building Web Components.

Creating the Welcome Page

The design for the retail web site calls for shoppers to begin their interaction with the site at a home page. The home page, a typical web site feature, provides an entry point for users that identifies the site and presents the options that are available to them. Shoppers view the home page and choose the features they want to use.

The shopper's first action is to start a browser and open the URL for the shopping site. Inside the web module, this URL has been mapped to the application's context root. If you want the application to display the home page whenever users open the site's URL, identify the home page as the welcome page.

Creating the HTML Page

In the Filesystems window's hierarchy of nodes, the HTML file for the welcome page must be at the same level as the web module's WEB_INF node. For an example, see FIGURE 1-2.

To create an HTML file at the correct level, use the following procedure:

1. Right-click the node for the file system that contains the green WEB-INF node, and choose New All Templates.

The New wizard's Choose Template page opens.

2. Choose the HTML File template.

a. In the Select a Template field, expand the JSPs & Servlets node and select the HTML File node.

b. Click Next.

The New wizard's New Object Name page opens.

3. In the name field, type index. Click Finish.

The integrated development environment (IDE) creates the new HTML file and represents it in the Filesystems window with a new node named index. The Source Editor opens with the cursor in the new file.

4. Type the HTML code for your welcome page.

CODE EXAMPLE 2-1 shows the HTML code for the simple welcome page that is used in this scenario.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>

  <head>

    <title>Online Catalog</title>

  </head>

  <body>

<h2>

Inventory List Application

</h2>

<p>

<a href="allItems">Display the Catalog

</a>

</body>

</html>

This welcome page presents only one option to users, which is a text link named Display the Catalog. This link uses a URL pattern to specify one of the servlets in the module, AllItemsServlet. When a user clicks this link, the browser sends another request to the web module. The request is processed by executing AllItemsServlet. The next page the user sees is the page that is output by AllItemsServlet. To see the page that is output by AllItemsServlet, refer to CODE EXAMPLE 2-2.

The welcome page for a real-world web site includes many links to different functions, but each link follows the principle that is demonstrated in this example. Pages that are displayed to the user contain links or actions that generate HTTP requests. Each request is processed by some component in the web module, and the web module responds by writing out another page for the user to see.

In this example, the link specifies a servlet, but not a method of the servlet. When a request specifies only a servlet name, the default action is to execute the servlet's doGet method. You can also write links that specify one of the servlet's other methods, such as doPost. For more information on servlet methods, see Building Web Components.

Identifying Your Page as the Module's Welcome Page

When you create a web module in the IDE, the module has a Welcome Files property that lists the default names for the welcome page files. FIGURE 2-2 shows the Welcome Files property editor with the default names. When a user accesses the root URL for the application, the application server searches the module directory for files with these names. The first file found is displayed as the welcome page.

The easiest way to create a welcome file for a module is to create a file with one of these default names. In this scenario, for example, you created a file named index.html.

FIGURE 2-2 Welcome Files Property Editor

To use a file with a different name for the module's welcome page, use the following procedure:

1. In the Filesystems window, right-click the web node and select Properties.

The property sheet opens.

2. In the Deployment section, click the Welcome Files ellipsis (...) button.

The Welcome Files property editor displays.

3. Enter the name of the welcome page in the Item field and click Add. Click OK.

Programming the Servlet Methods

The servlets in this scenario obtain data from the EJB module by calling enterprise bean methods. There are two programming tasks for these method calls: coding the calling method and setting up a resource references, in the calling servlet, for the called enterprise bean. Coding the method body code is covered first.

The Method Body

CODE EXAMPLE 2-2 shows the implementation of the processRequest method in AllItemsServlet. This method executes when a user clicks the Display the Catalog link that appears on the welcome page.

The URL pattern on the welcome page names the servlet AllItemsServlet, but the URL pattern does not specify a method. In this case, the application server performs the default action and executes the servlet's doGet method. The doGet method calls the processRequest method.

CODE EXAMPLE 2-2 shows you how AllItemsServlet obtains the catalog data from the EJB module and displays it to the user. There are three steps:

1. AllItemsServlet uses a JNDI lookup to obtain a remote reference to a session enterprise bean in the CatalogData EJB module. For more information about the CatalogData module, see Chapter 3.

2. AllItemsServlet calls the getAllItems method, a business method of the session bean.

3. The servlet writes the data that is returned by the remote method call into the HTML output stream. The outlet stream is returned to the user's browser window.

protected void processRequest(HttpServletRequest request, 

                               HttpServletResponse response)

                               throws ServletException, IOException {

  response.setContentType("text/html");

  PrintWriter out = response.getWriter();

  /* output your page here */

  out.println("<html>");

  out.println("<head>");

  out.println("<title>AllItemsServlet</title>");

  out.println("</head>");

  out.println("<body>");

  out.println("<h2>The Inventory List</h2>");

  out.println("<table>");

  out.println("<tr>");

  out.println("<td>Item</td>");

  out.println("<td>Item SKU</td>");

  out.println("<td>Detail</td>");

  out.println("</tr>");

  CatalogBeans.CatalogManagerBeanHome catHome;

  CatalogBeans.CatalogManagerBean catRemote;

  try {

    InitialContext ic = new InitialContext();

    Object objref  = ic.lookup("java:comp/env/ejb/CatalogManagerBean");

    catHome = (CatalogBeans.CatalogManagerBeanHome) objref;

    catRemote = catHome.create();

    java.util.Vector allItems = catRemote.getAllItems();

    Iterator i = allItems.iterator();

    while (i.hasNext()) {

      CatalogBeans.iDetail itemDetail = (CatalogBeans.iDetail)i.next();

      out.println("<tr>" +

        "<td>" +

        itemDetail.getItemname() + "</td>" +

        "<td>" +

        itemDetail.getItemsku() + "</td>" +

        "<td>" + 

        "<a href=\"" + response.encodeURL("itemDetail?sku=" + 

        itemDetail.getItemsku()) + 

        "\"> " +

        "Get Item Detail" +

        "</a>" + "</td>" + "</tr>");

    }

  }

  catch (javax.naming.NamingException nE) {

    System.out.println("Naming Exception on Lookup" + nE.toString());

  }

  catch (javax.ejb.CreateException cE) {

    System.out.println("CreateException" + cE.toString());

  }

  catch (java.rmi.RemoteException rE) {

    System.out.println("RemoteException" + rE.toString());

  }

  catch (Exception e) {

    System.out.println(e.toString());

  }

  out.println("</table>");

  out.println("</body>");

  out.println("</html>");

  out.close();

}

The lookup statement specifies CatalogManagerBean, but this string is actually the name of the reference, not the enterprise bean that is referenced. The enterprise bean's name is often used as the reference name to make it easier to remember which bean is meant. The referenced enterprise bean is actually specified in the resource reference, which is covered in the next section.

The EJB Resource References

A web component, like AllItemsServlet, that calls methods of an enterprise bean in an EJB module does so by means of EJB references. The two parts of an EJB reference are as follows:

• JNDI lookup code, which uses the JNDI naming facility to obtain a remote reference to a named enterprise bean.
• A resource reference, which is part of the deployment descriptor, tells the application server to which specific bean the lookup code refers.

In this scenario, the lookup code is in the processRequest method of AllItemsServlet (see CODE EXAMPLE 2-2). You can compile this code, but without the resource reference, it cannot return a reference at runtime. The resource reference maps the reference name that is used in the lookup statement to the actual name of an enterprise bean.

To set up an EJB resource reference for a web module, use the following procedure:

1. Right-click the web module's web node and choose Properties. In the References section, click the EJB References ellipsis (...) button.

The EJB references property editor opens.

2. Click the Add button.

The Add EJB Reference dialog opens. Use this dialog to set up the resource reference.

3. To set up the reference, type the resource reference name that is used in the lookup statement and the names of the home and remote interfaces that are used in the method calls.

FIGURE 2-3 shows the Add EJB Reference dialog box with these values in the fields. For the reference to work at runtime and the JNDI lookup to return a remote reference to an enterprise bean, the reference must be linked to a specific enterprise bean in the same application. The reference must be linked before you deploy and execute the application, but it need not be done now.

At this point in development, you can leave the reference unlinked and link it later, after you assemble the web module into a J2EE application. In some circumstances, you might choose to resolve the reference at this stage of development. Consider the following conditions:

• If the enterprise bean is not in your development environment, you cannot link the reference. Supply the names of the interfaces and click OK. You cannot compile the JNDI lookup code unless you have copies of the interfaces mounted in your development environment.

FIGURE 2-3 shows the Add EJB Reference dialog box setting up an unlinked reference. The Home Interface and Remote Interface are specified, but the Referenced EJB Name field is empty. The reference will be linked later on the application property sheet.

FIGURE 2-3 EJB Reference Property Editor With Unlinked Reference

[ D ]

• If the enterprise bean is available in your development environment, you can link the reference now. Click the Browse button next to the Referenced EJB Name field. Use the dialog box that appears to select the called enterprise bean. Click OK.

FIGURE 2-4 shows the reference named ejb/CatalogManagerBean linked to CatalogManagerBean.

FIGURE 2-4 EJB Reference Property Editor With Linked Reference

[ D ]

Even if the called enterprise bean is available, you might choose not to link the reference now. There are many reasons to wait. For example, if there is any chance that your web component will be used in more than one application, you do not want to link the reference on the web module's property sheet. A developer who reuses the web module can relink the reference to some other enterprise bean that implements the same interfaces. Relinking the reference changes the value in the web.xml deployment descriptor file and affects every use of the source code.

In this scenario, the reference is left unlinked, as shown in FIGURE 2-3. The reference is linked after the J2EE application is created, on the application node's property sheet. See Linking the EJB Reference.

Mapping URLs to the Servlets

The link you set up on the welcome page is formatted with the following HTML tag:

<a href="allItems">Display the Catalog</a>

When a shopper clicks this link, the application server appends the URL pattern in the HTML tag to a URL path and executes the resulting URL. For the link to work properly, the URL that is generated by the application server must map to the servlet that you want to execute. The next section explains how URLs are mapped to servlets.

Understanding Servlet Mappings

In a deployed web module, the URLs for servlets and other web resources in the web module are the result of appending names to a URL path. For modules that are deployed to the Sun Java System Application Server Standard Edition 7, the URL path has this general form:

http://hostname:port/web-context/URL-pattern

The elements in this path are determined as follows:

• The host name is the name of the machine that the application server is running on, and the port is the port that is specified for that server instance's HTTP requests. The port number is assigned when the application server is installed.
• The web context is a string that you specify as a property of the web module after you add the module to a J2EE application. The web context qualifies all of the web resources in the module.
• The URL pattern is a string that identifies a specific servlet or JavaServer Pages (JSP) page. You set up the URL pattern on the web module property sheet. You can do this before you assemble the web module into a J2EE application.

In other words, the URL patterns that you assign in your web module are relative to a web context that you will assign later when you add the module to a J2EE application. The URLs in this scenario use a format that makes them relative to the web context. Whatever web context you supply when you assemble the application, these links will work properly when the application executes. For information on setting the web context, see Setting the Web Context for the Web Module.

Examining Default Servlet Mappings

When you create a servlet, by default, the Servlet wizard uses the class name that you supply on the first page of the Servlet wizard for the servlet name and maps the servlet name to a URL pattern that includes the servlet name. FIGURE 2-5 shows the Servlet Mappings property editor for the web module with the default settings for AllItemsServlet.

FIGURE 2-5 Servlet Mappings Property Editor

[ D ]

If you deploy the web module with this servlet mapping, AllItemsServlet is mapped to the following URL:

http://hostname:port/web-context/servlet/AllItemsServlet

Editing Servlet Mappings

If you want to map a different URL to the servlet, use the Servlet Mappings property editor to edit the mapping. In this scenario, you change the URL pattern from the default value to a more meaningful value.

To edit the servlet mapping, use the following procedure:

1. Right-click the web module's web node and choose Properties. In the Deployment section, click the Servlet Mappings ellipsis (...) button.

The Servlet Mappings property editor opens. The Servlet Mappings property editor lists all servlets in the module and any mappings that are set up for them.

2. Select the current mapping for allItemsServlet and click the Edit button.

The Edit Servlet Mapping dialog box opens.

3. In the URL Pattern field, type /allItems and Click OK.

FIGURE 2-6 shows the Servlet Mappings property editor with new mappings for AllItemsServlet and ItemDetailServlet.

FIGURE 2-6 Servlet Mappings Property Editor

[ D ]

After you edit the servlet mappings, AllItemsServlet can be executed with the following URL:

http://hostname:port/web-context/allItems

Notice that the new URL pattern is the string you used in the HTML tag that creates the link on the welcome page (see CODE EXAMPLE 2-1). Clicking the link now executes AllItemsServlet.

Other Assembly Tasks

The preceding sections cover the assembly tasks that are required to assemble CatalogWebModule. This section covers web module assembly tasks that are not required by the CatalogWebModule scenario.

Your web modules might require you to perform some of these other assembly tasks. This section covers several web module assembly tasks that you are likely to perform.

Setting Up Error Pages

If you want to specify error pages for a web module, you must identify the error pages in the module's deployment descriptor within the Error Pages property editor.

To set up error pages for your web module, use the following procedure:

1. Right-click the web node and choose Properties. In the Deployment section, click the Error Pages ellipsis (...) button.

The Error Pages property editor opens.

2. Identify an error by HTTP error code or Java exception class and map it to a specific error page. Click Add.

You can identify errors either by an HTTP error code or a Java exception class. Notice that the editor has two Add buttons, one for each category of error. For either type, you specify the error and map it to a page. FIGURE 2-7 shows the property editor after HTTP error code 404 has been mapped to a specific error page.

FIGURE 2-7 Error Pages Property Editor

Setting Up JSP Pages

If the web module you are assembling contains JSP page components, you have several ways to execute those components. If you create a new JSP page named myJsp, you can execute it in any of the following ways.

Executing JSP Pages With HTML Links

If you want to execute a JSP page from an HTML link, set up the link like the following example:

<a href="myJsp.jsp">Execute myJsp</a>

Executing JSP Pages Programmatically

If you create a JSP page with the IDE, no deployment descriptor entry is created for the JSP page. If your business logic accesses the JSP page programmatically, you do not need the deployment descriptor entry. For example, the following code is from a servlet that executes myJsp. Notice that the code identifies the JSP page to be executed by supplying its actual file name (myJsp.jsp).

...

response.setContentType("text/html"); 

        RequestDispatcher dispatcher; 

        dispatcher = getServletContext().getRequestDispatcher ("/myJsp.jsp"); 

        dispatcher.include(request, response); 

...

Using URL to JSP Mappings

The preceding examples execute a JSP page by specifying its actual file name, myJsp.jsp. You can also map a URL pattern to a JSP page and then execute the page by referring to its URL pattern. This is a two-step process. You first set up a servlet name for the JSP file.

To set up a URL mapping for a JSP page, use the following procedure:

1. Right-click the web node and choose Properties. In the Deployment section, click the JSP Files ellipsis (...) button.

The JSP Files property editor opens.

2. Click the Add button.

The Add JSP File dialog box opens.

a. In the JSP File field, type the file name of the JSP file you are setting up.

b. In the Servlet Name field, type the servlet name you are mapping to the JSP file.

c. Click OK.

The Add JSP File dialog box closes.

FIGURE 2-8 shows the JSP Files property editor after the servlet name itemDetailPage has been mapped to the file myJsp.jsp.

FIGURE 2-8 JSP Files Property Editor

[ D ]

3. Click OK again to close the JSP Files property editor and return to the property sheet.

4. Still in the property sheet, click the Servlet Mappings ellipsis (...) button.

The Servlet Mappings property editor opens.

5. Click the Add button.

The Add Servlet Mapping dialog box opens.

6. In the Add Servlet Mapping dialog box, map a URL pattern to the new servlet name.

a. In the Servlet Name field, type the servlet name you mapped to the JSP file.

b. In the URL Pattern field, type the URL pattern you are mapping to the servlet name and, ultimately, to the JSP file.

c. Click OK.

The Add Servlet Mapping dialog box closes.

FIGURE 2-9 shows the Servlet Mappings property editor with the URL pattern ItemDetail mapped to the servlet name ItemDetailPage. The servlet name ItemDetailPage is already mapped to the JSP file myJsp.jsp.

FIGURE 2-9 Servlet Mappings Property Editor

[ D ]

d. Click OK again to close the Servlet Mappings property editor.

After this mapping, the JSP page that is defined by the file myJSP.jsp can be executed with the following URL:

http://hostname:port/web-context/ItemDetail

Setting Up Resource Environment Entry References

Environment entries are data that you store in the EJB module deployment descriptor of your web service. Environment entries are available to your web service for use as parameters to the methods that create or find target objects. Because environment entries are stored in the deployment descriptor, they can be configured at deployment time to values appropriate for the runtime environment. For more information on environment entries, refer to Building Web Services.

There are two parts to an environment entry:

• A JNDI lookup. The web component that uses the environment entry uses the JNDI naming facility to look up the entry's value.
• A resource environment reference in the web module's deployment descriptor. The resource environment reference declares the reference to the application server. The deployment descriptor also contains a value for the environment entry.

JNDI Lookup for Resource Environment Entry References

A web component that uses the value of an environment entry needs lookup code like the code in CODE EXAMPLE 2-4.

try {

	// Obtain Initial Context--Opens Communication With JNDI Naming:

	Context ic = new InitialContext();

	// Request Lookup of Environment Entry Named "Cache Size":

	Integer cacheSize = (Integer)

	 ic.lookup("java:comp/env/NumberOfRecordsCached");

} 

catch(Exception e) {

	System.out.println(e.toString()); 

	e.printStackTrace();

	return; 

} 

The comments in the code explain what each line does.

Resource Reference for Environment Entries

To set up a resource reference for an environment entry, use the following procedure:

1. Right-click the web node and choose Properties. In the References section, click the Environment Entries ellipsis (...) button.

The Environment Entries property editor opens.

2. Click the Add button.

The Add Environment Entry dialog box opens.

3. Declare the environment entry reference.

a. In the Name field, type the reference name that is used in the lookup statement.

b. In the Type field, select the data type of the environment entry.

c. In the Value field, type an initial value for the environment entry.

FIGURE 2-10 shows the Add Environment Entry dialog box with values that match the lookup statement in CODE EXAMPLE 2-4.

FIGURE 2-10 Add Environment Entry Dialog Box

4. Click OK to close the dialog box and process your environment entry definition.

5. Click OK again to close the Environment Entries property editor.

Building J2EE Applications

819-0819-10

Copyright © 2004, Sun Microsystems, Inc. All Rights Reserved.