Building the EJB Tier of the DiningGuide Application

This chapter describes, step by step, how to create the EJB tier of the DiningGuide tutorial application. Along the way, you learn how to use the EJB Builder to create both entity and session beans, and how to use the IDE's test mechanism to test the beans. The topics covered in this chapter are:

• Overview of the Tutorial's EJB Tier
• Creating Entity Beans With the EJB Builder
• Creating Detail Classes to View Entity Bean Data
• Testing the Entity Beans
• Creating a Session Bean With the EJB Builder
• Testing the Session Bean
• Comments on Creating a Client

By the end of this chapter, you will be able to run the whole EJB tier of the DiningGuide application as a deployed test application.

After you have created the EJB tier, you are free to create your own web services and client pages. Alternatively, you can continue on to Chapter 4, to learn how to create the application's web services using the Sun ONE Studio 5 Web Services features.

---

Overview of the Tutorial's EJB Tier

In this chapter, you create the module that is the heart of the tutorial application, namely, its EJB tier. As you create each component, you test it using the IDE's test application facility, which automatically creates a test web service and test client.

The EJB tier you create will include:

• a Restaurant entity bean
• a Customerreview entity bean
• a DiningGuideManager session bean
• a RestaurantDetail bean
• a CustomerreviewDetail bean

For a complete discussion of the role of the EJB tier within J2EE architecture, see Building Enterprise JavaBeans Components in the Sun ONE Studio 5 Programming series. That document provides full descriptions of all the bean elements, and explains how transactions, persistence, and security are supported in enterprise beans.

To examine an application that also uses an EJB tier and a web service generated from it, see the PartSupplier example on the Sun ONE Studio 5 examples page, http://forte.sun.com/ffj/documentation/tutorialsandexamples.html

The Entity Beans

An entity bean provides a consistent interface to a set of shared data that defines a concept. In this tutorial, there are two concepts: restaurant and customer review. The Restaurant and Customerreview entity beans that you create represent the database tables you created in .

Entity beans can have either container-managed persistence (CMP) or bean-managed persistence (BMP). With a BMP entity bean, the developer must provide code for mapping the bean's fields to the database table columns. With a CMP entity bean, the EJB execution environment manages persistence operations. In this tutorial, you use CMP entity beans. Using the IDE's EJB Builder wizard, you connect to the database and indicate which columns to map. The wizard creates the entity beans mapped to the database.

The EJB Builder creates the CMP entity bean's framework, including the required home interface, remote interface, and bean class. The wizard also creates a logical node to organize and facilitate customization of the entity bean.

You manually define the entity bean's create, finder, and business methods. When you define these methods, the IDE automatically propagates the method to the appropriate bean components. For example, a create method is propagated to the bean's home interface and a corresponding ejbCreate method to the bean's class. When you edit the method, the changes are propagated as well.

With finder methods, you must define the appropriate database statements to find the objects you want. The EJB 2.0 architecture defines a database-independent version of SQL, called EJB QL, which you use for your statements. At deployment, the Sun ONE Application Server plugin translates the EJB QL into the SQL appropriate for your database and places the SQL in the deployment descriptor.

The Session Bean

Entity beans represent shared data, but session beans access data that spans concepts and is not shared. Session beans can also manage the steps required to accomplish a particular task. Session beans can be stateful or stateless. A stateful session bean performs tasks on behalf of a client while maintaining a continued conversational state with the client. A stateless session bean does not maintain a conversational state and is not dedicated to one client. Once a stateless bean has finished calling a method for a client, the bean is available to service a request from a different client.

In the DiningGuide application, client requests might include obtaining data on all the restaurants in the database or finding all the customer reviews for a given restaurant. Submitting a review for a given restaurant is another client request. These requests are not interrelated, and don't require maintenance of a conversational state. For these reasons, the DiningGuide tutorial uses a stateless session bean to manage the different steps required for each request.

The session bean repeatedly builds collections of restaurant and customer review records to satisfy a client's request. This task could be accomplished by adding getter and setter methods for each field onto the entity beans, but this approach would require calling a method for every field each time the session bean has to retrieve a row of the table. To reduce the number of method calls, this tutorial uses special helper classes, called detail classes, to hold the row data.

