Exercises

About the exercises

These exercises are designed to provide help according to your needs. For example, you might simply complete the exercise given the information and the task list in the exercise body; you might want a few hints; or you may want a step-by-step guide to successfully complete a particular exercise. You can use as much or as little help as you need per exercise. Moreover, because complete solutions are also provided, you can skip a few exercises and still be able to complete future exercises requiring the skipped ones.

Each exercise has a list of any prerequisite exercises, a list of skeleton code for you to start with, links to necessary API pages, and a text description of the exercise goal. In addition, there is a help page, with help for each task, and a solution page with links to files that comprise a solution to the exercise.

Exercise 1. How to install and configure Sun's J2EE
Reference Implementation: Tasks

This exercise steps you through the process of downloading and installing Sun's Java 2 Enterprise Edition Reference Implementation application server on your machine. This exercise is specific to the J2EE RI. If you want to use a different application server for the remainder of these exercises, then you should ensure it is EJB 1.1 compliant and install it now.

Prerequisites
* None

Task 1: Check your system requirements to make sure you have an adequate hardware and software platform for installing and running J2EE RI.

Task 2: Ensure you have the Java 2 SDK version 1.2.2 or higher installed on your machine.

Task 3: Download the J2EE RI server and documentation from Sun's J2EE download site . The software distribution and the documentation site include installation instructions.

Task 4: Run the installer for both the J2EE and the documentation.

Task 5: Set the J2EE_HOME environment variable to point to the base directory where you installed the J2EE RI.

Task 6: Put J2EE_HOME/bin into your PATH environment variable.

Task 7: Start the Cloudscape database with the command


Task 8: Start the J2EE RI with the command


Task 9: J2EE is now installed and running. Explore the J2EE Reference Implementation documentation within the documentation site to familiarize yourself more with J2EE.

Help for each of these tasks can be found on the next panel.


Exercise 1. How to install and configure Sun's J2EE Reference Implementation: Help

Task 1: Check your system requirements to make sure you have an adequate hardware and software platform for installing and running J2EE RI.

Help for task 1: System requirements are Windows NT 4.0 or Solaris 2.5.1+. Windows 2000 and Windows 98 also are reported to work, but Sun does not yet officially support them. A minimum of 128 MB of RAM is needed to adequately complete the exercises.
Visit Sun's Web page, which lists J2EE Reference Implementation Tested Configurations for more information.

Task 2: Ensure you have the Java 2 SDK version 1.2.2 or higher installed on your machine.

Help for task 2: The J2EE RI cannot run without the full Java 2 SDK installed. The J2EE RI cannot run if the HotSpot performance engine has been installed on top of the SDK; if HotSpot has been installed, be sure to uninstall then reinstall the Java 2 SDK.

Task 3: Download the J2EE RI server and documentation from Sun's J2EE download site . The software distribution and the documentation site include installation instructions.

Help for task 3: The Windows and Solaris distributions are each approximately 11 MB. The documentation is an additional 7 MB.

Task 4: Run the installer for both the J2EE and the documentation.

Help for task 4: Double click on the installer that you downloaded in the previous step.

Task 5: Set the J2EE_HOME environment variable to point to the base directory where you installed the J2EE RI.

Help for task 5: In Windows, this may be done by the command:


Make sure to point to the proper folder for your machine.

Task 6: Put J2EE_HOME/bin into your PATH environment variable.

Help for task 6: In Windows, this may be done by the command:


Make sure to point to the proper folder for your machine.

Task 7: Start the Cloudscape database with the command


Help for task 7: cloudscape -start should produce output similar to the following:


Task 8: Start the J2EE RI with the command


Help for task 8: Running the J2EE RI via the command-line command j2ee -verbose should produce output similar to the following:


Task 9: J2EE is now installed and running. Explore the J2EE Reference Implementation documentation within the documentation site to familiarize yourself more with J2EE.

Help for task 9: There is extensive documentation on all aspects of J2EE, along with example enterprise beans API documentation for the javax.ejb packages, and other goodies.

Exercise 1. How to install and configure Sun's J2EE Reference Implementation: Solution

There is no solution to this exercise. When the tasks in this exercise have been completed, the J2EE RI will be installed, running, and available for the subsequent exercises.

Exercise 2. How to create an entity bean: Tasks

This exercise implements a MusicCD entity bean, which represents data stored in a database describing an audio CD. The MusicCD bean will be used by subsequent exercises. Prerequisites

* Exercise 1. How to install and configure Sun's J2EE Reference Implementation:

Skeleton code

* MusicCD.java
* MusicCDHome.java
* MusicCDBean.java

Task 1: Design a MusicCD remote interface and a MusicCDHome home interface. The MusicCD bean must encapsulate the persistent fields upc, title, artist, type, and price, so the MusicCD remote interface should define accessors and mutators for these persistent fields. The MusicCDHome interface should define a findByPrimaryKey() method which accepts a String argument for the upc, and a create() method that accepts a upc.

Task 2: Code the MusicCDBean entity bean implementation class. You need to provide implementations for all the methods defined in the remote interface, plus you need to implement all the methods defined in the EntityBean interface. You also need to provide an implementation of ejbCreate() with the same number and datatypes of arguments as you defined in the create() method of your home interface.


Task 3: Compile all the classes that make up your bean.

Task 4: Package your entity bean into a jar file, using the provided XML deployment descriptor.

Help for each of these tasks can be found on the next panel.

Exercise 2. How to create an entity bean: Help

Task 1: Design a MusicCD remote interface and a MusicCDHome home interface. The MusicCD bean must encapsulate the persistent fields upc, title, artist, type, and price, so the MusicCD remote interface should define accessors and mutators for these persistent fields. The MusicCDHome interface should define a findByPrimaryKey() method which accepts a String argument for the upc, and a create() method that accepts a upc.

Help for task 1: Remember that all of the methods in the remote interface must throw RemoteException and that the create() methods in the home interface must return an object of type MusicCD.

Task 2: Code the MusicCDBean entity bean implementation class. You need to provide implementations for all the methods defined in the remote interface, plus you need to implement all the methods defined in the EntityBean interface. You also need to provide an implementation of ejbCreate() with the same number and datatypes of arguments as you defined in the create() method of your home interface.

Help for task 2: MusicCDHome should prescribe a single bean-creation method with the signature:


but the implementation of this in the bean class must return null in the case of container-managed persistence.
Because MusicCDBean is an implementation of an entity bean, it has a primary key and it must have creation methods with arguments to initialize the key: create() and ejbCreate().

Task 3: Compile all the classes that make up your bean.

Help for task 3: Don't forget that the compiler needs to be able to find the javax.ejb classes, which are in J2EE_HOME/j2ee.jar. You may use the following command to compile:


Task 4: Package your entity bean into a jar file, using the provided XML deployment descriptor.

Help for task 4: Execute the command:


to create the jar file.

Exercise 2. How to create an entity bean: Solution

The following files contain a complete implementation of the MusicCD entity bean:

* solution/musicstore/MusicCD.java
* solution/musicstore/MusicCDHome.java
* solution/musicstore/MusicCDBean.java
* solution/META-INF/ejb-jar.xml

Exercise 3. How to create a stateless session bean: Tasks

This exercise implements an Inventory session bean, which can perform inventory operations via the MusicCD bean, with both beans operating in the middle-tier. Inventory-management operations are initiated by a distributed client, MusicInventoryClient.

Prerequisites

* Exercise 1. How to install and configure Sun's J2EE Reference Implementation:
* Exercise 2. How to create an entity bean:
Skeleton code
* Inventory.java
* InventoryHome.java
* InventoryBean.java
* MusicData.java

Task 1: Design a wrapper class called MusicData, that can represent the persistent fields in MusicCD (namely upc, title, artist, type, price).

Task 2: Design an Inventory session bean that provides an addInventory() service. This argument should take an array of MusicData objects as an argument. Within the addInventory() method, this bean should establish a MusicCDHome reference and then loop through the data passed as an argument to addInventory(), creating MusicCD beans and setting their attributes.

Task 3: Compile all the classes that make up your bean.

Task 4: Package your session bean into a jar file, using the provided XML deployment descriptor.

Help for each of these tasks can be found on the next panel.

Exercise 3. How to create a stateless session bean: Help

Task 1: Design a wrapper class called MusicData, that can represent the persistent fields in MusicCD (namely upc, title, artist, type, price).

Help for task 1: Don't forget to implement java.io.Serializable.

MusicData should provide a constructor for setting its instance fields with the MusicCD attributes:


Task 2: Design an Inventory session bean that provides an addInventory() service. This argument should take an array of MusicData objects as an argument. Within the addInventory() method, this bean should establish a MusicCDHome reference and then loop through the data passed as an argument to addInventory(), creating MusicCD beans and setting their attributes.

Help for task 2: InventoryHome should prescribe a single bean-creation method with the signature:


Inventory should prescribe one method only, addInventory(), with an interface similar to the following, depending on your design:


Because Inventory is a session bean, it has no primary key and its creation methods have no arguments: create() and ejbCreate().

Note that InventoryBean.addInventory() is similar to MusicClient in that it must establish a JNDI context, look up the MusicCD bean, and so on.

Task 3: Compile all the classes that make up your bean.

Help for task 3: Don't forget that the compiler needs to be able to find the javax.ejb classes, which are in J2EE_HOME/j2ee.jar. You may use the following command to compile:


Task 4: Package your session bean into a jar file, using the provided XML deployment descriptor.

Help for task 4: Execute the command:


to create the jar file.

Exercise 3. How to create a stateless session bean: Solution

The following files contain a complete implementation of the Inventory session bean:

* solution/musicstore/Inventory.java
* solution/musicstore/InventoryHome.java
* solution/musicstore/InventoryBean.java
* solution/musicstore/MusicData.java
* solution/META-INF/ejb-jar.xml

Exercise 4. How to set up the database: Tasks

As illustrated in the previous exercises, the database has a music store theme. This exercise sets up the database with one table for music CDs. This exercise includes a pre-built database for the Cloudscape database system in jar format.

Also, the skeleton code and solutions sections include programs for building the database via JDBC. Note that all utility programs associated with this project have -usage, -help, and -h command-line options.

Prerequisites
* Exercise 1. How to install and configure Sun's J2EE Reference Implementation:
Resources
* DatabaseTool.java
* MusicStoreDB.jar
* MusicCDCreateTables.java
* MusicCDInsertRecords.java

Task 1: Choose a database system appropriate for your environment and then either install or build the database system with the music data that you prefer.

Task 2: Verify the integrity of the database using a vendor-supplied graphical tool or the DatabaseTool.java program provided.

Help for each of these tasks can be found on the next panel.

Exercise 4. How to set up the database: Help


Task 1: Choose a database system appropriate for your environment and then either install or build the database system with the music data that you prefer.

Help for task 1: Sun's J2EE Reference Implementation comes with a built-in version of the Cloudscape RDBMS. If you are using J2EE RI, you should initially use Cloudscape as your database to avoid configuration problems. You can learn how to substitute a different database after you become comfortable with creating and deploying applications using Cloudscape.

If you insist on initially using a database other than Cloudscape, you should carefully read and follow the instructions in the following J2EE RI documentation before you begin:

* Configuration Guide
* Release Notes

Note that Microsoft Access doesn't provide adequate SQL support for the tasks required by EJB technology servers.

For Cloudscape, simply copy the MusicStoreDB.jar archive into the directory %J2EE_HOME%\cloudscape and then unjar the database. (All files unjar into the directory MusicStoreDB within the current working directory.)

For other database environments, simply compile and run the programs MusicCDCreateTables.java and MusicCDInsertRecords.java after creating an empty database. You can modify the source for the appropriate driver and URL values, or supply them as command-line options. You can also perform these tasks using DatabaseTool, or JDBCTest (TestTool) from the Sun's JDBC area .

One last step is needed when running with J2EE RI: You need to modify the %J2EE_HOME%\config\default.properties file to define the datasources available to J2EE RI. This is done by changing the line that reads (with everything on one line):


to be:


(with everything on one line) and then restarting both Cloudscape and J2EE RI.

Barnes and Noble and other sites provide easy access to music CD data such as UPCs, if you want to customize the MusicCD database with your own entries.

Task 2: Verify the integrity of the database using a vendor-supplied graphical tool or the DatabaseTool.java program provided.

Help for task 2: The exercise solution on the next panel has example output for the Cloudscape View tool and for DatabaseTool.java.

Exercise 4. How to set up the database: Solution

There is no explicit solution to this exercise. If you have set up the database correctly, then when you run cloudscape -start you will see output similar to the following:


Likewise, when you startup J2EE RI you should see something like the following:


Exercise 5. How to deploy enterprise beans in Sun's J2EE Reference Implementation: Tasks

This exercise takes you through the process of deploying the MusicCD entity bean and Inventory session bean into the J2EE Reference Implementation container. Deploying is usually a major task in and of itself, and it is always application-server specific. If you are using an application server other than J2EE RI, you should consult that server's documentation for the details of how to deploy your beans. You will need to have the MusicCD and Inventory beans deployed for the subsequent exercises.

Prerequisites
* Exercise 1. How to install and configure Sun's J2EE Reference Implementation:
* Exercise 2. How to create an entity bean:
* Exercise 3. How to create a stateless session bean:
* Exercise 4. How to set up the database:

Skeleton code

* Inventory.jar
* MusicCD.jar

Task 1: Save the two jar files from the skeleton code section above into your working directory. From that working directory, start the deploytool utility. This runs an application for deploying enterprise beans into a running J2EE RI server.

Task 2: In deploytool, select File/New Application... to create a new application called MusicStore saved in a file called MusicStore.ear.

Task 3: Select the MusicStore application from the list of deployed applications on the left side of the deploytool GUI. Select File/Add EJB JAR to Application... and use the dialog box to open MusicCD.jar, which is provided as the skeleton code for this exercise.

Task 4: Follow the same procedure to add the Inventory.jar to the application.

Task 5: With the MusicStore application selected, choose the JNDI panel from the main portion of the deploytool window. Fill in the JNDI names for each component as shown:

MusicCDBean	MusicCDBean	ejb/MusicCD
InventoryBean	InventoryBean	ejb/Inventory
InventoryBean	ejb/MusicCD	ejb/MusicCD

Task 6: Now set up the database mapping for the MusicCD entity bean. You will have to select the MusicCDBean component from the left window. Then select the Entity tab in the main window and click the Deployment Settings button to get the input dialog box. Set the database JNDI name to jdbc/MusicStore in this dialog, uncheck the boxes Create table on deploy and Delete table on deploy, then click the Generate SQL now button.

Task 7: The MusicStoreDB that you set up in the previous exercise uses a table called MusicCD to store the MusicCD beans. The SQL commands that the J2EE RI automatically generates do not use this exact table name, so you need to select each of the life-cycle methods and edit the SQL being generated for each to change them to operate on the MusicCD table.

Task 8: In deploytool, select Tools/Deploy Application... from the menu. Check the box to Return Client Jar, accept all the other defaults, and step through the wizard. Click the Finish button at the end.

Task 9: You should see MusicStore application show up in the lower section of the deploytool screen in the panel labeled Server Applications. You have successfully deployed your beans.

Help for each of these tasks can be found on the next panel.

Exercise 5. How to deploy enterprise beans in Sun's J2EE Reference Implementation: Help

Task 1: Save the two jar files from the skeleton code section above into your working directory. From that working directory, start the deploytool utility. This runs an application for deploying enterprise beans into a running J2EE RI server.

Help for task 1: First make sure that your J2EE RI server and database server are running. If they aren't, execute cloudscape -start and j2ee -verbose from the command-line. You will need the J2EE_HOME/bin directory in your PATH. Then you can run deploytool from the command-line. This should bring up the following screen:

Task 2: In deploytool, select File/New Application... to create a new application called MusicStore saved in a file called MusicStore.ear.

Help for task 2: The left portion of the deploytool GUI should now show MusicStore as an application:

Task 3: Select the MusicStore application from the list of deployed applications on the left side of the deploytool GUI. Select File/Add EJB JAR to Application... and use the dialog box to open MusicCD.jar, which is provided as the skeleton code for this exercise.

Help for task 3: The left portion of the deploytool GUI should now show MusicCDEJB beneath the MusicStore application as shown here:

Task 4: Follow the same procedure to add the Inventory.jar to the application.

Help for task 4: The left portion of the deploytool GUI should now show MusicCDEJB and InventoryEJB beneath the MusicStore application as shown here:

Task 5: With the MusicStore application selected, choose the JNDI panel from the main portion of the deploytool window. Fill in the JNDI names for each component as shown:

MusicCDBean	MusicCDBean	ejb/MusicCD
InventoryBean	InventoryBean	ejb/Inventory
InventoryBean	ejb/MusicCD	ejb/MusicCD

Help for task 5: You should see a list of three component with blank JNDI names. Fill in the names as shown here:

Task 6: Now set up the database mapping for the MusicCD entity bean. You will have to select the MusicCDBean component from the left window. Then select the Entity tab in the main window and click the Deployment Settings button to get the input dialog box. Set the database JNDI name to jdbc/MusicStore in this dialog, uncheck the boxes Create table on deploy and Delete table on deploy, then click the Generate SQL now button.

Help for task 6: The Entity tab will appear as follows:

jdbc/MusicStore is the JNDI name of the database you set up in the . If deploytool complains about this database name, make sure you have completed the previous exercise properly and that the J2EE RI server has been restarted since then (so that it will pick up the database you created). After this is done, it should look something like this:

Task 7: The MusicStoreDB that you set up in the previous exercise uses a table called MusicCD to store the MusicCD beans. The SQL commands that the J2EE RI automatically generates do not use this exact table name, so you need to select each of the life-cycle methods and edit the SQL being generated for each to change them to operate on the MusicCD table.

Help for task 7: See the help for the previous task to see what the screen should look like when you edit the SQL commands.

Task 8: In deploytool, select Tools/Deploy Application... from the menu. Check the box to Return Client Jar, accept all other defaults, and step through the wizard. Click the Finish button at the end.
Help for task 8: After this is done, and if the deployment was successful, you should see a dialog something like this:

Task 9: You should see MusicStore application show up in the lower section of the deploytool screen in the panel labeled Server Applications. You have successfully deployed your beans.

Help for task 9: Note that the FCS version of J2EE RI has a bug that prevents the Server Applications panel to be initially shown. Use your mouse and drag the divider bar which appears along the bottom of the screen until this panel is visible. It should look something like this:

Exercise 5. How to deploy enterprise beans in Sun's J2EE Reference Implementation: Solution

When you have sucessfully deployed the MusicStore application, your deploytool screen should look something like this:

Exercise 6. How to create EJB clients: Tasks

This exercise implements two stand-alone client applications to use the MusicCD entity bean and Inventory session bean which you developed and deployed in the previous exercises.

Note: Due to a bug in the 1.0 release of the J2EE RI, these client programs will not run properly. The J2EE RI does not conform to the J2EE specification regarding the use of compound primary keys. The J2EE RI 1.0 only works properly with single-valued primary keys. In order to make this exercise work with the J2EE RI, you will have to use the upc field of the MusicCDBean class as the primary key and remove all mention of MusicCDPK in the MusicCD entity bean, the Inventory session bean, and the clients in this exercise. This bug will be fixed in the next J2EE RI release.

For more help with exercises, see About the exercises.
Prerequisites

* Exercise 1. How to install and configure Sun's J2EE Reference Implementation:
* Exercise 2. How to create an entity bean:
* Exercise 3. How to create a stateless session bean:
* Exercise 4. How to set up the database:
* Exercise 5. How to deploy enterprise beans in Sun's J2EE Reference Implementation:

Skeleton code

* MusicClient.java
* MusicInventoryClient.java
* Inventory.jar
* MusicCD.jar

Task 1: Start the Cloudscape database server with the command:


Task 2: Start the J2EE RI with the command:


Pay attention to the output to make sure that J2EE loads the MusicStoreDB datasource that you set up in the previous exercise.

Task 3: Edit the MusicClient.java skeleton to obtain the JNDI context, and use this context to get a reference to the MusicCDHome.

Task 4: Create a new MusicCD bean with the UPC code given in the skeleton, and set its fields to the values shown in the skeleton. Or if you have a favorite CD of your own, you can use that data.

Task 5: Add code to find the MusicCD bean you just created in the database, then print out the database values of the fields you set in the previous step.

Task 6: Compile and run your client application.

Task 7: Edit the MusicInventoryClient.java skeleton to obtain the JNDI context, and use this context to get a reference to the InventoryHome.

Task 8: Create a new Inventory bean.

Task 9: Create an instance of MusicData and fill it with information about CDs you want to insert into the database, then use the Inventory bean's business method to perform this task.

Task 10: Compile and run your client application.

Help for each of these tasks can be found on the next panel.

Exercise 6. Creating EJB clients: Help

Task 1: Start the Cloudscape database server with the command:


Help for task 1: You may already have Cloudscape running from the previous exercise. If so, there is no need to start it again (in fact, you can't have two copies running). When shutting down Cloudscape, be sure to use cloudscape -stop instead of ^C.

Task 2: Start the J2EE RI with the command:


Pay attention to the output to make sure that J2EE loads the MusicStoreDB datasource that you set up in the previous exercise.

Help for task 2: Running the J2EE RI via the command-line command j2ee -verbose should produce output similar to the following:


Note in particular the lines:


that let you know that the MusicStore database is known to the J2EE server, and


that let you know the MusicStore application has been deployed.

Task 3: Edit the MusicClient.java skeleton to obtain the JNDI context, and use this context to get a reference to the MusicCDHome.

Help for task 3: Obtain the JNDI context by creating a new instance of javax.naming.InitialContext and storing it in a reference variable of datatype javax.naming.Context

Task 4: Create a new MusicCD bean with the UPC code given in the skeleton, and set its fields to the values shown in the skeleton. Or if you have a favorite CD of your own, you can use that data.

Help for task 4: Use the create() method that takes the UPC code as an argument to create the bean. Use the accessor and mutator methods defined in the remote interface to modify the bean's data.

Task 5: Add code to find the MusicCD bean you just created in the database, then print out the database values of the fields you set in the previous step.

Help for task 5: Create an instance of MusicCDPK, set the upc field to an appropriate value, and use the findByPrimaryKey() method of the MusicCD home interface to find the MusicCD bean. When you have a reference to the bean, you can read the data using accessor methods on that bean.

Task 6: Compile and run your client application.

Help for task 6: Because the client needs to use both the MusicCD bean and the Inventory bean, you will need to put Inventory.jar and MusicCD.jar in your CLASSPATH in order to compile. You will also have to make sure that j2ee.jar is in your CLASSPATH, because that is where the javax.ejb classes are stored.

Task 7: Edit the MusicInventoryClient.java skeleton to obtain the JNDI context, and use this context to get a reference to the InventoryHome.

Help for task 7: You obtain the JNDI context by creating a new instance of javax.naming.InitialContext and storing it in a reference variable of datatype javax.naming.Context.

Task 8: Create a new Inventory bean.

Help for task 8: Use the create() method on the Inventory home interface.

Task 9: Create an instance of MusicData and fill it with information about CDs you want to insert into the database, then use the Inventory bean's business method to perform this task.

Help for task 9: The addInventory() method of the Inventory bean takes an instance of MusicData as an argument, and inserts those records into the database.

Task 10: Compile and run your client application.

Help for task 10: Because the client needs to use both the MusicCD bean and the Inventory bean, you will need to put Inventory.jar and MusicCD.jar in your CLASSPATH in order to compile. You will also have to make sure that j2ee.jar is in your CLASSPATH, because that is where the javax.ejb classes are stored.

Exercise 6. How to create EJB clients: Solution

As a solution, both the source code for the client applications and the MusicStoreClient.jar file, which holds the container-generated stubs and skeletons and other things needed for a stand-alone client to communicate with the J2EE server, are provided.

* solution/musicstore/MusicClient.java
* solution/musicstore/MusicInventoryClient.java
* solution/MusicStoreClient.jar

---