Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## 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`, and `League`), a stateful session bean (`RequestBean`), an application client (`RosterClient`), and three helper classes (`PlayerDetails`, `TeamDetails`, and `LeagueDetails`).

> Functionally, `roster` is similar to the `order` application described earlier in this chapter with two new features that `order` does not have: many-to-many relationships and automatic table creation at deploytime.

> ### Relationships in the roster Application

> A recreational sports system has the following relationships:

> - A player can be on many teams.
> - A team can have many players.
> - A team is in exactly one league.
> - A league has many teams.

> In `roster` this is reflected by the following relationships between the `Player`, `Team`, and `League` entities:

> - There is a many-to-many relationship between `Player` and `Team`.
> - There is a many-to-one relationship between `Team` and `League`

> #### The Many-To-Many Relationship in roster

> The many-to-many relationship between `Player` and `Team` is specified by using the `@ManyToMany` annotation.

> In `Team.java`, the `@ManyToMany` annotation decorates the `getPlayers` method:

>     @ManyToMany(cascade=REMOVE)
>     @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 the `Team` entity is the owner of the relationship with the `Player` entity. Because `roster` uses automatic table creation at deploytime, the container will create a join table in the database named `EJB_ROSTER_TEAM_PLAYER`.

> `Player` is the inverse, or non-owning side of the relationship with `Team`. As one-to-one and many-to-one relationships, the non-owning side is marked by the `mappedBy` element in the relationship annotation. Because the relationship between `Player` and `Team` is bidirectional, the choice of which entity is the owner of the relationship is arbitrary.

> In `Player.java`, the `@ManyToMany` annotation decorates the `getTeams` method:

>     @ManyToMany(cascade=REMOVE, mappedBy="players")
>     public Collection<Team> getTeams() {
>       return teams;
>     }

> ### Automatic Table Generation in roster

> At deploytime the Application Server will automatically drop and create the database tables used by `roster`. This is done by setting the `toplink.ddl-generation` property to `drop-and-create-tables` in `persistence.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.