Step-By-Step EJB 2.0 CMP/CMR Development

Jun. 12, 2003 12:00 AM

The EJB 2.0 specification enhances the Enterprise JavaBeans paradigm in many ways. The entire concept of the container-managed persistence (CMP) component model has been redefined for better performance and flexibility. To make your work a lot easier, IBM quickly introduced WebSphere Application Developer (WSAD) 5.0, which supports both the EJB 1.1 and 2.0 specifications. In this article we will discuss some important concepts that will provide you a good basis for working with the new specification.

CMP Component Model
Persistence service, usually provided by the container, has been redesigned with an entirely new CMP component model. Unlike with the EJB 1.1 container, EJB 2.0 persistence is handled by a new entity called the "persistence manager." This makes the persistence mechanism independent of the container provider, thus making CMP entity beans portable to any EJB 2.0-complaint container, irrespective of the vendor and back-end relational databases. The persistence manager also handles the relationships among all of the CMP entity beans as well. To make this work, the CMP entity beans are introduced with abstract class qualifiers and all the persistence and relationship fields are accessed using abstract getters and setters, which is known as "abstract persistence schema," for example:

public abstract Customer implements javax.ejb.EntityBean{
//
public abstract void setPhone(){}
public abstract String getPhone(){}
//
}

During deployment, the persistence manager uses the persistence information in the EJB deployment descriptor (DD), the bean's persistence schema, to generate concrete bean classes, which are instantiated at runtime.

Local Interface vs Remote Interface
EJB 2.0 introduces local interfaces, which either coexist with the remote interface or exist alone. Prior to creating EJBs it is wise to decide on the design aspects of an entity EJB. The introduction of local interfaces has improved performance, but it makes the job of the designers more challenging since they need to decide whether to use only a local interface or both a local and remote interface. If an EJB has only a local interface, then clients within the same JVM can access the EJB, but remote clients will not see it. On the one hand this is good, since you are adding pseudo-security by not allowing outside clients to access your EJB. But remember that for a distributed Web application or Web service where you are allowing clients outside the JVM to access the EJB, you need to add remote interfaces. WSAD 5.0 gives you the option of adding local and remote interfaces to your EJB (see Figure 1). So if you want to test your EJBs using a simple Java client, make sure to add the remote interface to your EJBs or you won't be able to work with them.

Container-Managed Relationships
Container-managed relationships (known as CMR) are now standardized in the EJB 2.0 specification. WSAD lets you create relationships between the CMP entity beans. It supports all three types of relationships between data: one-to-one, one-to-many, and many-to-many.

To clarify the entity relationships, we will exercise the steps to create two entities using WSAD and to create a one-to-many relationship between the Customer and Order CMP entity beans. For our example we used DB2 7.2 Fixpack1 as our relational database. Before we start, we want to choose the approach for mapping our entities to the respective tables. There are three standard approaches in creating and persisting field mapping: Bottom Up, Top Down, and Meet in the Middle.

You would use the Bottom Up approach for creating entities that represent an existing relational database. In this case you could use the WSAD wizard to magically create all the entities and their relationships. With the Top Down approach you would create the entities using the Create Enterprise Beans wizard and then you would create the EJB-to-RDB mapping. You could ask WSAD to generate the data definition language file for the tables, which will be used as a persistence store by the beans. On the other hand, the Meet in the Middle approach is used for handshaking between already created database tables and entity beans.

Create Two CMP Entity EJBs

Create a J2EE 1.3 Enterprise Application project "OnlineStore" with the EJB module "OnlineStoreEJB". Make sure to uncheck the Application Client and Web Modules check boxes. We don't need them for our example.

Create the entity EJBs: from the context menu select File->New->Enterprise Bean->. This will take you to the EJB Creation wizard.

On the first page, select the "OnlineStoreEJB" EJB Module from the list and select Next.

On the Create a 2.0 Enterprise Bean page, select CMP 2.0 Bean. Provide Customer as the bean name (the first letter of the bean name should be in caps, by convention). Set com.store.ejb as the Default Package and select Next.

On this Enterprise Bean detail page make sure to select Local Client View and deselect Remote Client View (see Figure 1).

Now we need to add persistence fields to the bean. We will add three CMP attributes to the Customer bean: cust_id as type Java String (also the Primary Key Field); fname, also as a Java String; and lname, as a Java String. Add these attributes in the CMP Attributes text area. Click Finish. This will create the abstract Customer bean class and the two local interfaces.

Follow the same steps to create the Order entity. For order, add the CMP attributes order_id (Java String and Primary Key Field); date (sql date); amount (double), desc ( Java String).

Create a One-to-Many Relationship

Open the DD Editor on the Overview tab, and find the group name "Relationships 2.0".

Click on the Add button under the Relationships heading to open the Add Relationship wizard.

On the first screen you can see all of your entity beans on both sides. Select one bean from the left side (Customer) and another bean from the right (Order). The name for the relationship "Customer-Order" is automatically set. Click Next.

WSAD assigns relationship roles for your beans. In the Relationship Roles page, under the Customer bean, set a role named "orders". Multiplicity should be set to One. For the Order bean, set the multiplicity to Many. You'll see that the field type under Customer is now java.util.Collection. You should check the Cascade Delete check box under Order to ensure that all orders are deleted if a customer is deleted. Now set the navigable check box on both sides as checked. You'll also see that the Foreign Key check box is checked but disabled. This is because for a one-to-many relationship a foreign key is mandatory. Click Finish. This will append the getOrders() and setOrders (Collection) methods to the Customer bean and promote these methods to the CustomerLocal Interface. Also in the OrderBean class and the OrderLocal interface you can see two generated methods named getCustomer and setCustomer (CustomerLocal). Save the DD. Note: Notice that the CMR relationships generated methods only for the local interfaces. You have to code your own methods to add this in the Remote interface.

