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
deploytoolscreens, it discusses the highlights of the tabs and dialog boxes that appear.
To begin our tour, please run
deploytooland open the
RosterApp.earfile, which is in the
To view the deployment settings for the application, select the
RosterAppnode in the tree view.
General Tab (RosterApp)
The Contents field displays the files contained in the
RosterApp.earfile, including the two EJB JAR files (
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
The References table has two entries. The EJB Ref entry maps the coded name (
ejb/SimpleRoster) in the
RosterClientto the JNDI name of the
RosterEJBsession bean. The Resource entry specifies the JNDI name for the database that is accessed by the entity beans contained in the
To view this client, expand the
RosterAppnode by clicking its adjacent key icon in the tree view. Next, select
JAR File Tab (RosterClient)
The Contents field shows the files contained by the
roster-ac.jarfile: two XML files (the deployment descriptors) and a single class file (
EJB Refs Tab (RosterClient)
RosterClientaccesses a single bean, the
RosterEJBsession 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 (
In the tree view, select
RosterJAR. This JAR file contains the
General Tab (RosterJAR)
The Contents field lists three packages of class files. The
rosterpackage contains the class files required for
RosterEJB--the session bean class, remote interface, and home interface. The
teampackage includes the local interfaces for the entity beans accessed by the
RosterEJBsession bean. The
utilpackage holds the utility classes for this application.
In the tree view, expand the
RosterJARnode and select
General Tab (RosterEJB)
This tab shows that
RosterEJBis a stateful session bean with remote access. Because it allows no local access, the Local Interfaces fields are empty.
EJB Refs Tab (RosterEJB)
RosterEJBsession bean accesses three entity beans:
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
LeagueEJBname 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.
In the tree view, select the
TeamJARnode. This JAR file contains the three related entity beans:
General Tab (TeamJAR)
The Contents field shows two packages of class files:
teampackage has the entity bean classes, local interfaces, and local home interfaces for all three entity beans. The
utilpackage 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:
LeagueEJB-TeamEJB. In the
TeamEJBis designated as EJB A and
PlayerEJBas EJB B. (This designation is arbitrary--we could have assigned
PlayerEJBto EJB A and
TeamEJBto 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-PlayerEJBrelationship, select the row in which the EJB A value is
Teamand then click Edit.
Figure 6-4 Edit Relationship Dialog Box of
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
TeamEJBside of the relationship. The Field Referencing Bean B combo box displays the relationship field (
TeamEJB. This field corresponds to the relationship access methods in the
TeamBean.javasource 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
playerstype in the access methods. The
playerstype is a multi-valued object (
Collection) because on the
TeamEJBside of the relationship the multiplicity is many.
TeamEJB-PlayerEJBrelationship 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
In the Edit Relationship dialog box, the Multiplicity choice should be One to Many. This choice indicates that a single league has multiple teams.
LeagueEJB, the relationship field is
TeamEJBis on the multiple side of the relationship, the
teamsfield is a
Collection. In contrast, since
LeagueEJBis on the single side of the relationship, the
leaguefield is a single-valued object, a
TeamBean.javacode defines the league relationship field with these access methods:public abstract LocalLeague getLeague(); public abstract void setLeague(LocalLeague players);
TeamEJB(Enterprise Bean B), the Delete When Bean A Is Deleted checkbox is selected. Because of this selection, when a
LeagueEJBinstance is deleted the related
TeamEJBinstances 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.
In the tree view, expand the
TeamJARnode and select the
General Tab (PlayerEJB)
This tab shows the enterprise bean class and interfaces. Since the
PlayerEJBentity 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
The Fields To Be Persisted box lists the persistent and relationship fields defined by the access methods in the
PlayerBean.javacode. The checkboxes for the persistent fields must be selected, but those for the relationship fields must not be selected. The
PlayerEJBentity bean has one relationship field:
The abstract schema name is
Player, a name that represents the relationships and persistent fields of the
PlayerEJBentity bean. This abstract name is referenced in the
PlayerEJBEnterprise 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
LocalPlayerHomeinterface, 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
deploytoolutility 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,
deploytooltranslates 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
TABLEstatement, for example, click the Container Methods radio button and then select the createTable entry in the Method list. The
CREATE TABLEstatement 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
PlayerEJBinstance, it issues a SQL
INSERTstatement. To examine this statement, select createRow from the Method list. In the
INSERTstatement, the parameters in the
valuesclause correspond to the arguments of the
createmethod that is defined in the
LocalPlayerHomeinterface: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.