The roster Application
The
roster
application maintains the team rosters for players in recreational sports leagues. The application has four components: Java Persistence API entities (Player
,Team
, andLeague
), a stateful session bean (RequestBean
), an application client (RosterClient
), and three helper classes (PlayerDetails
,TeamDetails
, andLeagueDetails
).Functionally,
roster
is similar to theorder
application described earlier in this chapter with three new features thatorder
does not have: many-to-many relationships, entity inheritance, and automatic table creation at deploytime.Relationships in the roster Application
A recreational sports system has the following relationships:
In
roster
this is reflected by the following relationships between thePlayer
,Team
, andLeague
entities:The Many-To-Many Relationship in roster
The many-to-many relationship between
Player
andTeam
is specified by using the@ManyToMany
annotation.In
Team.java
, the@ManyToMany
annotation decorates thegetPlayers
method:@ManyToMany @JoinTable( name="EJB_ROSTER_TEAM_PLAYER", joinColumns= @JoinColumn(name="TEAM_ID", referencedColumnName="ID"), inverseJoinColumns= @JoinColumn(name="PLAYER_ID", referencedColumnName="ID") ) public Collection<Player> getPlayers() { return players; }The
@JoinTable
annotation is used to specify a table in the database that will associate player IDs with team IDs. The entity that specifies the@JoinTable
is the owner of the relationship, so in this case theTeam
entity is the owner of the relationship with thePlayer
entity. Becauseroster
uses automatic table creation at deploytime, the container will create a join table in the database namedEJB_ROSTER_TEAM_PLAYER
.
Player
is the inverse, or non-owning side of the relationship withTeam
. As one-to-one and many-to-one relationships, the non-owning side is marked by themappedBy
element in the relationship annotation. Because the relationship betweenPlayer
andTeam
is bidirectional, the choice of which entity is the owner of the relationship is arbitrary.In
Player.java
, the@ManyToMany
annotation decorates thegetTeams
method:Entity Inheritance in the roster Application
The
roster
application demonstrates how to use entity inheritance, as described in Entity Inheritance.The
League
entity inroster
is an abstract entity with two concrete subclasses:SummerLeague
andWinterLeague
. BecauseLeague
is an abstract class it cannot be instantiated:... @Entity @Table(name = "EJB_ROSTER_LEAGUE") public abstract class League implements java.io.Serializable { ... }Instead,
SummerLeague
orWinterLeague
are used by clients when creating a league.SummerLeague
andWinterLeague
inherit the persistent properties defined inLeague
, and only add a constructor that verifies that the sport parameter matches the type of sport allowed in that seasonal league. For example, here is theSummerLeague
entity:... @Entity public class SummerLeague extends League implements java.io.Serializable { /** Creates a new instance of SummerLeague */ public SummerLeague() { } public SummerLeague(String id, String name, String sport) throws IncorrectSportException { this.id = id; this.name = name; if (sport.equalsIgnoreCase("swimming") || sport.equalsIgnoreCase("soccer") || sport.equalsIgnoreCase("basketball") || sport.equalsIgnoreCase("baseball")) { this.sport = sport; } else { throw new IncorrectSportException( "Sport is not a summer sport."); } } }The roster application uses the default mapping strategy of
InheritanceType.SINGLE_TABLE
, so the@Inheritance
annotation is not required. If you wanted to use a different mapping strategy, decorateLeague
with@Inheritance
and specify the mapping strategy in thestrategy
element:@Entity @Inheritance(strategy=JOINED) @Table(name="EJB_ROSTER_LEAGUE") public abstract class League implements java.io.Serializable { ... }
roster
uses the default discriminator column name, so the@DiscriminatorColumn
annotation is not required. Because we are using automatic table generation inroster
the Persistence provider will create a discriminator column in theEJB_ROSTER_LEAGUE
table calledDTYPE
, which will store the name of the inherited entity used to create the league. If you want to use a different name for the discriminator column, decorateLeague
with@DiscriminatorColumn
and set thename
element:@Entity @DiscriminatorColumn(name="DISCRIMINATOR") @Table(name="EJB_ROSTER_LEAGUE") public abstract class League implements java.io.Serializable { ... }Automatic Table Generation in the roster Application
At deploytime the Application Server will automatically drop and create the database tables used by
roster
. This is done by setting thetoplink.ddl-generation
property todrop-and-create-tables
inpersistence.xml
.<?xml version="1.0" encoding="UTF-8"?> <persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0"> <persistence-unit name="em" transaction-type="JTA"> <jta-data-source>jdbc/__default</jta-data-source> <properties> <property name="toplink.ddl-generation" value="drop-and-create-tables"/> </properties> </persistence-unit> </persistence>This feature is specific to the Java Persistence API provider used by the Application Server, and is non-portable across Java EE servers. Automatic table creation is useful for development purposes, however, and the toplink.ddl-generation property may be removed from
persistence.xml
when preparing the application for production use, or when deploying to other Java EE servers.Building and Running the roster Application
This section describes how to build, package, deploy, and run the
roster
application. You can do this using either NetBeans 5.5 or Ant.Building, Packaging, Deploying, and Running roster in NetBeans 5.5
Follow these instructions to build, package, deploy, and run the
roster
example to your Application Server instance using NetBeans 5.5.
- In NetBeans 5.5, select File
Open Project.
- In the Open Project dialog, navigate to
<
INSTALL
>/javaeetutorial5/examples/ejb/
.- Select the
roster
folder.- Select the Open as Main Project and Open Required Projects checkboxes.
- Click Open Project Folder.
- In the Projects tab, right-click the
roster
project and select Run Project.You will see the following partial output from the application client in the Output tab:
List all players in team T2: P6 Ian Carlyle goalkeeper 555.0 P7 Rebecca Struthers midfielder 777.0 P8 Anne Anderson forward 65.0 P9 Jan Wesley defender 100.0 P10 Terry Smithson midfielder 100.0 List all teams in league L1: T1 Honey Bees Visalia T2 Gophers Manteca T5 Crows Orland List all defenders: P2 Alice Smith defender 505.0 P5 Barney Bold defender 100.0 P9 Jan Wesley defender 100.0 P22 Janice Walker defender 857.0 P25 Frank Fletcher defender 399.0 ...Building, Packaging, Deploying, and Running roster Using Ant
To build the application components of
roster
, enter the following command:This runs the
default
task, which compiles the source files and packages the application into an EAR file located at<
INSTALL
>/examples/ejb/roster/dist/roster.ear
.To deploy the EAR, make sure the Application Server is started, then enter the following command:
The build system will check to see if the Java DB database server is running and start it if it is not running, then deploy
roster.ear
. The Application Server will then drop and create the database tables during deployment, as specified inpersistence.xml
.After
roster.ear
is deployed, a client JAR,rosterClient.jar
, is retrieved. This contains the application client.To run the application client, enter the following command:
You will see the output, which begins:
[echo] running application client container. [exec] List all players in team T2: [exec] P6 Ian Carlyle goalkeeper 555.0 [exec] P7 Rebecca Struthers midfielder 777.0 [exec] P8 Anne Anderson forward 65.0 [exec] P9 Jan Wesley defender 100.0 [exec] P10 Terry Smithson midfielder 100.0 [exec] List all teams in league L1: [exec] T1 Honey Bees Visalia [exec] T2 Gophers Manteca [exec] T5 Crows Orland [exec] List all defenders: [exec] P2 Alice Smith defender 505.0 [exec] P5 Barney Bold defender 100.0 [exec] P9 Jan Wesley defender 100.0 [exec] P22 Janice Walker defender 857.0 [exec] P25 Frank Fletcher defender 399.0 ...The all Task
As a convenience, the
all
task will build, package, deploy, and run the application. To do this, enter the following command:Undeploying order
To undeploy
roster.ear
, enter the following command: