Developing Sets of Related CMP Entity Beans

Many J2EE applications contain related entity beans that use container-managed persistence (CMP entity beans). That is, two CMP entity beans in an application might contain a bean-to-bean relationship field, representing the way different entities or tables in a database or a database schema might contain a related column. For example, a schema might include the tables Customer, Order, LineItem, and Part. The Order table has a foreign key to the Customer table, LineItem has a foreign key to Order, and LineItem also has a foreign key to Part.

This chapter describes how to use the EJB Builder in the Sun ONE Studio 5 IDE to create a set of related CMP entity beans all at once, along with the necessary interfaces. You can generate CMP entity beans from all entities in a database or schema model, or you can select a subset of the entities. The wizard automatically places the generated beans in an EJB module (see Chapter 8 for more information on modules).

The wizard also considers any relationships between the entities in the data source and preserves the relationships in the resulting CMP entity beans as logical entities called CMR fields. In fact, the IDE does not allow you to accidentally overlook a relationship between two database tables.

The wizard automates or prompts you for all the tasks involved in creating the infrastructure of a set of related CMP entity beans.

When programming a set of related CMP entity beans, you have many options in addition to those described in this chapter. For more information, refer to the resources listed in Before You Read This Book, or to one of the many excellent texts on programming enterprise beans.

---

Using the EJB Builder With Sets of Related CMP Entity Beans

The EJB Builder is a collection of wizards, property sheets, and editors with which you can build enterprise beans consistently and easily. You get the most comprehensive support and, in general, the fastest path to bean completion, if you use the EJB Builder's wizards and the approach recommended in this chapter. The methodology described here takes full advantage of the IDE's ability to ensure consistency and its adherence to the J2EE standard.

Creating All Related CMP Entity Beans at Once

For best results, use the EJB Builder to program CMP entity beans by:

• Creating a set of CMP entity beans and their required classes. After using the EJB Builder wizard, you have the framework of your set of related CMP entity beans. Each bean, with its necessary class, interfaces, and a logical node, is shown in the Explorer's Filesystems tab. The wizard generates declarations for the interfaces. Each CMP entity bean's generated bean class contains declarations of required methods, as well as persistent fields matching the columns in the data source.

The wizard prompts you to either include or explicitly exclude related beans. This way, you can't miss seeing a bean-to-bean relationship.

The logical node is the best place from which to work with an entity bean. All logical nodes appear in the Explorer with this icon:

• Adding methods, parameters, and exceptions. Use the IDE's GUI support as described later in this chapter. You can work partly in the GUI and partly in the Source Editor to complete each CMP entity bean's method implementations. For example, you can add a method to a bean by using a dialog box available from the contextual menu or by directly editing the set of required classes.
• Setting values in a bean's deployment descriptor. Use the entity bean's property sheet, available at the logical node, to edit properties for deployment purposes.

Creating a Set of Related CMP Entity Beans One at a Time

If you wanted to, you could build a set of related CMP entity beans by hand, generating the beans individually, adding them to an EJB module, and using the module's property sheets to declare the relationships (CMRs) between beans. However, the EJB Builder wizard does this work for you automatically, and any relationships between beans are more likely to be complete and accurate if you use the wizard.

If you can't take advantage of the EJB container's persistence management, and you must create a set of entity beans that manage their own persistence (BMP entity beans), then you must manually code all relationships between the beans. See TABLE 4-1 for the differences between CMP and BMP entity beans; see Chapter 6 for details on creating BMP entity beans.

The rest of this chapter addresses how to create a set of related CMP entity beans all at once, using the wizard, and issues to consider during development.

---

Defining a Set of Related CMP Entity Beans

The EJB Builder wizard automates much of the task of creating the components of your set of related CMP entity beans. For each CMP entity bean, the wizard does the following:

• Creates the minimum required classes, which consist of a bean class and the interfaces you choose: local only, or both local and remote
• Creates a primary-key class in the CMP entity bean, if a table you selected requires a composite primary key or uses a simple Java type for the primary key
• Creates relationships between CMP entity beans. These relationships appear as accessor methods that return collections
• Generates an EJB module to hold your set of related CMP entity beans

To define a set of related CMP entity beans, you take the following steps:

1. Select or create a package to contain the beans and the EJB module.

2. Use the EJB Builder wizard to generate an EJB module and the infrastructure of the individual, related CMP entity beans.

3. As appropriate, add create, business, finder, select, and home methods to each CMP entity bean's code.

4. Complete the bodies of the methods you added.

These basic steps are explained in detail next.

Creating a Package

If you need to create a package to house your set of related CMP entity beans, select a filesystem, do as follows:

1. In the IDE's main window, if the Explorer is not already open, choose View Filesystems to open the Explorer window to the Filesystems tab.

2. In the Filesystems tab of the Explorer, select a filesystem, right-click, and choose New All Templates.

The New wizard opens the Choose Template page.

3. Select Java Package and click Next.

The wizard displays the New Object Name page.

4. Type a name for the package and click Finish.

The new Java package appears under your filesystem node.

Preparing to Use a Database or Schema

You need to decide whether to model your set of related CMP entity beans on a database or on a database schema (a snapshot of a database). The EJB Builder wizard maps columns from a table of the database or schema to create the persistent fields in your related CMP entity beans. Both choices provide the same result in your finished entity bean.

When you build a set of related CMP entity beans, the EJB Builder also preserves any relationships between the database tables and carries them over into the CMP entity beans in the set.

Consider the following when deciding which form of data source to use:

• Generating a set of related CMP entity beans from a live database. Assuming that you have direct access to the database itself, and that contention among database users is not a problem, you might want to use the direct database connection to create your set of related CMP entity beans. If so, you must already have the database up and running before you start the EJB Builder wizard.
• Generating a set of related CMP entity beans from a database schema. If database access is restricted but schema objects have been made available, you might want to take a table from a schema. If so, the schema must be available to you from the IDE's Explorer window. If you don't already have a schema, you must capture one from a database.

For details on starting and stopping the PointBase database server that is automatically installed with the IDE, and for details on capturing a database schema, see Having a Data Source Ready.

While you're creating a set of related CMP entity beans, you need access to the database, so the server must be running at least until you finish with the EJB Builder wizard. (Later, when the application that uses the CMP entity beans is being deployed and is executing, the database and application servers must also be running, if you want the plugin to create tables.)

The EJB Builder wizard provides information to the application server plugin about how the original database mapping was derived. If appropriate, the plugin incorporates this information into its default mapping. EJB containers vary in how they treat column-to-field mappings. For details, refer to the documentation for your container and server plugin.

Starting the EJB Builder Wizard

When you're ready to create a set of related CMP entity beans, do as follows:

1. In the IDE's main window, if the Explorer is not already open, choose View Filesystems to open the Explorer window to the Filesystems tab.

2. In the Filesystems tab, select the Java package where you want your related CMP entity beans to reside.

3. Right-click the package and choose New All Templates.

The New wizard displays the Choose Template page.

4. Expand the J2EE node, select Related CMP Entity EJBs, and click Next.

The New wizard displays the Related CMP Entity EJBs page. Notice that the panel on the left shows the current step and the steps you still must complete before your set of related CMP entity beans is created.

Generating the Bean Set's Infrastructure

Before generating the individual beans' infrastructure, the wizard asks you to name a new EJB module that will hold the related CMP entity beans. In the same page, as shown in FIGURE 5-1, the wizard asks where your CMP entity beans will get their persistent fields and relationships.

 FIGURE 5-1 Selections in the EJB Builder Wizard for a CMP Entity Bean Set

[ D ]

To make these basic decisions about your bean set, do as follows in the Specify EJB Module Name and Data Source page:

1. Type a name for the module.

If you have used an EJB Builder wizard to create an individual bean, as described in Chapter 4, you remember that the input field was for the bean's name. However, individual beans in a set of related CMP entity beans are named by the wizard a little later in the generation process. Here, type a name for the module that will enclose your set of related CMP entity beans.

2. Select a database source:

• Select Tables from Database Connection if the CMP entity beans you are creating will represent tables from an existing database. (The database must already be up and running.) See the next section.
• Select Tables from Database Schema Object if you want to use an existing schema. (The schema must have already been created, and it must be in a filesystem to which you have access through the IDE's Explorer.) See Using a Database Schema Object.

3. Click Next.

Using a Database Connection

You should now be in the wizard's Specify the Database Connection page, having selected Tables From Database Connection in the first wizard page.

Make sure the database you're using is running. If you're using a database that is not supplied with the IDE, make sure that the database driver files are in the s1studio-install-directory/lib/ext directory, and start the database server.

In the Specify the Database Connection page, do as follows:

1. Click either Existing Connection or New Connection:

• Select Existing Connection if you want to use an installed or supplied database and the connection is defined but not active. Select a database from the combo box. A login dialog box appears. Type the information required by your database and click OK.
• Select New Connection if you have a database installed but no connection has been defined. Select a database driver from the combo box. A login dialog box appears. Type the information required to connect to your database and click OK.

The tables that you can use to build your set of related CMP entity beans appear in the next wizard page, Select Database Tables.

2. From the Available Tables list on the left, select the tables you want and add them to the Selected Tables list on the right.

If you like, the EJB Builder can preserve all relationships between tables and replicate them in your set of related CMP entity beans.

Or, you can exclude any tables you don't need, which means that any relationships between those tables and the ones you have selected are gone. In the latter case, the EJB Builder treats foreign-key columns and non-foreign-key columns in the same way.

3. Click Next.

A table that you did select might have a foreign key that references a table you didn't select. If this is the case, a warning dialog box appears, listing all the related tables you didn't select. Consider whether any CMP entity bean in your set will ever need access to data in any of those unselected tables.

For example, part of this dialog box is shown next. It contains a list of tables that you did not select in the previous dialog box. Notice that by default all the tables are checked for inclusion.

[ D ] 

(The tables shown in this dialog box are those that are left over from the initial selection list, shown in the previous dialog box, and that are accessible using foreign keys. The set of tables you selected plus the set of tables in this dialog box constitute the entire set of tables that would allow all foreign keys to be included in CMRs.)

If you don't add a particular table to your set of related CMP entity beans now, you can always do it later. However, at that point, you will also have to specify its relationships with other CMP entity beans. If you think you might need the table and your application's performance isn't likely to be affected, the least complicated way is to add it now by leaving its checkbox selected.

4. In the warning dialog box, deselect the checkbox corresponding to any table you do not want represented in your set of related CMP entity beans.

Don't forget to use the scrollbar, if one appears.

When you click OK, all tables that you left selected become CMP entity beans in your set, in addition to any tables you selected explicitly in Step 2.

The Edit CMP Entity EJB Data page appears, showing the EJB module that is about to be created, the CMP entity beans within that module, the EJB module name, and the package name. The interesting part of this page is shown next.

[ D ] 

In this page, if needed, you can select and edit a CMP entity bean, a field, or a container-managed relationship (CMR) between two CMP entity beans. The IDE has assigned default names and types to your beans and their fields, but you can make changes if necessary.

---

Note - This page is here for your convenience. If you want, after finishing with the wizard, you can make the same types of changes using the logical nodes of the set of related CMP entity beans and the EJB module.

---

5. Edit one or more CMP entity beans, if necessary.

Select one of the included bean nodes and notice how the window changes. An example is shown next.

[ D ] 

Notice the icons that identify CMP fields () and container-managed relationships ().

You can make changes in the following places:

• (Optional) In the EJB Name field, rename the selected CMP entity bean.

The EJB Builder wizard propagates the change to the bean class, the appropriate interfaces, and the relationships between the beans.

• (Optional) In the Abstract Schema Name field, rename the selected bean's abstract schema.

As you have been specifying your set of related CMP entity beans, you have also been automatically creating part of the set's deployment descriptor, namely, some declarative instructions to the container for handling your beans' persistence. These particular instructions are called the abstract persistence schema or abstract schema. When you add a finder or select method later (see Adding Finder Methods), the EJB QL queries in the method use the abstract schema name.

If you want, you can assign the schema a different name, but the default, which is the bean name, is recommended.

• (Optional) Use the Component Interfaces radio buttons to specify different interfaces for the selected bean.

Unless you select Both Local and Remote Interfaces, each of the CMP entity beans in your module is automatically given only a local interface and a local home interface. If a CMP entity bean will be used by beans in another container (or, to be more specific, in another JVM), then the bean needs both local and remote interfaces.

6. Edit one or more CMP fields, if necessary.

Select a CMP field and notice how the window changes. An example is shown next.

[ D ] 

If necessary, make changes in the following places:

• (Optional) In the CMP Field Name field, overwrite the default name with another name.

The EJB Builder wizard propagates the change to the bean class and the appropriate interfaces, maintaining any relationship between this and another field.

• (Optional) In the CMP Field Type field, select another type for the field.

7. Edit a relationship between two CMP entity beans, if necessary.

The EJB Builder wizard shows any relationship between two beans as a separate node. This node does not represent an actual object. It's just a logical node, labeled to show that a container-managed relationship (CMR) exists between the bean you've selected and the bean named in the label. This relationship between CMP entity beans is like the relationship between tables with a foreign key.

In the example shown next, the ProductCodeTbl bean has a CMR with the ProductTbl bean, since the corresponding tables have a foreign key in common.

Select a CMR and notice how the window changes. An example is shown next.

[ D ] 

Make any necessary changes in the following places:

• (Optional) In the EJB Relation Name field, change the name that the wizard has assigned to the relationship between the two beans.
• (Optional) In the Role Name field, change the role name.

Notice the two CMP entity beans described in the right side of the page. The role name describes the role of the bean shown in the top of the page as it relates to the bean in the bottom of the page.

• (Optional) In the CMR Field Name field, change the field name.

The wizard has given each bean's CMR field a name that enables the beans to navigate their relationship. A foreign key, for example, might be mapped to this CMR field. A relationship can be unidirectional (that is, the two related CMP entity beans have only one CMR field between them) or bidirectional (the pair have two CMR fields). In the example shown here, the relationship is bidirectional, and so each bean has a differently named CMR field.

A CMR field name becomes an abstract method in the bean class. This abstract method doesn't do any work directly on an entity.

If two CMP entity beans have multiple relationships between them, it's a good idea to add semantic meaning to the CMR field names. Do that here.

• (Optional) Select the Cascade Delete checkbox if, when one bean's relationship record is deleted, you also want the other bean's corresponding record to be deleted.

This decision depends on the semantic meaning of the two beans' relationships. For example, an order might have several related line items. The relationship between an order and a line item should always use Cascade Delete because if the order doesn't exist, neither should any of the line items. However, in peer relationships, deleting the referenced side should not cause the referencing bean to be deleted.

The EJB container handles referential integrity when it uses CMR fields to operate on the relationship between two CMP entity beans.

8. When you are done, click Finish.

The infrastructure of your set of related CMP entity beans (the bean classes, the types of interfaces you specified, and the interbean relationships) is generated automatically by the EJB Builder. See Looking at the Components of a CMP Entity Bean Set for the next step.

Using a Database Schema Object

You should now be in the wizard's Select Database Schema Object page, having selected Tables From Database Schema Object in the first wizard page (see FIGURE 5-1).

If you don't already have a schema, you can use the IDE's Database Schema wizard to create one, as discussed in Capturing a Database Schema. Make sure you can get to the schema through the IDE's Explorer.

In the Select Database Schema Object page, you see the filesystems to which you have access through the Explorer. Your schema should be there. Do as follows:

1. Select the database schema that contains the tables you want represented in your set of related CMP entity beans, and click Next.

You see a side-by-side display that consists of the list of available tables in your database schema and a blank page labeled Selected Tables.

2. From the Available Tables list on the left, select the tables you want and add them to the Selected Tables list on the right.

From this point on, the process and the GUI are just as described in Using a Database Connection:

a. When you have selected all your tables, click Next.

b. In the next dialog, deselect the checkbox of any table you don't want in your set of related CMP entity beans. Click OK.

c. In the Edit CMP Entity EJB Data page, edit beans, fields, or relationships as needed.

3. When you are done, click Finish.

The infrastructure of your set of related CMP entity beans is generated automatically by the EJB Builder.

---

Looking at the Components of a CMP Entity Bean Set

The EJB Builder wizard generates the basic CMP entity bean classes for you and sets up the relationships between all the beans and their classes. FIGURE 5-2 shows how a typical set of related CMP entity beans and their EJB module appear in the Explorer's Filesystems tab. In this example, the default, Local Interfaces Only, has been selected for a CMP entity bean whose references are to objects in the same container, while Both Local and Remote Interfaces has been selected for another CMP entity bean.

 FIGURE 5-2 Default Classes of a Typical Set of Related CMP Entity Beans

[ D ]

With the exception of the EJB module node, the nodes in represent the same components as are described in Looking at a CMP Entity Bean's Classes. Again, notice each bean's logical node marked with a bean icon. Do all your editing in the logical node.

Expanding the EJB Module's Node

The interesting difference lies in the bean-to-bean relationships in a set of related CMP entity beans. Those relationships are stored and displayed at the level of the EJB module, as shown in FIGURE 5-3.

 FIGURE 5-3 Expanded Nodes of an EJB Module Containing Related CMP Entity Beans

[ D ]

Notice the module's component bean nodes and relationship nodes. Notice also that the beans displayed in the EJB module are only logical links, not copies of the actual beans.

Reviewing the Generated Classes

Certain default methods, described in Chapter 4, are automatically placed in all CMP entity beans. For details, see the discussion in Reviewing the Generated Classes.

---

Completing Your Set of Related CMP Entity Beans

To complete your set of related CMP entity beans, do the following:

• Add any other CMP entity beans that your set needs, along with relationships to beans already in the set.
• Edit CMRs as needed.
• Define a create method if you want to let a bean's client insert data into the database. An entity bean can have more than one create method, and adding create methods is the same regardless of whether the CMP entity bean is on its own or in a set of related beans. Follow the instructions in Defining Create Methods.
• If necessary, add or replace a primary key. Again, you do this in the same way for all CMP entity beans. See the instructions in Adding or Replacing a Primary Key.
• Define all business methods that each of your beans needs, as explained in Defining Business Methods.
• Define any finder methods that your beans need in addition to findByPrimaryKey. Instructions are in Adding Finder Methods.
• Define one or more home methods if a bean needs to perform an operation that does not depend on any given bean instance. See Defining Home Methods.
• Define one or more select methods, if you want a CMP entity bean to query other beans within the same EJB module or to query the database and return a local or remote interface. Details are in Defining Select Methods.
• Add code, if necessary, to complete a bean's setEntityContext, unsetEntityContext, ejbActivate, ejbPassivate, and ejbRemove methods.

You might need to add one or more CMP fields to a bean if all the needed fields were not generated for you.

Make the basic parts of your additions in the Explorer by using the GUI tools that the IDE provides under the logical bean node. Provide the content of a method as follows:

• Name the method and completely define the method signature within the appropriate dialog box. Select the logical node, right-click, and choose Add Create Method, Add Business Method, Add Finder Method, Add Home Method, or Add Select Method. The EJB Builder propagates your method to the right classes of the CMP entity bean.
• Finish coding the method body within the Source Editor.

Using Recommended Approaches When Working With Enterprise Beans

Appendix A discusses the best ways to make changes in your enterprise beans, and the errors and anomalies that you might see if you use other approaches. As a general rule, you should work through the logical node rather than the individual class nodes, use the bean's property sheets or the Customizer dialog box to edit methods, and use the IDE's Source Editor to complete or edit any bean code that isn't available to you through one of the dialog boxes.

Adding a Bean to the Set

After generating your set of related CMP entity beans, you might find that you need another bean to represent a database table you didn't select. If so, follow these steps:

1. Decide which CMP entity bean you will add to the set.

Since the wizard has already generated the CMP entity beans in your existing set, the CMP entity bean you add to the set must already be generated, either as a single bean or as part of another set of related CMP entity beans.

2. Select the EJB Module node of your set of related CMP entity beans, right-click, and choose Add EJB.

The Add EJB to EJB Module dialog box appears. The tree view shows all filesystems mounted in the IDE's Explorer window.

3. Find the CMP entity bean you want to add to your set, select it, and click OK.

The bean is added to your set of related CMP entity beans.

4. Expand the EJB module node to see the set of related CMP entity beans, including the CMP entity bean you just added.

The bean you added appears without any relationships defined to other beans. In the following example, the new bean is Customer.

[ D ] 

Now you need to add any relationships needed by your new CMP entity bean or by other beans in the set.

5. Under the EJB Module node, select the two CMP entity beans between which you want to add a relationship.

In this example, the Customer and OrderTbl bean nodes are selected.

[ D ] 

6. Right-click and choose Add EJB Relation.

The Add EJB Relation dialog box appears, as shown next. The dialog box has three main sections: a field that names the relationship between the two CMP entity beans, a section describing the first entity bean, and a section describing the second entity bean.

[ D ] 

7. Define the relationship between the two CMP entity beans.

The wizard has populated the fields with default information based on existing information for the two selected beans. If necessary, you can make changes in the following places:

• (Optional) In the EJB Relation Name field, rename the relationship between the two beans.
• (Optional) In the Relationship Role Name field for either entity bean, give another name to the role that the bean plays in the relationship.
• (Optional) In the CMR Field Name field for either entity bean, specify by another name the field that relates the two beans.
• (Optional) In the CMR Type field for either entity bean, choose another type. However, if you don't change the CMR Field Name, you probably should leave the CMR Type as it is.
• (Optional) In the Multiplicity of BeanName section for either entity bean, change the cardinality of that bean in the relationship. However, if you don't change the CMR Field Name or the CMR Type field, you probably should leave the Multiplicity section as it is. Notice that if the radio button labeled Many is selected, the Cascade Delete BeanName checkbox becomes available.

8. Click OK when you're done.

Under the EJB Module node, the bean to which you added a relationship now shows a relationship badge added to its main icon:

---

After Creating Your Set of Related CMP Beans

Your set of related CMP entity beans is now finished except for a few steps that prepare the set to work in its eventual application environment. These final steps are described in Chapter 8.

Recommendations for working with finished enterprise beans are given in Appendix A.