Building and Running the RosterApp Example

Now that you understand the structure of the RosterApp example EAR file, you will assemble the enterprise application and the application client and then run the example. This section gives detailed instructions on how to build and run the RosterApp example, which is located at <INSTALL>/j2eetutorial14/examples/ejb/cmproster/.

Creating the Database Tables

The RosterApp application uses the database tables shown in Figure 27-2.

Database Tables in RosterApp

Figure 27-2 Database Tables in RosterApp

The instructions that follow explain how to use the RosterApp example with Derby, the database software that is included in the Application Server bundle.

  1. Create the database tables by running the create.sql script.
    1. In a terminal window, go to this directory:

      2.   <INSTALL>/j2eetutorial14/examples/ejb/cmproster/

    2. Type the following command, which runs the create.sql script:

      3.   asant create-db_common

Note: Application Server 8.2 includes a copy of the open source Derby database server. Application Server 8.0/8.1 includes the PointBase database server. If you are using Application Server 8.0/8.1, either follow the instructions in the J2EE Tutorial at http://java.sun.com/j2ee/1.4/docs/tutorial-update6/doc/index.html that works with Application Server 8.0/8.1 or upgrade to Application Server 8.2 (see http://java.sun.com/j2ee/1.4/download.html#appserv to download).

Creating the Data Source

You must create the jdbc/ejbTutorialDB data source. For instructions on creating this resource in the Admin Console, see Creating a Data Source.

Capturing the Table Schema

You will now create a database schema file, which will allow you to map fields from the enterprise beans to columns in the database tables created earlier.

  1. Make sure that the Derby server is running.
  2. In a terminal window, go to

    3. <INSTALL>/j2eetutorial14/examples/ejb/cmproster/

  3. Type the following command to create the database schema file, named cmproster.dbschema, in the ./build/ directory:

    4. asant capture-db-schema

The capture-db-schema task calls the capture-schema utility to output an XML file, cmproster.dbschema, which represents the structure of the database tables you created in Creating the Database Tables. The cmproster.dbschema file will be used to automatically map the enterprise bean fields to database columns.

The command that's called when you run the capture-db-schema task is as follows: 

capture-schema 
-dburl jdbc:derby://localhost:1527/sun-appserv-samples 
-username APP -password APP-table LEAGUE 
-table PLAYER -table TEAM -table TEAM_PLAYER 
-schemaname APP 
-driver org.apache.derby.jdbc.ClientDriver 
-out build/cmproster.dbschema

Building the Enterprise Beans

You will now build the enterprise beans.

  1. In a terminal window, go to this directory:

    2. <INSTALL>/j2eetutorial14/examples/ejb/cmproster/

  2. Type the following command:

    3. asant build

Creating the Enterprise Application

Create a new application in deploytool called RosterApp.

  1. In deploytool select FileRight ArrowNewRight ArrowApplication.
  2. In the Application File Name field, click Browse.
  3. Navigate to <INSTALL>/j2eetutorial14/examples/ejb/cmproster/.
  4. In the File Name field enter RosterApp.
  5. Click New Application.
  6. Click OK.

Packaging the Enterprise Beans

You will now package the four enterprise beans: RosterBean, LeagueBean, PlayerBean, and TeamBean. Note that RosterBean, a stateful session bean, will be packaged in RosterJAR. The others (LeagueBean, PlayerBean, and TeamBean) are entity beans using container-managed persistence, and will be packaged in TeamJAR.

Packaging RosterBean

RosterBean is a stateful session bean that accesses the data in the entity beans. Clients will access and manipulate that data through RosterBean.

  1. Create a new enterprise bean in RosterApp by selecting FileRight ArrowNewRight ArrowEnterprise Bean.
  2. In the EJB JAR screen:
    1. Select Create New JAR Module in Application.
    2. Enter RosterJAR under JAR Name.
    3. Click Edit Contents.
    4. Navigate to <INSTALL>/j2eetutorial14/examples/ejb/cmproster/build/.
    5. Select the roster and util directories.
    6. Click Add.
    7. Click OK.
    8. Click Next.
  3. In the General screen:
    1. Select roster.RosterBean under Enterprise Bean Class.
    2. Enter RosterBean under Enterprise Bean Name.
    3. Select Stateful Session under Enterprise Bean Type.
    4. Select roster.RosterHome under Remote Home Interface.
    5. Select roster.Roster under Remote Interface.
    6. Select Next.
  4. Click Finish.

