Introduction to EJBs: Part 4
Deploying the Case Study Application
You can deploy the server-side components of the agency application (in this case, a single EJB) using deploytool. To deploy them, select the agency application item (indicated by a blue diamond under the Applications folder in the explorer area on the left side), and select Tools, Deploy from the deploytool menu. This will display the initial deployment screen shown in Figure 4.8.
As you can see from Figure 4.8, the default target host is localhost. This is fine, presuming that your copy of the J2EE RI is running on the local machine. If not, you should Cancel and add the appropriate server name through the File, Add Server menu item before proceeding.
You can select a server on which to deploy an enterprise application.
If you are deploying the agency application on an other machine (not localhost), you should not use the pre-provided agencyClient.jar file. Instead, select the option to return the client JAR file and add this JAR to the classpath when you run the client later.
Click Next to move on to the JNDI Names screen. This gives the deployer another chance to provide server-specific deployment information. Note that this is the same information you saw earlier when examining the application's JNDI information. For now, just click the Next button. At the last screen, click Finish to deploy the application to the selected server.
The progress of the deployment is shown in a separate window, as seen in Figure 4.9. The blue and green bars are progress bars that will increase as the deployment proceeds. Click OK when the deployment is complete.
When you are done, the agency enterprise application should have been deployed, as shown in Figure 4.10. To view the applications deployed on a server, expand the Servers folder in the explorer area on the left side and then expand the particular server, such as localhost.
deploytool will show you the progress of the deployment.
You can list the applications deployed on a server.
Testing the Case Study Application
After you have successfully deployed the server-side components of the application under the J2EE RI, you can run the test client to check that everything is okay.
The test client, client.SimpleClient, is provided pre-compiled in the classes subdirectory. To run this, use the script/batch file runSimple that can be found in the run subdirectory. When you run the client, you will need to provide a username and password. Use the username guest with a password of guest123. Your interaction with the client should look something like the following:
Initiating login ... Username = null Enter Username:guest Enter Password:guest123 Binding name:´java:comp/env/ejb/Agency´ Welcome to: J2EE in 21 Days Job Agency Customer list: J2EE in 21 Days Job Agency abraham alfred george winston Unbinding name:´java:comp/env/ejb/Agency´
If you are not able to run this test, refer to the "Troubleshooting the Case Study Application," section next.
As you can see, this has used the Agency EJB to list all of the customers in the job agency database. The code for the client is provided in the client sub-directory of the src directory. If you examine it, you will see that it is identical to the code shown earlier, but with some extra code to invoke the customer listing methods on the EJB and display the results.
If you examine the runSimple script/batch file, you will see that it uses the runclient utility provided by the J2EE RI as follows:
runclient -client agency.ear -name SimpleClient -textauth
The precise command line used will differ between platforms to define the location of the agency EAR file using the correct direction of slashes (backslash or forwardslash). However, this makes no difference in how the command works.
This runs the client application directly from the EAR file without having to unpack it. The command line specifies that the client is called SimpleClient and that it lives in the agency.ear archive. It also specifies that simple, text-based authentication should be used between the client and the server.
The other thing to note in the script/batch file is that the environment variable APPCPATH is set before runclient is called. The runclient utility uses this environment variable to find the client JAR file for the application (in this case, it points to agencyClient.jar). This information will be needed at runtime, not only because the EJB's interface class files are needed, but also because it also contains RMI stubs that are targeted at the correct server and deployment information that is used to map resource names to the target server's JNDI names.
Should you need to re-compile the client, or to compile your own client, you will need to add this client JAR file to your classpath.
Initial Naming Context for the Client
When creating a JNDI InitialContext, the client runtime must get hold of information regarding the content of this initial context. In the case of runclient, it will find mappings in the deployment descriptors contained in the client JAR file. These mappings will be used to set up the initial context for the client. Consequently, when the client gets a new initial context and looks up java:comp/env/ejb/Agency, for example, the local naming service runtime will be able to use the pre-provided mapping information to match this text string to the appropriate JNDI name.
Other application servers may use different mechanisms to set up this initial context, such as passing a Properties object to the naming runtime containing the appropriate information.
Troubleshooting the Case Study Application
If you have problems running the case study application, check out the following possible issues:
Have you started the J2EE RI (j2ee -verbose)? Make sure by locating its console window or looking for it in the list of processes or applications on your machine.
Have you started the cloudscape database (cloudscape -start)? Try running the initial database test at the end of Day 2 to ensure that the data is present and that the database server is running.
Have you deployed the EJBs? By opening the EAR file, you are simply loading the enterprise application into the deploytool environment. You must explicitly deploy the application to the server you are using through the Tools, Deploy menu.
Have you set the classpath correctly for your client? The client will need access to the J2EE libraries in order to run.
Try re-creating the client JAR file when you deploy the J2EE application to your server. Make sure that this client JAR file is on the classpath when you compile and run the client application.
Check the J2EE RI console window to see if exceptions or errors are shown there.
Check the J2EE log files under the logs directory in J2EE_HOME. There is a directory below logs that is named after the machine on which the server is running. Below this, there are two nested j2ee directories. In the lower of these, you will find various log files that you can examine for errors.
If you still have problems and you suspect that there is a problem with the configuration of your J2EE RI, you can either re-install the RI or you could try deleting the server- specific repository directory and then re-starting your server. You will lose all of your deployed J2EE applications, but you may find this easier than re-installing. Under the J2EE_HOME directory, you will find a directory called repository, and below this there will be a directory named after the server on which you are running this instance of the RI (for example, if your hostname is "fred", there will be a fred directory below repository). Stop the J2EE RI, remove the directory that is named after your server, and then start the J2EE RI again.
Today, you have seen common ways that EJBs are used in applications and why you would want to use them. You have seen that an EJB will have a home interface, a business or remote interface, and an implementation. You have seen how the EJB container will provide much of the underlying code to support the EJB, and that it relies on detailed deployment information that defines the EJB's requirements.
You have also seen that a J2EE application consists of components and deployment information and how the server-side part of such an application can be deployed. You have seen a client that is able to use such server-side components and the code required to write such a client.
How many Java classes and interfaces must I write to create an EJB?
The EJB writer must define a remote (or business) interface, a home interface, and the bean implementation itself.
Why does an EJB run inside a container?
The container provides many services to the EJB, including distribution, lifecycle, naming/registration, transaction management, security/authentication, and persistence. If the container did not exist, you would have to write all the code to interact with these services yourself.
What issues surround passing an object as part of a remote method call?
To be passed as an argument or return type, an object must be either serializable or remote. If it is neither of these, an error will occur at runtime. If an object is defined as serializable, a new copy will be created and passed/returned. This can add to the overhead of making the method call, but it is a very useful tool when trying to cut down the amount of network traffic between clients and EJBs (as you will see later on Day 18).
Most of the deployment descriptor information is straightforward, but what is the difference between a <resource-ref> and an <env-entry>, and what sort of information is contained in each type of entry?
A <resource-ref> is part of a deployment descriptor that defines an external resource used by a J2EE component. The <resource-ref> will define a name and type for a resource together with other information for the container. The information in a <resource-ref> is really for the container rather than for the EJB itself. To access a resource defined in a <resource-ref>, you would use JNDI to look up its name java:comp/env/jdbc/Agency.
On the other hand, an <env-entry> contains information that is intended for the EJB itself rather than the container. It will define a name, a class type and a value. The contents of <env-entry> elements are usually strings. Again, you would use JNDI to look up its name, java:comp/env/AgencyName.
The intention of this day is for you to familiarise yourself with the EJB environment and the use of EJBs. To ensure that you are comfortable with these areas, you should attempt the following tasks.
If you have not already done so, follow the steps to deploy the example Agency EJB from the Day 4 Exercise directory on the CD-ROM.
Examine the information displayed by deploytool and make sure that you can identify where the resource reference for the Agency JDBC connection is set, where the environment reference for the agency name is set, and where the JNDI name of the Agency EJB itself is set.
Use the runSimple script/batch file provided under the Day 4 Exercise directory on the CD-ROM to run the test client. Make sure that this client runs without errors and successfully lists all the customers in the agency database.
Without referring to the example client (but referring to the material you have covered today), create your own simple test client for the Agency EJB from scratch. This should just consist of a command-line client that creates an instance of an Agency EJB and asks it for its name.
Try changing the name under which the EJB is registered in JNDI using deploytool. Change the JNDI name used by your client to find the Agency EJB and make sure that it still works.