The Detail Classes

A detail class is a Java class that has fields that correspond to the container-managed fields of the entity beans, plus getter and setter methods for each field. When the session bean looks up an entity bean, it uses the corresponding detail class to create an instance of each remote reference returned by the entity bean. The session bean just calls the detail class's constructor to instantiate a row of data for viewing. In this way, the session bean can create a collection of row instances that can be formatted into an HTML page for the client to view. Returning detail class instances to the client consumes less network bandwidth than returning remote references for the entity bean instances.

FIGURE 3-1 shows graphically how the detail classes work.

 FIGURE 3-1 Function of a Detail Class

The numbered items in FIGURE 3-1 signify the following actions:

1. The web container passes a client's request for all restaurant data to the DiningGuideManager session bean.

2. The session bean calls the Restaurant entity bean's findAll method to perform a lookup on the Restaurant entity bean.

3. The findAll method obtains all available remote references to the entity bean.

4. For each remote reference returned, the session bean calls the Restaurant bean's getRestaurantDetail business method to fetch the RestaurantDetail class.

5. The getRestaurantDetail method returns a RestaurantDetail object, which is added to the collection.

6. The session bean returns a collection of all RestaurantDetail objects to the web container, which formats the data appropriately for the client to view.

Summary of Steps

Creating the EJB tier requires six steps:

1. Creating the entity beans

First, you create database schemas in the IDE, mapped from the tutorial's database tables. Next, using the EJB Builder, you create CMP entity beans that model the tables with the EJB Builder wizard. Then, you program the entity beans by adding and coding create, finder, and business methods.

2. Creating detail classes to be passed to the client for display

You create two JavaBeans classes with the same fields as the corresponding entity beans, and include the same accessor methods. These classes are used by the entity beans as types for parameters, fields, and return values. Returning these classes to the client is more efficient regarding network bandwidth than returning remote references for the entity bean instances.

3. Creating business methods on the entity beans to fetch the detail classes

4. Testing the entity beans' methods with the IDE's test application facility

From each entity bean, you automatically generate a test client that, when viewed in a web browser, allows you to create an instance of the bean and then exercise the business methods on the instance.

5. Creating the session bean

You use the EJB Builder to create a stateless session bean. You program the bean's create method to perform a lookup on the entity beans and its getter methods to construct collections of detail objects (from the detail classes for each entity bean. You create a method that creates customer review record in the database. You also create two dummy business methods required by the SOAP runtime.

6. Testing the session bean's methods

Before testing the session bean, you add references to the CMP entity beans to the EJB module's property sheet. From the session bean, you then generate a test application, which includes an EJB module. To this module, you add the EJB modules from the entity beans' test applications. Then you use the test client to create an instance of the session bean and then exercise its methods.

---

Note - Before you can begin work on the tutorial application, you must first have performed all the setup steps described in .

---

---

Creating Entity Beans With the EJB Builder

Create two entity beans, Restaurant and Customerreview, to represent the two database tables you created in .

In version 2.0 of the EJB architecture, entity beans can have local interfaces, remote interfaces, or both. The criterion for deciding which to use rests on whether the client that calls the bean's methods is remote or local to the bean. In this tutorial, you create the entity beans with both remote and local interfaces, for flexibility regarding how the web service will access the beans' methods. Two possibilities are the session bean accesses the beans' methods (using local interfaces), or the web service accesses the methods directly (using remote interfaces).

---

Tip - For more details about working with the EJB Builder, see the Sun ONE Studio 5 help topics on EJB components.

---

---

Note - The source code for the completed entity beans is provided in Appendix A.

---

Creating the Restaurant and Customerreview Entity Beans

First, create a directory to contain the application, then mount the directory in the IDE. Mounting a directory puts it in the IDE's class path. Next, in the mounted directory, create a database schema from the two database tables. Finally, create a package for the EJB tier and create two entity beans in it that are modeled from the database schema.

Creating the Tutorial's Directory

Create a directory to contain the tutorial's files and mount it in the IDE's file system, as follows:

1. Somewhere on your file system, create a directory and name it DiningGuide.

---

Note - If you create this as a subdirectory of another directory, the specifications of some methods you create for this tutorial, which include the file specification, may become very long. This may cause execution problems for platforms using Microsoft Windows 2000 with a Service Pack number less than 3. To avoid this, create this directory at the top level of a disk or volume (for example c:\DiningGuide).

---

2. Mount the DiningGuide directory.

Mounting an object in the Explorer puts that object into the IDE's class path.

a. In the Sun ONE Studio 5 IDE, choose the File Mount Filesystem.

The New wizard is displayed.

b. Select Local Directory, and click Next.

The Select Directory page of the New wizard is displayed.

c. Use the Look In file finder to find the DiningGuide directory, select it, and click Finish.

The new directory (for example, c:\DiningGuide) is mounted in the Explorer.

Creating a Database Schema for the Tutorial's Tables

Now create a database schema that models the Restaurant and Customerreview database tables. The IDE reads table definitions from the database and creates the schema.

1. Start the PointBase server by choosing Tools PointBase Network Server Start Server.

If the Start Server command is dimmed, the server is already running.

2. Open a connection to the PointBase sample database.

a. Select the Runtime tab of the Explorer.

b. Expand the Databases node.

• If there is a square icon labeled jdbc:pointbase:server://localhost:9092/sample [PBPUBLIC on PBPUBLIC] and it is whole, skip to Step 3.
• If there is a square icon, as above, and it is broken, right-click it and choose Connect.

The broken square icon redisplays as a whole square when the connection is opened.

---

Note - If there is no square icon, your IDE and application server were installed separately from each other and the PointBase JDBC driver has not been enabled in the IDE; consult the Sun ONE Studio 5, Mobile Edition Getting Started Guide for instructions on connecting an external PointBase database to the IDE.

---

3. Begin creating the schema.

a. Right-click the DiningGuide node in the Explorer and choose New All Templates.

The New Wizard is displayed, showing the Choose Template page.

b. Expand the Databases node, select Database Schema, and click Next.

The New Object Name page of the New wizard is displayed.

4. Type dgSchema in the Name field and click Next.

The Database Connection page of the wizard is displayed.

5. Specify the source database for the schema.

a. Enable the Existing Connection option.

b. Select from the list jdbc:pointbase:server://localhost:9092/sample [PBPUBLIC on PBPUBLIC].

c. Click Next.

The Tables and Views page is displayed.

6. Select the table to be modeled in the schema.

a. Select the CUSTOMERREVIEW table in the list of available tables and click the Add button.

b. Select the RESTAURANT table in the list and click the Add button.

The CUSTOMERREVIEW and RESTAURANT tables appear in the list of selected tables and views.

c. Click Finish.

The new database schema appears under the DiningGuide directory in the Explorer. If you expand all its subnodes, it looks like this:

 

Creating a Java Package for the EJB Tier

Create a Java package within the mounted DiningGuide node to hold the EJB tier, which is the data of your application.

1. Right-click the DiningGuide node and choose New Java Package.

2. Name the new package Data and click Finish.

The new Data package appears under the DiningGuide directory.

Creating the Restaurant Entity Bean

Create an entity bean to model the Restaurant table, as follows:

1. Begin creating the Restaurant entity bean.

a. Right-click the new Data package and choose New All Templates.

b. From the Templates wizard, expand the J2EE node, select CMP Entity EJB and click Next.

The CMP Entity Bean Name and Properties page of the New wizard (used by the EJB Builder module) is displayed. If you click the Help button on any page of the wizard, you can get context-sensitive help on creating CMP entity beans.

c. Name the new CMP entity bean Restaurant and select the following options:

Option Category	Option to Select
Source for Entities and Fields	Table from Database Schema Object
Component Interfaces	Both Remote and Local Interfaces

The New wizard looks like this.

 

d. Click Next.

This displays the Table from Database Schema Object page.

2. Specify the RESTAURANT schema.