Packaging LeagueBean, PlayerBean, and TeamBean

To package LeagueBean, PlayerBean, and TeamBean, follow these steps:

  1. Create a new enterprise bean in RosterApp by selecting FileRight ArrowNewRight ArrowEnterprise Bean.
  2. In the EJB JAR screen:
    1. Select Create New JAR Module in Application.
    2. Enter TeamJAR under JAR Name.
    3. Click Edit Contents.
    4. Navigate to <INSTALL>/j2eetutorial14/examples/ejb/cmproster/build/.
    5. Select the team and util directories, and the cmproster.dbschema file.
    6. Click Add.
    7. Click OK.
    8. Click Next.
  3. In the General screen:
    1. Select team.LeagueBean under Enterprise Bean Class.
    2. Enter LeagueBean under Enterprise Bean Name.
    3. Select team.LocalLeagueHome under Local Home Interface.
    4. Select team.LocalLeague under Local Interface.
    5. Click Next.

Note: Be sure to enter the correct name in the Enterprise Bean Name field for LeagueBean, PlayerBean, and TeamBean to allow the automatic mapping of persistent fields and relationships.

  1. In the Entity Settings screen:
    1. In the Persistence Management Type field, select Container-Managed Persistence (2.0).
    2. In the Fields To Be Persisted frame, check name, leagueId, and sport.
    3. In the Abstract Schema Name field, enter League.
    4. In the Primary Key Class field, choose Select an Existing Field.
    5. Select leagueId [java.lang.String].
    6. Click Next.
  2. Click Finish.

Now we'll add PlayerBean to TeamJAR.

  1. Create a new enterprise bean in TeamJAR by selecting FileRight ArrowNewRight ArrowEnterprise Bean.
  2. In the EJB JAR screen:
    1. Select Add To Existing JAR Module.
    2. Select TeamJAR (RosterApp) under Add To Existing JAR Module.
    3. Click Next.
  3. In the General screen:
    1. Select team.PlayerBean under Enterprise Bean Class.
    2. Enter PlayerBean under Enterprise Bean Name.
    3. Select team.LocalPlayerHome under Local Home Interface.
    4. Select team.LocalPlayer under Local Interface.
    5. Click Next.
  4. In the Entity Settings screen:
    1. In the Persistence Management Type field, select Container-Managed Persistence (2.0).
    2. In the Fields To Be Persisted frame, check name, position, playerId, and salary.
    3. In the Abstract Schema Name field, enter Player.
    4. In the Primary Key Class field choose Select an Existing Field.
    5. Select playerId [java.lang.String].
    6. Click Next.
  5. Click Finish.

Now we'll add TeamBean to TeamJAR.

  1. Create a new enterprise bean in TeamJAR by selecting FileRight ArrowNewRight ArrowEnterprise Bean.
  2. In the EJB JAR screen:
    1. Select Add To Existing JAR Module.
    2. Select TeamJAR (RosterApp) under Add To Existing JAR Module.
    3. Click Next.
  3. In the General screen:
    1. Select team.TeamBean under Enterprise Bean Class.
    2. Enter TeamBean under Enterprise Bean Name.
    3. Select team.LocalTeamHome under Local Home Interface.
    4. Select team.LocalTeam under Local Interface.
    5. Click Next.
  4. In the Entity Settings screen:
    1. In the Persistence Management Type field, select Container-Managed Persistence (2.0).
    2. In the Fields To Be Persisted frame, check name, teamId, and city.
    3. In the Abstract Schema Name field, enter Team.
    4. In the Primary Key Class field, choose Select an Existing Field.
    5. Select teamId [java.lang.String].
    6. Click Next.
  5. Click Finish.

Adding EJB QL Queries to PlayerBean

