38.2 The roster Application

38.2.1.1 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
@JoinTable(
    name="PERSISTENCE_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 database table that will associate player IDs with team IDs. The entity that specifies the @JoinTable is the owner of the relationship, so the Team entity is the owner of the relationship with the Player entity. Because roster uses automatic table creation at deployment time, the container will create a join table named PERSISTENCE_ROSTER_TEAM_PLAYER.

Player is the inverse, or nonowning, side of the relationship with Team. As one-to-one and many-to-one relationships, the nonowning 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(mappedBy="players")
public Collection<Team> getTeams() {
    return teams;
}

38.2.3.1 Metamodel Classes in the roster Application

Metamodel classes model an entity's attributes and are used by Criteria queries to navigate to an entity's attributes. Each entity class in roster has a corresponding metamodel class, generated at compile time, with the same package name as the entity and appended with an underscore character (_). For example, the roster.entity.Player entity has a corresponding metamodel class, roster.entity.Player_.

Each persistent field or property in the entity class has a corresponding attribute in the entity's metamodel class. For the Player entity, the corresponding metamodel class is as follows:

@StaticMetamodel(Player.class)
public class Player_ {
    public static volatile SingularAttribute<Player, String> id;
    public static volatile SingularAttribute<Player, String> name;
    public static volatile SingularAttribute<Player, String> position;
    public static volatile SingularAttribute<Player, Double> salary;
    public static volatile CollectionAttribute<Player, Team> teams;
}

38.2.3.2 Obtaining a CriteriaBuilder Instance in RequestBean

The CriteriaBuilder interface defines methods to create criteria query objects and create expressions for modifying those query objects. RequestBean creates an instance of CriteriaBuilder by using a @PostConstruct method, init:

@PersistenceContext
private EntityManager em;
private CriteriaBuilder cb;

@PostConstruct
private void init() {
    cb = em.getCriteriaBuilder();
}

The EntityManager instance is injected at runtime, and then that EntityManager object is used to create the CriteriaBuilder instance by calling getCriteriaBuilder. The CriteriaBuilder instance is created in a @PostConstruct method to ensure that the EntityManager instance has been injected by the enterprise bean container.

38.2.3.3 Creating Criteria Queries in RequestBean's Business Methods

Many of the business methods in RequestBean define Criteria queries. One business method, getPlayersByPosition, returns a list of players who play a particular position on a team:

public List<PlayerDetails> getPlayersByPosition(String position) {
    logger.info("getPlayersByPosition");
    List<Player> players = null;
    
    try {
        CriteriaQuery<Player> cq = cb.createQuery(Player.class);
        if (cq != null) {
            Root<Player> player = cq.from(Player.class);

            // set the where clause
            cq.where(cb.equal(player.get(Player_.position), position));
            cq.select(player);
            TypedQuery<Player> q = em.createQuery(cq);
            players = q.getResultList();
        }
        return copyPlayersToDetails(players);
    } catch (Exception ex) {
        throw new EJBException(ex);
    }
}

A query object is created by calling the CriteriaBuilder object's createQuery method, with the type set to Player because the query will return a list of players.

The query root, the base entity from which the query will navigate to find the entity's attributes and related entities, is created by calling the from method of the query object. This sets the FROM clause of the query.

The WHERE clause, set by calling the where method on the query object, restricts the results of the query according to the conditions of an expression. The CriteriaBuilder.equal method compares the two expressions. In getPlayersByPosition, the position attribute of the Player_ metamodel class, accessed by calling the get method of the query root, is compared to the position parameter passed to getPlayersByPosition.

The SELECT clause of the query is set by calling the select method of the query object. The query will return Player entities, so the query root object is passed as a parameter to select.

The query object is prepared for execution by calling EntityManager.createQuery, which returns a TypedQuery<T> object with the type of the query, in this case Player. This typed query object is used to execute the query, which occurs when the getResultList method is called, and a List<Player> collection is returned.

38.2.5.1 To Run the roster Example Using NetBeans IDE

1. Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).

2. If the database server is not already running, start it by following the instructions in Starting and Stopping the Java DB Server.

3. From the File menu, choose Open Project.

4. In the Open Project dialog box, navigate to:

   tut-install/examples/persistence
   

5. Select the roster folder.

6. Select the Open Required Projects check box.

7. Click Open Project.

8. In the Projects tab, right-click the roster project and select Build.

   This will compile, package, and deploy the EAR to GlassFish Server.

   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
   

38.2.5.2 To Run the roster Example Using Maven

1. Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).

2. If the database server is not already running, start it by following the instructions in Starting and Stopping the Java DB Server.

3. In a terminal window, go to:

   tut-install/examples/persistence/roster/roster-ear/
   

4. Enter the following command:

   mvn install
   

   This compiles the source files and packages the application into an EAR file located at tut-install/examples/persistence/roster/target/roster.ear. The EAR file is then deployed to GlassFish Server. GlassFish Server will then drop and create the database tables during deployment, as specified in persistence.xml.

   After successfully deploying the EAR, the client stubs are retrieved and the application client is run using the appclient application included with GlassFish Server.

   You will see the output, which begins as follows:

   [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