J2EE^TM Developer's Guide
Entity Beans

A Container-Managed Persistence Example

The entity bean discussed in this section represents a product. The source code files for this entity bean reside in the doc/guides/ejb/examples/product directory:

Entity Bean Class (ProductEJB.java)
Home Interface (ProductHome.java)
Remote Interface (Product.java)
A client class (ProductClient.java)

The code in the home and remote interfaces is the same whether or not an entity bean uses container-managed persistence. However, the code in the entity bean class is different for container-managed and bean-managed persistence. With container-managed persistence, the entity bean class contains no database access code. The Application Deployment Tool generates the SQL statements needed by the entity bean class. In order to generate the SQL statements, the tool needs to know which instance variables must be stored in the database. These instance variables are called container-managed fields.

Container-Managed Fields

The ProductEJB class has the following container-managed fields:

public String productId;
public String description;
public double price;

These fields represent the state of an ProductEJB instance. You specify the container-managed fields with the Application Deployment Tool (either in the New Enterprise Bean Wizard or on the Entity tab). A container-managed field must be one of the following types:

Java serializable class
Java primitive
Reference of a home interface
Reference of a remote interface

A container-managed field must be public and may not be defined as transient.

Using the Application Deployment tool, you define one (or more) of the container-managed fields as the primary key field (or fields) of the entity bean. For more information, see the section, Primary Key Class on page 66.

Entity Bean Class

The ProductEJB class relies on container-managed persistence. Because it contains no database access routines, the ProductEJB class is quite brief.

The ejbCreate Method

The ejbCreate method initializes the container-managed fields from the input parameters. The method returns null because with container-managed persistence the container ignores its return value. After the ejbCreate method executes, the container inserts the container-manged fields into the database. Here is the ejbCreate method of the ProductEJB class:

public String ejbCreate(String productId, String description,
      double price) throws CreateException {

      if (productId == null) {
         throw new CreateException("The productId is required.");
      }

      this.productId = productId;
      this.description = description;
      this.price = price;

      return null;
}

The ejbRemove Method

When the client invokes the remove method, the container calls the ejbRemove method. After the ejbRemove method returns, the container deletes the row from the database. If the container fails to delete the row, it throws an exception.

If an entity bean needs to perform some operation immediately before removal, it should do so in the ejbRemove method. Because the ProductEJB class does not have to perform such an operation, its ejbRemove method is empty.

The ejbLoad Method

When the container needs to refresh the entity bean's state from the database, it performs these steps:

Selects the row from the database
Assigns the row's column values to the container-manged fields
Invokes the ejbLoad method

Usually, the ejbLoad method is empty. The entity bean may use the ejbLoad method, however, to transform the values read from the database. For example, the ejbLoad method might uncompress text data so that it can be manipulated by the business methods.

The ejbStore Method

When the container needs to save the entity bean's state in the database, it performs these steps:

Invokes the ejbStore method
Gets the values of the container-managed fields
Updates the row in the database with the values of the container-managed fields

Like the ejbLoad method, the ejbStore method is typically empty. But if you need to transform container-managed fields before the container stores them in the database, you should do so in the ejbStore method. For example, the ejbStore method might compress text data before the container stores it in the database.

The Finder Methods

The ProductHome interface defines the following finder methods:

public Product findByPrimaryKey(String productId) 
   throws FinderException, RemoteException;

public Collection findByDescription(String description)
   throws FinderException, RemoteException;

public Collection findInRange(double low, double high)
   throws FinderException, RemoteException;

Because the ProductEJB class uses container-managed persistence, it does not implement these finder methods. The Application Deployment tool implements the findByPrimaryKey method, including the SQL select statement that retrieves the row from the database. The tool also implements the customized finder methods (findByDescription and findInRange), but you must specify the where clauses for their select statements. For instructions on specifying the where clause, see the section, Specifying the Deployment Settings on page 63.

Table Creation

The Application Deployment Tool generates the SQL create table statement for an entity bean with container-managed persistence. For example, the tool generates the following statement for the ProductEJB class:

CREATE TABLE "ProductEJBTable"  (
"description" VARCHAR(255) , 
"price" DOUBLE PRECISION NOT NULL , 
"productId" VARCHAR(255), 
CONSTRAINT "pk_ProductEJBTable" PRIMARY KEY ("productId") )

Note: The double quotes are part of the table, column, and constraint names. In the preceding SQL statement, the table name is "ProductEJBTable"-- not ProductEJBTable.

By default, the EJB container executes the create table statement when you deploy the application containing the entity bean. (Also by default, it drops the table when you uninstall the application.) If you do not want the container to create the table during deployment, follow these steps:

1. In the Application Deployment Tool, select the Entity tab of the entity bean.

2. In the Entity tabbed pane, click Deployment Settings.

3. In the Deployment Settings dialog box, de-select the checkbox for "Create Table on Deploy."

Tips on Running the ProductEJB Example

Setting Up the Database

1. At the command-line prompt, run the Cloudscape database server:

cloudscape -start

2. Do not create the database table. The EJB container will create the table automatically.

Running the New Enterprise Bean Wizard

The material in this section highlights the wizard steps that are unique to an entity bean with container-managed persistence, such as ProductEJB.

General Dialog Box:

a. Select the Entity radio button.

b. In the Display Name field, enter ProductBean.

Entity Settings Dialog Box:

a. Select the radio button labelled "Container-Managed Persistence."

b. Select the check boxes for these container-managed fields: productId, description, and price.

c. In the Primary Key Class field, enter java.lang.String.

d. In the Primary Key Field Name field, select productId.

Transaction Management Dialog Box:

For the business methods, in the Transaction Type column select Required. (The business methods are getDescription, getPrice, and setPrice.)

Specifying the Deployment Settings

1. In the Application Deployment Tool, select the Entity tabbed pane for the ProductBean.

2. In the Entity tabbed pane, click Deployment Settings.

3. In the Database JNDI Name field, enter jdbc/Cloudscape.

4. Verify that the checkbox is selected for "Create Table on Deploy."

5. Click Generate SQL Now.

6. A window pops open to inform you that the SQL statements have been generated for the Cloudscape database. Click OK.

7. A window pops open to inform you that you need to provide the SQL where clause for the findByDescription and findInRange methods. Click OK.

8. In the EJB method list, select findByDescription. A partial select statement appears.

9. Add the following where clause to the select statement:

WHERE "description" = ?1

Note: You must include the quotes in the "description" column name. The ?1 represents the first parameter of the finder method.

10. In the EJB method list, select findInRange. A partial select statement appears.

11. Add the following where clause to the select statement:

WHERE "price" BETWEEN ?1 AND ?2

Note: You must include the quotes in the "price" column name. The ?1 and ?2 represent the first and second parameters of the finder method.

12. Click OK.

Deploying the J2EE Application

1. Click the radio button labelled "Return Client Jar."

2. In the second dialog box, for the ProductBean enter MyProduct in the JNDI Name field.

Prev | Next

TOC | Index