CMP 2.0 Bean Example

by Beth Stearns

CMP Example Overview

The CMP 2.0 example models an application that maintains customers, addresses, and customer publication subscriptions in a database. Customers may have multiple addresses and may subscribe to multiple publications. Publications are classified according to type: magazines, newspapers, journals, and so forth.

You can find the example application files beneath the /j2ee directory in which you've installed the release. The .ear file for the application, cmpcustomer.ear, and it is found in the directory:

../j2ee/doc/samples/cmpcustomer.ear

The directory ../j2ee/doc/samples/customer contains the Java source files for the different entity beans, while the directory ../j2ee/doc/samples/contentRoot contains the JSP files for the application.

The example application appears in the deploytool within the Applications folder. It is called CMPCustomerApp. If you expand CMPCustomerApp, you'll see it has a web section and an Ejb1 section. Expand the web section to see the JSPs defined for this application. Expand Ejb1 to see the application' s three entity beans.

The example uses three entity beans: a Customer bean, an Address bean, and a Subscription bean. Each customer is represented by an instance of the Customer bean. Each customer may have one or more addresses, and each address is represented by an instance of an Address bean and associated to the particular customer. The relationship between customers and addresses is a one-to-many, uni-directional aggregation. You may add and delete individual addresses for a customer, but, because an address instance must be associated to a customer, when you delete a customer, you are also automatically deleting all addresses associated to that customer. The example illustrates the architecture's cascade delete functionality because it automatically ensures that all address instances associated with a customer instance are deleted when the customer instance is removed.

There is also a many-to-many, bi-directional association between the Customer bean and the Subscription bean. A customer may have zero or more subscriptions, where each Subscription instance represents a different publication. Similarly, a single Subscription instance may be associated to many customers.

Lastly, each subscription instance has an attribute, subscription type, indicating its type, such as magazine or journal. When you create a new subscription, you designate its type. The subscription type is a separate class, SubscriptionType, and is considered a dependent value class. It is not an enterprise bean. The Subscription bean references it as a container-managed persistent field.

Defining the CMP Relationships

The deployment descriptor contains the enterprise bean relationship definitions. The CMP 2.0 example has already been set up with a deployment descriptor, which is contained in the .ear file. When you open the example in the deploytool, the tool shows you all of the relationship mappings, container-managed persistent fields, and so forth. It is not necessary for you to add or change any of these associations. However, if you were writing your own application, you use the deploytool screens to designate the cmp fields and bean relationships. It is important that you follow what has been done in the enterprise bean code when you make these designations. That is, the deploytool mappings must mirror the code. Otherwise, your application may not run properly.

Here, we describe how you define relationships in the code and then show you how to set up these same relationships using the deploytool.

Defining Many-to-Many Relationships

The Customer bean to Subscription bean is a good example of defining a many-to-many relationship. The Customer bean has a many-to-many bi-directional relationship to Subscriptions. Thus, the Customer bean includes two methods: one to return all subscriptions associated to a single customer and the other to update a customer's subscriptions:

public abstract Collection getSubscriptions(); 
public abstract void setSubscriptions (Collection subscriptions);

The Subscription bean includes equivalent methods to retrieve and set all customers associated to a particular subscription instance:

public abstract Collection getCustomers();
public abstract void setCustomers(Collection customers); 

Define this relationship in the deploytool as follows:

  1. Highlight the Ejb1 JAR file. (This JAR file appears beneath CMPCustomerApp.)
  2. Select the Relationships tab.
  3. Highlight the Customer bean to Subscription bean relationship.
  4. Select Edit to bring up the Edit Relationship screen.
  5. From the Multiplicity pull-down menu, select Many to Many.
  6. For Enterprise Bean A, select CustomerBean.
  7. For its Field Referencing Bean B, choose subscriptions from the list of fields.
  8. For Enterprise Bean B, select SubscriptionBean from the list of beans.
  9. For its Field Referencing Bean A, choose customers .
  10. Select OK to complete the relationship set up.

Defining One-to-Many Relationships

In the code, a local bean object represents the single side of a one-to-many relationship. A Java Collection of local objects represents the many side. For example, the CustomerBean defines the method getAddresses to retrieve all the addresses for one customer and the method setAddresses to set all addresses:

public abstract Collection getAddresses();
public abstract void setAddresses (Collection addresses);

Because the Customer to Address relationship is only in one direction, the Address bean does not define a method to get an address instance's associated customer.

Set up the one-to-many relationship between the Customer bean and the Address bean in the deploytool as follows.

  1. Highlight the Ejb1 JAR file. (This JAR file appears beneath CMPCustomerApp.)
  2. Select the Relationships tab.
  3. Highlight the Customer bean to Address bean relationship.
  4. Select Edit to bring up the Edit Relationship screen.
  5. From the Multiplicity pull-down menu, select One to Many.
  6. For Enterprise Bean A, select CustomerBean.
  7. For its Field Referencing Bean B, choose addresses from the pull-down menu.
  8. For Enterprise Bean B, select AddressBean from the list of beans.
  9. For its Field Referencing Bean A, choose none (because AddressBean does not contain any references to the Customer bean).
  10. Select OK to complete the relationship set up.

Setting the Cascade Delete Functionality

Set cascade delete functionality from the same Customer to Address Edit Relationship screen. Notice that the box to Delete When Bean A is checked for AddressBean in the Customer to Address bean Edit Relationship screen. When this box is checked and the application deletes an instance of a Customer bean, the container ensures that all instances of the Address bean that are associated to the deleted Customer object are also deleted.

Setting CMP Fields

The deployment descriptor must correctly indicate the cmp fields for the entity beans using container-managed persistence.

For example, the CustomerBean uses container-managed persistence (2.0). It uses container-manager persistence for three of its five fields: customerID , firstName , and lastName . These checked fields correspond to the cmp fields for which the CustomerBean provides get and set methods.

	
public abstract String getCustomerID();
public abstract void setCustomerID(String id);	
public abstract String getFirstName(); 
public abstract void setFirstName(String firstName);
public abstract String getLastName();
public abstract void setLastName(String lastName);

Do the following in the deploytool to set the cmp fields.

  1. Select the CustomerBean entity bean (listed beneath the Ejb1 JAR file).
  2. Select the Entity tab.
  3. Check the type of persistence management for the bean. CustomerBean uses container-managed persistence (2.0).
  4. Check the three CustomerBean fields ( customerID , firstName , and lastName ) to be persisted.

Running the Sample Application

Before you can run the sample application, be sure that the application has been deployed and that the enterprise bean SQL code has been generated. Use the deploytool's Deploy function (available from the Tools menu) to deploy the application.

To generate the SQL:

  1. Select Ejb1 beneath the CMPCustomerApp application.
  2. Select the General tab.
  3. Select Deployment Settings.
  4. From the Deployment Settings screen, select Generate SQL Now. This operation generates the SQL statements.

You may now run the application. From a browser window, enter the following location:

http://localhost:8000/customer

This starts the application and opens its main window. From this window, you can create new customers and subscriptions, search for existing customers and subscriptions, and search for addresses. When you add a new customer, you have the option to add addresses for that customer. Notice, too, that when you delete a particular customer, you also delete all addresses associated to that customer.