Home TOC Index

Search Feedback

A Guided Tour of the RosterApp Settings

This section introduces you to the settings of the deployment descriptors for entity beans with container-managed persistence and relationships. As this tour guides you through the deploytool screens, it discusses the highlights of the tabs and dialog boxes that appear.

To begin our tour, please run deploytool and open the RosterApp.ear file, which is in the j2eetutorial/examples/ears directory.

RosterApp

To view the deployment settings for the application, select the RosterApp node in the tree view.

General Tab (RosterApp)

The Contents field displays the files contained in the RosterApp.ear file, including the two EJB JAR files (team-ejb.jar, roster-ejb.jar) and the J2EE application client JAR file (roster-ac.jar). See Figure 6-2.

Figure 6-2 General Tab of RosterApp

JNDI Names Tab (RosterApp)

The Application table lists the JNDI names for the enterprise beans in the RosterApp application.

The References table has two entries. The EJB Ref entry maps the coded name (ejb/SimpleRoster) in the RosterClient to the JNDI name of the RosterEJB session bean. The Resource entry specifies the JNDI name for the database that is accessed by the entity beans contained in the TeamJAR module.

RosterClient

To view this client, expand the RosterApp node by clicking its adjacent key icon in the tree view. Next, select RosterClient.

JAR File Tab (RosterClient)

The Contents field shows the files contained by the roster-ac.jar file: two XML files (the deployment descriptors) and a single class file (RosterClient.class).

EJB Refs Tab (RosterClient)

The RosterClient accesses a single bean, the RosterEJB session bean. Because this access is remote, the value in the Interfaces column is Remote and the value for the Local/Remote Interface column is the bean's remote interface (roster.Roster).

RosterJAR

In the tree view, select RosterJAR. This JAR file contains the RosterEJB session bean.

General Tab (RosterJAR)

The Contents field lists three packages of class files. The roster package contains the class files required for RosterEJB--the session bean class, remote interface, and home interface. The team package includes the local interfaces for the entity beans accessed by the RosterEJB session bean. The util package holds the utility classes for this application.

RosterEJB

In the tree view, expand the RosterJAR node and select RosterEJB.

General Tab (RosterEJB)

This tab shows that RosterEJB is a stateful session bean with remote access. Because it allows no local access, the Local Interfaces fields are empty.

EJB Refs Tab (RosterEJB)

The RosterEJB session bean accesses three entity beans: PlayerEJB, TeamEJB, and LeagueEJB. Because this access is local, the entries in the Interfaces columns are defined as Local. The Home Interface column lists the local home interfaces of the entity beans. The Local/Remote Interfaces column displays the local interfaces of the entity beans.

To view the runtime deployment settings, select a row in the table. For example, when you select the row with the Coded Name of ejb/SimpleLeague, the LeagueEJB name appears in the Enterprise Bean Name field. If a component references a local entity bean, then you must enter the name of the referenced bean in the Enterprise Bean Name field.

TeamJAR

In the tree view, select the TeamJAR node. This JAR file contains the three related entity beans: LeagueEJB, TeamEJB, and PlayerEJB.

General Tab (TeamJAR)

The Contents field shows two packages of class files: team and util. The team package has the entity bean classes, local interfaces, and local home interfaces for all three entity beans. The util package contains utility classes.

Relationships Tab (TeamJAR)

On this tab (Figure 6-3) you define the relationships between entity beans with container-managed persistence.

Figure 6-3 Relationships Tab of TeamJAR

The Container Managed Relationships table summarizes two relationships: TeamEJB-PlayerEJB and LeagueEJB-TeamEJB. In the TeamEJB-PlayerEJB relationship, TeamEJB is designated as EJB A and PlayerEJB as EJB B. (This designation is arbitrary--we could have assigned PlayerEJB to EJB A and TeamEJB to EJB B.)

Edit Relationship Dialog Box (TeamJAR)

To view the Edit Relationship dialog box (Figure 6-4), on the Relationships tab select a row and click Edit. For example, to view the TeamEJB-PlayerEJB relationship, select the row in which the EJB A value is Team and then click Edit.

Figure 6-4 Edit Relationship Dialog Box of TeamJAR

TeamEJB-PlayerEJB Relationship

The Multiplicity combo box offers four choices. For this relationship, the Many To Many choice should be selected because a team has many players and a player can belong to more than one team.

The information in the Enterprise Bean A box defines TeamEJB side of the relationship. The Field Referencing Bean B combo box displays the relationship field (players) in TeamEJB. This field corresponds to the relationship access methods in the TeamBean.java source code:

public abstract Collection getPlayers();	
public abstract void setPlayers(Collection players);
 

The selection of the Field Type combo box is java.util.Collection, which matches the players type in the access methods. The players type is a multi-valued object (Collection) because on the TeamEJB side of the relationship the multiplicity is many.

The TeamEJB-PlayerEJB relationship is bidirectional--each bean has a relationship field that identifies the related bean. If this relationship were unidirectional, then one of the beans would not have a relationship field identifying the other bean. For the bean without the relationship field, the value of the Field Referencing combo box would be <none>.

LeagueEJB-TeamEJB Relationship

In the Edit Relationship dialog box, the Multiplicity choice should be One to Many. This choice indicates that a single league has multiple teams.

For LeagueEJB, the relationship field is teams and for TeamEJB it is league. Because TeamEJB is on the multiple side of the relationship, the teams field is a Collection. In contrast, since LeagueEJB is on the single side of the relationship, the league field is a single-valued object, a LocalLeague. The TeamBean.java code defines the league relationship field with these access methods:

public abstract LocalLeague getLeague();	
public abstract void setLeague(LocalLeague players);
 

For TeamEJB (Enterprise Bean B), the Delete When Bean A Is Deleted checkbox is selected. Because of this selection, when a LeagueEJB instance is deleted the related TeamEJB instances are automatically deleted. This type of deletion, in which one deletion triggers another, is called a cascade delete. For LeagueEJB, the corresponding checkbox is disabled: If you delete a team, you don't want to automatically delete the league, because there may be other teams in that league. In general, if a bean is on the multiple side of a relationship, the other bean cannot be automatically deleted.

PlayerEJB

In the tree view, expand the TeamJAR node and select the PlayerEJB entity bean.

General Tab (PlayerEJB)

This tab shows the enterprise bean class and interfaces. Since the PlayerEJB entity bean uses container-managed persistence, it has local interfaces. It does not have remote interfaces because it does not allow remote access.

Entity Tab (PlayerEJB)

The radio buttons at the top of the tabbed page define the bean's persistence type (Figure 6-5). For PlayerEJB, this type is container-managed persistence, version 2.0. (Because version 1.0 did not support relationships, it is not recommended. These version numbers identify a particular release of the Enterprise JavaBeans Specification, not the J2EE SDK software.)

Figure 6-5 Entity Tab of PlayerEJB

The Fields To Be Persisted box lists the persistent and relationship fields defined by the access methods in the PlayerBean.java code. The checkboxes for the persistent fields must be selected, but those for the relationship fields must not be selected. The PlayerEJB entity bean has one relationship field: teams.

The abstract schema name is Player, a name that represents the relationships and persistent fields of the PlayerEJB entity bean. This abstract name is referenced in the PlayerEJB Enterprise JavaBeans Query Language (EJB QL) queries. For more information on EJB QL, see Chapter 8.

Finder/Select Methods Dialog Box (PlayerEJB)

To open this dialog box, click Finder/Select Methods on the Entity tab. This dialog box(Figure 6-6) enables you to view and edit the EJB QL queries for a bean's finder and select methods. For example, to list the finder methods defined in the LocalPlayerHome interface, select the Local Finders radio button. When you select the finder method, its EJB QL query appears in an editable text field.

Figure 6-6 Finder/Select Methods Dialog Box of PlayerEJB

Entity Deployment Settings Dialog Box (PlayerEJB)

To view this dialog box, click Deployment Settings in the Entity tab. In this dialog box, you define the runtime settings of an entity bean with container-managed persistence. These runtime settings are specific to the J2EE SDK; other implementations of the J2EE platform may take a different approach.

In the J2EE SDK, the bean's persistent fields are stored in a relational database table. In the checkboxes of the Database Table box, you specify whether or not the server automatically creates or drops the table. If you want to save the data in your table between deployments, then make sure that the Delete Table checkbox is not selected. Otherwise, every time you undeploy the bean, the table will be deleted.

The J2EE server accesses the database by issuing SQL calls. In an entity bean with container-managed persistence, you do not code these calls. The deploytool utility creates the SQL calls automatically when you click the Generate Default SQL button. To view the SQL statement for a finder method, for example, select the Local Finder radio button and then select an entry in the Method list. You may modify a SQL statement by editing the text in the SQL Query field.

For the finder and select methods, the corresponding EJB QL query is also displayed. When you click Generate Default SQL, deploytool translates the EJB QL queries into SQL calls. If you change an EJB QL query, you should click the Generate Default SQL button again.

To view the SQL CREATE TABLE statement, for example, click the Container Methods radio button and then select the createTable entry in the Method list. The CREATE TABLE statement defines column names for the bean's persistent fields and specifies a primary key constraint for playerId, the bean's primary key field.

When the EJB container creates a new PlayerEJB instance, it issues a SQL INSERT statement. To examine this statement, select createRow from the Method list. In the INSERT statement, the parameters in the values clause correspond to the arguments of the create method that is defined in the LocalPlayerHome interface:

public LocalPlayer create (String id, String name, 	
    String position, double salary) throws CreateException;
 

Database Deployment Settings Dialog Box (PlayerEJB)

To access this dialog box, click Deployment Settings on the Entity tab. In the Deployment Settings dialog box that appears, click Database Settings. The Deployment Settings dialog box with the Database Settings label should appear.

It is important that you set the JNDI name of the database. (If it is not set, the bean cannot connect to the database.) For this example, the Database JNDI Name field should be jdbc/Cloudscape. The User Name and Password fields are blank because they are not required for Cloudscape.

Home TOC Index

Search Feedback