Create the EJB-to-RDB Mappings
Once the relationships are generated we need to map the relationships to the database side.

Switch to the J2EE perspective and select the J2EE hierarchy tab.

Right-click on the EJB module. Select Generate->EJB to RDB mapping. This will open the EJB to RDB Mapping wizard.

On the first page select "Create a new backend folder" and click Next.

"Create new EJB/RDB Mapping" will give you two options for creating the mapping: Top Down and Meet in the Middle. (An explanation of each is given on that page.) In our case we will be creating the mapping as Top Down. So select Top Down and click Next.

On this page provide the database vendor, database name, and schema name. In our example they will be DB2 UDB 7.2, onlinest, and administrator respectively. Make sure to create the onlinest database separately in your DB2 installation. Also, make sure that you have selected the "Generate DDL" check box, and click Finish. This will create the mapping and WSAD will open the mapping editor (Map.mapxmi) automatically for you (see Figure 2). Note: We noticed one limitation in the WSAD-generated DDL. The foreign key relationship definition is not generated. Make sure you manually add the foreign key constraint into the database tables created by the DDL.

Select table.ddl from the J2EE navigator panel under META-INF and right-click Run on Database Server. Make sure to create a new connection, "onlinest", which connects to the onlinest database.

Configure the WebSphere Test Environment

Switch to the Server perspective. Under the Server Configuration Panel, right-click on Servers and select New->Select Server and Server Configuration. This will open the New Server configuration wizard.

Provide a server name, "onlinestore", and click Finish. This will create a new WebSphere test server, where we will test our EJBs. WSAD will automatically open the WebSphere Server Configuration editor.

In the editor switch to the Datasource tab. From the JDBC Provider list select Default DB2 JDBC Provider and click Edit.

On the Edit page, you need to provide the path of the db2java. zip file on your file system. Remove the default entry and add the actual db2java.zip by clicking the Add External JARs button. Then click Finish to return to the editor.

Now we need to add a datasource to the onlinest database using the driver we just configured. So click Add under Data Source. In the Datasource wizard click Next to skip the first page by accepting the default values. On the second page you should notice that by default WSAD generated a JNDI name for the datasource; you can accept the default or enter your own JNDI name. We will accept the default, jdbc/ds1 (because this is the first datasource). Click next. Remember this datasource name. We will need this later.

On the Modify Resource Properties page we need to specify the database name. Provide the database name as the value of databaseName property. Click Finish. Save the server configuration.

Now go back to the DD page or open it. On the Overview tab, scroll all the way to the bottom. Under JNDI-CMP Factory Connection Binding, JNDI name, specify the datasource JNDI name we just created (jdbc/ds1). Save the DD.

Now that we have created two entities and established a relationship between them, we are ready to test our EJBs and their relationships. The EJB test client WSAD provides is not the best tool to test the relationships, since each method call from the test client is a transaction. So when you invoke getOrders() in Customer, it returns a Collection object that gets invalidated as soon the transaction ends and when you try to work with the Collection object, you will encounter an llegalStateException for the object. We encourage you to test your entity beans using a session facade to access them. Let's build a quick session facade for the Customer entity bean using its local interface.

Create a Session Facade as the Entity Client
Create a Customer Facade stateless session bean, CMRTester, using the Create Enterprise Bean wizard. After WSAD creates the bean skeleton, open the session bean class and add a method called doTesting(). Add the code shown in Listing 1 to access the Customer bean. Save the bean. Switch/Open EJB Deployment Descriptor. Now we need to create a local Customer reference under the session bean, so that the session bean can look up the localhome interface for the Customer entity. Open DD, click on the References tab, select the session bean, and click Add. Select EJB Local Reference. In the EJB Local Reference page, under Link, click Browse to select the Customer bean under Current Enterprise Project. This action will create a local reference (ejb/Customer) of the customer bean under the session bean.

Test the Entity Beans Using the EJB Test Client
Switch to the J2EE perspective and select the J2EE Hierarchy tab. Expand EJB Modules. Expand the OnlineStoreEJB module. Right-click the CMRTester session bean and select Run On Server. You will be given the option to run the bean on an existing server. The created server will automatically be selected. Click Next. On the second page make sure that the Deploy EJB Beans check box is selected. This will generate the RMIC code and the concrete implementation of the abstract bean class, which we discussed earlier. You could also generate the class by right-clicking the EJB module and selecting Generate ->Deploy and RMIC code... This will generate the classes necessary to run the beans on the test server. This action will also publish the EJBs to the test server. After successful startup of the server, the EJB Test Client will automatically start up. Now you can test your EJBs using the test client. Add some data to the tables to test.

March Ahead...
Thus far we've passed on some insights into the new enhancements in the EJB 2.0 specification. You can see that the abstract persistence schema is the basis of the new persistence mechanism and relationships. The specification also introduces message-driven beans and defines a query language, known as EJB-QL, to define the finder and select methods in the CMP entity EJBs. This specification surely comes with lot of promises that require more exploration. We hope you are now more enthusiastic about exploring in-depth. Happy EJBing.

Acknowledgment
The authors would like to thank Ashim Ranjitkar, Raju Mukherjee, and Soutik Singha for their contributions to this article.

Related Links

▪ Figure 1

▪ Figure 2

▪ Source Code

About Swaraj Pal