PlayerBean contains finder and selector methods that use EJB QL queries. These steps will add the appropriate EJB QL queries to the methods. See Chapter 29 for more details.

  1. Select PlayerBean in the tree in deploytool.
  2. Select the Entity tabbed pane.
  3. Click Find/Select Queries.
  4. In Show Local Finders:
    1. For the findAll method, enter

      2.   select object(p) from Player p

    2. For the findByCity method, enter

      3.   select distinct object(p) from Player p,
        in (p.teams) as t
        where t.city = ?1

    3. For the findByHigherSalary method, enter

      4.   select distinct object(p1)
        from Player p1, Player p2
        where p1.salary > p2.salary and
        p2.name = ?1

    4. For the findByLeague method, enter

      5.   select distinct object(p) from Player p,
        in (p.teams) as t
        where t.league = ?1

    5. For the findByPosition method, enter

      6.   select distinct object(p) from Player p
        where p.position = ?1

    6. For the findByPositionAndName method, enter

      7.   select distinct object(p) from Player p
        where p.position = ?1 and p.name = ?2

    7. For the findBySalaryRange method, enter

      8.   select distinct object(p) from Player p
        where p.salary between ?1 and ?2

    8. For the findBySport method, enter

      9.   select distinct object(p) from Player p,
        in (p.teams) as t
        where t.league.sport = ?1

    9. For the findByTest method, enter

      10.   select distinct object(p) from Player p
        where p.name = ?1

    10. For the findNotOnTeam method, enter

      11.   select object(p) from Player p
        where p.teams is empty

  5. In Show Select Methods:
    1. For the ejbSelectLeagues method, enter

      2.   select distinct t.league
        from Player p, in (p.teams) as t
        where p = ?1

    2. For the ejbSelectSports method, enter

      3.   select distinct t.league.sport
        from Player p, in (p.teams) as t
        where p = ?1

    3. Under Return EJBs of Type, select None for ejbSelectSports.
  6. Click OK.
  7. Select FileRight ArrowSave.

Establishing Relationships between Enterprise Beans

TeamJAR has the relationships shown in Figure 27-3.

Relationships between Enterprise Beans in TeamJAR

Figure 27-3 Relationships between Enterprise Beans in TeamJAR

Relationships should always be mapped to the primary key field(s) of the related table.

To create the container-managed relationships between the enterprise beans, do the following:

  1. Select TeamJAR in the tree in deploytool.
  2. Select the Relationships tabbed pane.
  3. Click Add.
  4. In the Add Relationship dialog box:
    1. In the Multiplicity field, select Many to Many (*:*).
    2. In the Enterprise Bean A section:
      1. In the Enterprise Bean Name field, select TeamBean.
      2. In the Field Referencing Bean B field, select players.
      3. In the Field Type field, select java.util.Collection.
    3. In the Enterprise Bean B section:
      1. In the Enterprise Bean Name field, select PlayerBean.
      2. In the Field Referencing Bean A field, select teams.
      3. In the Field Type field, select java.util.Collection.
    4. Click OK.
  5. Click Add.
  6. In the Add Relationship dialog box:
    1. In the Multiplicity field, select One to Many (1:*).
    2. In the Enterprise Bean A section:
      1. In the Enterprise Bean Name field, select LeagueBean.
      2. In the Field Referencing Bean B field, select teams.
      3. In the Field Type field, select java.util.Collection.
    3. In the Enterprise Bean B section:
      1. In the Enterprise Bean Name field, select TeamBean.
      2. In the Field Referencing Bean A field, select league.
      3. Check Delete When Bean A Is Deleted.
    4. Click OK.

Creating the Field and Relationship Mappings

To set the container-managed fields and relationships, do the following:

  1. Select TeamJAR from the tree in deploytool.
  2. Select the General tabbed pane.
  3. Click Sun-specific Settings.
  4. In the Sun-specific Settings dialog box:
    1. In the JNDI Name field, enter jdbc/ejbTutorialDB.
    2. Click Create Database Mappings.
  5. In the Create Database Mappings dialog box:
    1. Select Map to Tables in Database Schema File.
    2. Select cmproster.dbschema under Database Schema Files in Module.
    3. Click OK.
  6. Confirm that all the fields and relationships have been mapped.
  7. Click Close.

Setting RosterBean's Transaction Attributes

  1. Select RosterBean in deploytool's tree.
  2. Click the Transactions tabbed pane.
  3. In the Transaction Management field click, Container-Managed.

Setting the Enterprise Bean References

First, you'll set the enterprise bean reference for ejb/SimpleLeague.

  1. Select RosterBean in deploytool's tree.
  2. Click the EJB Ref's tabbed pane.
  3. Click Add.
  4. In the Add Enterprise Bean Reference dialog box:
    1. In the Coded Name field, enter ejb/SimpleLeague.
    2. In the EJB Type field, select Entity.
    3. In the Interfaces field, select Local.
    4. In the Home Interface field, enter team.LocalLeagueHome.
    5. In the Local/Remote Interface field, enter team.LocalLeague.
    6. Under Target EJB, select ejb-jar-ic1.jar#LeagueBean in the Enterprise Bean Name drop-down list.
    7. Click OK.

Next, you'll set the enterprise bean reference for ejb/SimplePlayer.

  1. Click Add.
  2. In the Add Enterprise Bean Reference dialog box:
    1. In the Coded Name field, enter ejb/SimplePlayer.
    2. In the EJB Type field, select Entity.
    3. In the Interfaces field, select Local.
    4. In the Home Interface field, enter team.LocalPlayerHome.
    5. In the Local/Remote Interface field, enter team.LocalPlayer.
    6. Under Target EJB, select ejb-jar-ic1.jar#PlayerBean in the Enterprise Bean Name drop-down list.
    7. Click OK.

Finally, you'll set the enterprise bean reference for ejb/SimpleTeam.

  1. Click Add.
  2. In the Add Enterprise Bean Reference dialog box:
    1. In the Coded Name field, enter ejb/SimpleTeam.
    2. In the EJB Type field, select Entity.
    3. In the Interfaces field, select Local.
    4. In the Home Interface field, enter team.LocalTeamHome.
    5. In the Local/Remote Interface field, enter team.LocalTeam.
    6. Under Target EJB, select ejb-jar-ic1.jar#TeamBean in the Enterprise Bean Name drop-down list.
    7. Click OK.
  3. Select FileRight ArrowSave.

Packaging the Enterprise Application Client

To package the application client, do the following:

  1. Create a new application client in RosterApp by selecting FileRight ArrowNewRight ArrowApplication Client.
  2. In the JAR File Contents screen:
    1. Select RosterApp under Create New AppClient Module in Application.
    2. Enter RosterClient under AppClient Name.
    3. Click Edit Contents.
    4. Navigate to <INSTALL>/j2eetutorial14/examples/ejb/cmproster/build/.
    5. Select the client directory.
    6. Click Add.
    7. Click OK.
    8. Click Next.
  3. In the General screen:
    1. Select client.RosterClient under Main Class.
    2. Select (Use container-managed authentication) under Callback Handler Class.
    3. Click Next.
  4. Click Finish.

Setting the Enterprise Bean Reference

You must map the coded JNDI name in the client to the RosterBean stateful session bean. To do this, follow these steps:

  1. Select RosterClient in deploytool's tree.
  2. Select the EJB Ref's tabbed pane.
  3. Click Add.
  4. In the Add Enterprise Bean Reference dialog box:
    1. In the Coded Name field enter ejb/SimpleRoster.
    2. In the EJB Type field, select Session.
    3. In the Interfaces field, select Remote.
    4. In the Home Interface field, enter roster.RosterHome.
    5. In the Local/Remote Interface field, enter roster.Roster.
    6. Under Target EJB, select JNDI Name.
    7. Select RosterBean under JNDI Name.
    8. Click OK.
  5. Select FileRight ArrowSave.

Deploying the Enterprise Application

You can now deploy the enterprise application by following these steps:

  1. Select ToolsRight ArrowDeploy.
  2. In the Deploy Module RosterApp dialog box enter the user name and password.
  3. Under Application Client Stub Directory, check Return Client Jar.
  4. Confirm that the path in the field below the checkbox is <INSTALL>/j2eetutorial14/examples/ejb/cmproster/. If it isn't, click Browse and navigate to <INSTALL>/j2eetutorial14/examples/ejb/cmproster/build/.
  5. Click OK.
  6. Confirm that the application deployed and started correctly and that the client stub JAR was created at <INSTALL>/j2eetutorial14/examples/ejb/cmproster/build/.
  7. Click Close.

Running the Client Application

To run the client, follow these steps:

  1. In a terminal, go to <INSTALL>/j2eetutorial14/examples/ejb/cmproster/.
  2. Type the following command:

    3. appclient -client RosterAppClient.jar

  3. In the terminal window, the client displays the following output:

    4. P7 Rebecca Struthers midfielder 777.0
    P6 Ian Carlyle goalkeeper 555.0
    P9 Jan Wesley defender 100.0
    P10 Terry Smithson midfielder 100.0
    P8 Anne Anderson forward 65.0

    T2 Gophers Manteca
    T5 Crows Orland
    T1 Honey Bees Visalia

    P2 Alice Smith defender 505.0
    P5 Barney Bold defender 100.0
    P25 Frank Fletcher defender 399.0
    P9 Jan Wesley defender 100.0
    P22 Janice Walker defender 857.0

    L1 Mountain Soccer
    L2 Valley Basketball

Note: Re-create the database tables using the create-db_common task before re-running the client.