a. Expand the DiningGuide node and the nodes under the dgSchema node, and select the RESTAURANT table.

The page looks like this:

 

b. Click Next to go to the CMP Fields page.

3. Customize any fields you wish to define the CMP bean.

You see a side-by-side display of the columns of the Restaurant database table and the corresponding Java fields that the columns will be mapped to when the wizard creates the Restaurant entity bean. For this tutorial, you want to change the type of the rating field.

a. Select the rating field and click the Edit button.

The Edit Persistent Field dialog box is displayed.

b. Delete the existing text in the Type field and type int.

The dialog box looks like this:

 

c. Click OK to close the dialog box.

The type of the rating Java field is changed to int.

d. Click Next.

The CMP Entity Bean Class Files page is displayed, listing the parts of the Restaurant bean that will be created. Notice that the EJB Builder wizard has automatically named the new entity bean with the same name as the database table.

4. Finish creating the bean by clicking Finish.

The new Restaurant entity bean and all its parts are created and displayed in the Explorer window.

 

Five of the parts are interfaces and one part is the bean class. The sixth part is the logical node that groups all the elements of the enterprise bean together and facilitates working with them.

Creating the Customerreview Entity Bean

Create the Customerreview entity bean as you did the Restaurant bean, using the following steps:

1. Begin creating the Customerreview entity bean.

a. Right-click the new Data package and choose New CMP Entity EJB.

Notice that this item appears in the contextual menu. This shortcut is created for your convenience whenever you select an item from the New menu.

b. Name the new CMP bean Customerreview and select the following options:

Option Category	Option to Select
Source for Entities and Fields	Table from Database Schema Object
Component Interfaces	Both Remote and Local Interfaces

c. Click Next.

This displays the Table from Database Schema Object page.

2. Specify the CUSTOMERREVIEW schema.

a. Expand the DiningGuide node and all the nodes under the dgSchema node.

b. Select the CUSTOMERREVIEW table.

c. Click Next.

3. Finish creating the bean.

a. Click Next on the CMP Fields page.

b. Click Finish on the last page (CMP Entity Bean Class Files page).

The Customerreview entity bean is displayed in the Data package in the Explorer. Notice that there is also a primary key class named CustomerreviewKey. This class is automatically created when the entity bean has a composite primary key. (See in to confirm the composite primary key in this table.)

 

Creating Create Methods for CMP Entity Beans

Create the create methods for both entity beans, adding parameters and code to initialize the fields of the beans' instances.

Creating the Restaurant Bean's Create Method

Create the create method for the Restaurant entity bean as follows:

1. In the Explorer, right-click the Restaurant(EJB) logical node (the bean icon ).

2. Choose Add Create Method from the contextual menu.

The Add New Create Method dialog box is displayed.

3. Add method parameters for each column of the Restaurant database.

a. Click the Add button in the Parameters section.

The Enter Method Parameter dialog box is displayed.

b. Type restaurantname for the Field Name.

c. Select java.lang.String for the Type.

d. Click OK (or press Enter) to create the parameter and close the dialog box.

e. Similarly, create the other parameters:

Field Name	Type
cuisine	java.lang.String
neighborhood	java.lang.String
address	java.lang.String
phone	java.lang.String
description	java.lang.String
rating	int

---

Note - The order in which you create these parameters becomes important when you test the bean with the test application facility. Create them in the order given here.

---

Keep the two exceptions created by default, and make sure the method is added to both Home and Local Home interfaces.

4. Click OK.

The IDE propagates a create method under the RestaurantHome interface, another create method under the LocalRestaurantHome interface, and an ejbCreate method under the Restaurant bean class (RestaurantBean). A related ejbPostCreate method is also added to the bean class.

5. Expand the Restaurant(EJB) logical node and the Create Methods folder, and double-click the create method.

The Source Editor is displayed with the cursor at the ejbCreate method of the bean.

---

Note - If you right-click the create method node and choose Help, you can get online help information on create methods.

---

6. Add the following code (the bold text only) to the body of the ejbCreate method to initialize the fields of the bean instance: