A Guided Tour of the RosterApp Settings - The J2EE 1.4 Tutorial

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 <INSTALL>/j2eetutorial14/examples/ejb/provided-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 (ejb-jar-ic.jar and ejb-jar-ic1.jar) and the application client JAR file (app-client-ic.jar). See Figure 27-4.

Figure 27-4 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 one entry. The EJB Ref entry maps the coded name (ejb/SimpleRoster) in the RosterClient to the JNDI name of the RosterBean session bean.

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 app-client-ic.jar file: two XML files (the deployment descriptors) and the class files (RosterClient.class, Debug.class, LeagueDetails.class, PlayerDetails.class, and TeamDetails.class).

EJB Ref's Tab (RosterClient)

The RosterClient accesses a single bean, the RosterBean 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 RosterBean session bean.

General Tab (RosterJAR)

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

RosterBean

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

General Tab (RosterBean)

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

EJB Ref's Tab (RosterBean)

The RosterBean session bean accesses three entity beans: PlayerBean, TeamBean, and LeagueBean. 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 LeagueBean 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: LeagueBean, TeamBean, and PlayerBean.

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. It also shows the database schema file that is used to map the enterprise bean's fields to the database.

Relationships Tab (TeamJAR)

On this tab (Figure 27-5) you define the relationships between entity beans that use container-managed persistence.

Figure 27-5 Relationships Tab of TeamJAR

The Container Managed Relationships table summarizes two relationships: TeamBean-PlayerBean and LeagueBean-TeamBean. In the TeamBean-PlayerBean relationship, TeamBean is designated as EJB A and PlayerBean as EJB B. (This designation is arbitrary. We could have assigned PlayerBean to EJB A, and assigned TeamBean to EJB B.)

Edit Relationship Dialog Box (TeamJAR)

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

TeamBean-PlayerBean 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 the TeamBean side of the relationship. The Field Referencing Bean B combo box displays the relationship field (players) in TeamBean. This field corresponds to the relationship access methods in the TeamBean.java source code:

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

Figure 27-6 Edit Relationship Dialog Box of TeamJAR

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 TeamBean side of the relationship the multiplicity is many.

The TeamBean-PlayerBean 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>.

LeagueBean-TeamBean 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 LeagueBean, the relationship field is teams, and for TeamBean it is league. Because TeamBean is on the multiple side of the relationship, the teams field is a Collection. In contrast, because LeagueBean 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 league); 

For TeamBean (Enterprise Bean B), the Delete When Bean A Is Deleted checkbox is selected. Because of this selection, when a LeagueBean instance is deleted the related TeamBean instances are automatically deleted. This type of deletion, in which one deletion triggers another, is called a cascade delete. For LeagueBean, 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.

PlayerBean

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

General Tab (PlayerBean)

This tab shows the enterprise bean class and interfaces. Because the PlayerBean 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 (PlayerBean)

The field at the top of the tabbed page define's the bean's persistence type (Figure 27-7). For PlayerBean, this type is Container-Managed Persistence, version 2.0. (Because version 1.1 did not support relationships, it is not recommended. These version numbers identify a particular release of the Enterprise JavaBeans specification, not the Application Server software.)

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 PlayerBean entity bean has one relationship field: teams.

The abstract schema name is Player, a name that represents the relationships and persistent fields of the PlayerBean entity bean. This abstract name is referenced in the PlayerBean EJB QL queries. For more information on EJB QL, see Chapter 29.

Figure 27-7 Entity Tab of PlayerBean

Finder/Select Methods Dialog Box (PlayerBean)

To open this dialog box, click Finder/Select Methods on the Entity tab. This dialog box (Figure 27-8) 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 27-8 Finder/Select Methods Dialog Box of PlayerBean

Sun-Specific CMP Settings Dialog Box (PlayerBean)

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

In the Application Server, 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 Application Server accesses the database by issuing SQL calls. In an entity bean with container-managed persistence, you do not code these calls. The container creates the SQL calls automatically when you access the persistent fields and relationships.

In the Persistent Field Mapping section (see Figure 27-9), the mappings and relationships for all the entity beans in TeamJAR are listed. For example, to see the mappings and relationships for PlayerBean, select it from the Enterprise Bean field.

Figure 27-9 CMP Settings for PlayerBean

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.