Using the J2EE Reference Implementation

In this section, you will look at how to deploy an EJB in the J2EE Reference Implementation (RI) and how to run the simple application client.

Configuring J2EE RI

On Day 2 you were asked to install and configure the J2EE RI available, free of charge, from Sun Microsystems (at http://java.sun.com/j2ee) and build a sample database for the exercises in this book. If you have not already done so go back to Day 2 and follow the instructions for installing the J2EE RI and building the Agency case study database.

There are two approaches to building and deploying a J2EE component or application using J2EE RI:

• You can use the deploytool provided with the J2EE SDK.

• You can use the asant utility supplied with the J2EE SDK (this is a modified version of the popular Apache Ant utility from http://jakarta.apache.org/ant). The J2EE tutorial examples for J2EE SDK 1.4 are built and deployed using asant build files and asant build files are supplied for all the examples used throughout this book.

As a newcomer to J2EE, you will find it informative to use the GUI interface of deploytool for building and configuring the EAR and WAR files used to hold your EJBs, applications, and web components. As you gain more experience, you might find the speed of the asant command-line interface to be preferable. You will also find asant build files useful for scripting automated testing procedures.

The disadvantage of using asant is that you will have to write the build files yourself; not to mention hand crafting all the deployment descriptors. Many developers use deploytool once to generate the basic deployment descriptors and then save these descriptors to disk for use with asant build files. That is how most of the examples for this book were developed.

This section will show how to build and deploy J2EE components using deploytool before looking at the asant build files used for the Agency case study example. The directory structure for the book's example code was discussed on Day 2, but as a quick reminder, these are the subdirectories under the exercise directory for Day 4:

• build— A temporary directory used by the asant build files (created when needed)

• classes— The compiled class files

• dd— The deployment descriptor files used by the asant build files

• j2ee-ri— Repository for files manipulated by deploytool

• src— The Java source files

• JSP— The HTML and JavaServer Pages source files

Remember to make sure you are running the J2EE RI server and PointBase database servers and have created the Agency database before starting this exercise.

Opening the Case Study EAR File

Now you are ready to run the deploytool found in the bin directory under the J2EE_HOME directory. Start a command line window in the Day04/exercise directory and enter the command:

deploytool

You will be presented with a graphic interface for building J2EE components. If you have not set your PATH to include the bin directory under J2EE home you will have to provide the full pathname for deploytool. Windows users can use the Start, Programs, Sun Microsystems, J2EE 1.4 SDK, Deploytool menu or run

%J2EE_HOME%indeploytool

Solaris and Linux users should enter

$J2EE_HOME/bin/deploytool

In deploytool, use the File, Open menu to open the supplied agency enterprise archive (EAR) file in Day04/exercise/j2ee-ri/agency.ear. The agency application will now be displayed in the list of applications, as shown in Figure 4.2.

Figure 4.2. The Agency application loaded by deploytool.

[View full size image]

Examining the Case Study Application

You can use deploytool to examine and alter deployment descriptor information for the application and, if necessary, for individual components, such as EJBs.

After you open an EAR file, the enterprise application will be selected and deployment information appropriate to the application is available in the tabbed dialog pages in the right pane. In Figure 4.3, clicking on the key icons to the left of each item has exposed the nested structure of the information.

Figure 4.3. The Agency application loaded by deploytool.

[View full size image]

Figure 4.3 shows that the application has three components:

• An Agency JAR file containing a single Agency EJB

• A WebApp WAR file containing a simple Web Application (Web Applications are introduced on Day 12)

• A SimpleClient client application

The right General pane in Figure 4.3 shows the files comprising the Agency application as follows:

• META-INF/application.xml— The application DD as shown in Listing 4.6

• META-INF/sun-j2ee-ri.project— A proprietary J2EE RI projects file (you can ignore this)

• META-INF/sun-j2ee-ri.xml— A J2EE RI platform-specific DD (discussed in the section “Defining the Platform-Specific Settings”)

• agency-session-ejb.jar— The JAR file for the Agency EJBs

• app-client-ic.jar— The JAR file for the application client

• webagency.war— The WAR file for the Web Application

The remaining tabbed dialog-pages in the application pane will be discussed in later days in this book.

With the agency application selected in the left pane you can use the Tools, Descriptor Viewer, Descriptor Viewer menu option to examine the application.xml deployment descriptor shown in Listing 4.6. You can also use the Tools, Descriptor Viewer, Application Server Descriptor… menu to view the Sun Specific deployment descriptor.

Figure 4.4 shows the EJB JAR specific information with the contents of the JAR file expanded in the right pane.

Figure 4.4. Details of the Agency JAR file.

[View full size image]

The right General pane in Figure 4.4 shows the files that compose the Agency EJB JAR:

• META-INF/ejb-jar.xml— The EJB DD

• META-INF/sun-ejb-jar.xml— The Sun Specific EJB DD

• META-INF/sun-j2ee-ri.project— A proprietary J2EE RI projects file (you can ignore this)

• agency/Agency.class— The Agency Session bean remote interface (see Listing 4.1)

• agency/AgencyBean.class— The Agency Session bean itself (see Listing 4.3)

• agency/AgencyHome.class— The Agency Session bean home interface (see Listing 4.2)

• agency/DuplicateException.class— Supporting class for the Agency Session

• agency/NotFoundException.class— Supporting class for the Agency Session

With the Agency EJB JAR file selected in the left pane you can use the Tools, Descriptor Viewer, Descriptor Viewer menu option to examine the ejb-jar.xml deployment descriptor shown in Listing 4.5. You can also use the Tools, Descriptor Viewer, Application Server Descriptor… menu to view the Sun Specific EJB deployment descriptor.

Drilling down further into the EJB, Figure 4.5 shows the Agency Session bean itself.

Figure 4.5. Details of the Agency Session bean.

[View full size image]

In Figure 4.5 the General tab shows the bean type and component classes for the Agency Session bean. This information is provided when the bean is created and cannot be changed thereafter. Creating a Session bean is discussed on Day 5. However, most of the configuration information for a bean can be changed through the remaining tabbed dialog pages shown in Figure 4.5.

Table 4.1 shows the basic categories of information that can be provided for an EJB.

Figure 4.6. Agency name stored as an environment entry.

[View full size image]

Figure 4.7. Agency database Resource Reference.

[View full size image]

The Agency EJB illustrates common requirements for most EJBs. The use of environment references is shown in Figure 4.6, where the displayable Agency name is stored as a String environment reference. The data source definition for the Agency database is shown in Figure 4.7.

Finally, you can examine the simple application client in the Agency EAR file. In Figure 4.8, the main dialog page for an application client has been selected to show the entry for the Main Class name.

Figure 4.8. Simple Client for the Agency application.

[View full size image]

In Figure 4.8, you can see that an application client has similar configuration requirements as an EJB. Most of the tabbed dialog pages available are the same as those for an EJB. Figure 4.9 shows the configuration of the Agency Session EJB reference defined for the simple client.

Figure 4.9. Agency Session EJB Reference.

[View full size image]

Verifying the Case Study Application

The J2EE RI comes with a verifier utility that you can use to validate the contents of an EAR file. The verifier can be run from the command line or it can be invoked from the Tools, Verify J2EE Compliance… menu option from within deploytool.

verifier j2ee-ri/agency.ear

asant verify-j2ee-ri

%J2EE_HOME"inverifier

You are advised to run verifier on all new EAR files or when changes have been made to any of the files composing an EJB. To illustrate the use of the verifier, Figure 4.10 shows the errors produced by a simple mistake in coding the AgencyBean.java class; in this case the ejbCreate() method was mistakenly defined as create().

Figure 4.10. verifer errors from a missing ejbCreate() method in AgencyBean.java.

[View full size image]

Running the verifier from within deploytool produces a list of failed tests or a brief “There were no failed tests” message. Selecting each failed test in turn will supply further information about the test. In Figure 4.10 the message indicates the following:

[agency.AgencyBean] does not properly declare at least one ejbCreate() method

A simple mistake can cause the failure of many tests, so do not be alarmed if you see a large number of test failures.

After you have written, packaged up your application, and verified the application contents, you are ready to deploy.

Deploying the Case Study Application

You can deploy the server-side components of the agency application using deploytool. To deploy the agency application, select the agency application item (indicated by a blue diamond under the Applications folder in the explorer area in the left-hand panel), and select the Tools, Deploy… menu. This will display the initial deployment screen shown in Figure 4.11.

You will need to provide the administrative username and password (admin and password if you installed the J2EE SDK as described on Day 2). You should also check the Return Client Jar box on the dialogue to ensure your Application Client Jar file is downloaded from the J2EE server. Accept the default location for the client JAR file (this will be the same directory as the EAR file).

Click on OK to proceed with deploying your application and then click Close on the popup window when the deployment completes.

This is the point at which things might go wrong. If you are using the software from the Web site, you should have no trouble, but if you are developing your own example then you might come across problems at this stage. The “Troubleshooting Deployment” section, later on, discusses problems that might occur at deployment. If something does go wrong, study the information in the deployment progress window and also look at the J2EE console window for additional, more detailed information.

Running the Application Client

After you have successfully deployed the server-side components of the application under the J2EE RI, you can run the simple application client to test the application.

To run an application client you must have obtained the client-side JAR file from the deployed application. You did this when you deployed the application by checking the Return Client Jar… box on the deployment popup window. You can also obtain the client JAR file using either deploytool, the Web-based Admin Console, or the command line asadmin utility as described in the following section “Managing J2EE RI Applications.”

The client JAR file contains all the client and EJB class files as well as the RMI stub files required to run the application client.

You run a J2EE RI application client using the appclient command (from the J2EE SDK bin directory). The appclient requires the name of the client JAR as its single –client parameter. Assuming you have followed the deployment process described in the previous section, your returned client JAR file will be in the Day02/exercise/j2ee-ri directory and called agencyClient.jar.

You can run your deployed client as follows (your command entry is shown in bold):

							appclient -client j2ee-ri/agencyClient.jar
Welcome to: J2EE in 21 Days Job Agency
Customer list: J2EE in 21 Days Job Agency
abraham
alfred
george
winston

Done

The client JAR file is always named after the application by appending Client.jar to the name of the application.

Congratulations, you have just deployed and run your first J2EE application. If the client fails to run, then look at the errors on the console window or in the domains/domain1/logs/server.log file in the J2EE SDK home directory for more information.

If you want to examine the simple Web Application you deployed with the EJB, then browse to the URL http://lcoalhost:8000/webagency. You will look at Web Applications in detail on Days 12, 13, and 14.

Managing J2EE RI Applications

You can manage J2EE RI applications using any of the following interfaces:

• deploytool

• The asadmin command line utility

• The Admin Console web application (http://localhost:4848/asadmin/)

Using deploytool you can obtain a list of deployed objects by selecting the localhost:4848 entry under Servers in the left pane and a list of deployed components will be displayed, as shown in Figure 4.12.

Figure 4.12. Managing J2EE Deployed Objects with deploytool.

[View full size image]

You can start, stop and undeploy an object using the appropriate buttons on this dialog.

Should you need to retrieve a client JAR file from a deployed application you can do this by selecting your application, clicking on the Client Jar… button and specifying a directory location on the popup dialogue window.

If you prefer to work from the command line, then you can use the asadmin utility. To deploy an application you use the asadmin deploy command. To deploy the example EAR file you have been viewing use the command

asadmin deploy --user admin --force j2ee-ri/agency.ear

You need to specify the name of your administrative user and the EAR filename; the --force option forces a redeployment if the application has already been deployed. You will be prompted for the administrative password unless you have stored this password in a configuration file, or as an environment variable, as described on Day 2 under the installation instructions for the J2EE SDK.

If you want to return the client JAR file when deploying an application use a command such as:

asadmin deploy --user admin --force --retrieve j2ee-ri j2ee-ri/agency.ear

The --retrieve option requires the name of the directory for the client JAR file; the client JAR filename is derived from the application name as described previously.

You can retrieve the client JAR file for a previously deployed application using the get-client-stubs command to asadmin as follows:

asadmin get-client-stubs --user admin --appname agency j2ee-ri

This command requires the application name (--appname option) and the target directory for the client JAR file.

As discussed on Day 2 asadmin will provide useful help messages when an invalid command is entered. And, you can always use the --help option to get more information. For example:

asadmin -help
asadmin deploy -help
admin get-client-subs --help

Finally, you can administer deployed applications using the J2EE RI Admin Console at http://localhost:4848/asadmin/. Select the Applications, Enterprise Applications option in the left pane to deploy and undeploy applications as shown in Figure 4.13.

Figure 4.13. Using the J2EE RI Admin Console to Manage J2EE Components.

[View full size image]

You can only stop, start, deploy and undeploy applications using the Admin Console interface; you cannot return client JAR files.

Case Study asant Build Files

As an alternative to using deploytool to build and deploy J2EE components, you can use Apache Ant (sometimes called Jakarta Ant) to assemble the EAR or WAR files from the constituent components. Ant is a Java-based, open source, automated build tool that is quickly becoming the de facto standard build tool for Java programmers. A version of Apache Ant, called asant, is included with the J2EE SDK and example asant build files are supplied with the J2EE 1.4 Tutorial examples. A discussion on writing the Ant build files required to assemble a J2EE archive is outside the scope of this book, but the online Ant documentation at http://ant.apache.org/manual/index.html gives a good introduction to writing build files. Alternatively you could check out the book Extreme Programming with Ant from SAMS Publishing.

On the accompanying Web site, asant build files have been provided to compile and package the EAR and WAR files used throughout this book. As described in Day 2, each working directory contains a build.xml file that defines the asant build targets appropriate for the directory.

The build.xml file in the Day04/exercise directory will build, deploy, and run the simple client example. In order to help you use asant with the case study, each build.xml file contains a help build target that will tell you which targets you can use for each directory, this is also the default asant target. Run the following command from the Day04/exercise directory to see what targets are available:

asant

To remove all the temporary files and then compile and build the case study from scratch, use the command

asant clean build

The generated agency.ear file is stored in the build subdirectory and is kept separate from the supplied agency.ear file in the j2ee-ri directory. The various deployment descriptors used to build the EAR file are kept in the dd/agency subdirectory.

You can verify the built application using the command

asant verify

The verification results from this command are stored in the file build/agency.ear.txt.

To deploy the case study from the build directory, use the command

asant deploy

This will return the client JAR as build/agencyClient.jar. To run the simple client example, use the command

asant run

You should see the following output:

...
appclient:
     [echo] (build) appclient.bat -client agencyClient.jar -name SimpleClient
     [exec] Welcome to: J2EE in 21 Days Job Agency
     [exec] Customer list: J2EE in 21 Days Job Agency
     [exec] abraham
     [exec] alfred
     [exec] george
     [exec] winston

     [exec] Done

To undeploy the agency example use

asant undeploy

If you want to use deploytool to build the EAR file but work at the command line to verify, deploy and run the examples, then you can use the following commands.

Verify the deploytool maintained agency.ear file in the j2ee-ri sub-directory with

asant verify-j2ee-ri

Deploy and return the j2ee-ri/agencyClient.jar file with

asant deploy-j2ee-ri

Run the application client (in the j2ee-ri sub-directory) using

asant run-j2ee-ri

To undeploy the agency example you still use

asant undeploy

Troubleshooting the Case Study Application

If you have encountered difficulties running the case study application, the following may help you in resolving your problems:

• Have you started the J2EE RI?

  If you are not sure, try locating its console window or looking for it in the list of processes or applications on your machine. Try browsing to http://localhost:4848 to view the Admin Console.

• At J2EE RI install time did you define the HTTP server port to be a different value to 8000?

  Try browsing to http://localhost:8000 to verify you are using port 8000. If you selected a different HTTP server port number you will have to use your value rather than 8000 as shown in all the examples in this book.

• Have you started the PointBase database?

  Try running the initial database test at the end of Day 2 exercise to ensure that the data is present and that the database server is running.

• Have you verified the EJBs?

  Use the asant build files to run the command line verifier. Run either

  asant verify
  

  or

  asant verify-j2ee-ri
  

  as discussed in the section “Case Study asant Build Files.”

• 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. Check that you application has been deployed using the Admin Console application at http://localhost:4848/asadmin.

• Have you retrieved the client JAR file after deploying your application?

  Retrieve your application client using

  asant deploy-j2ee-ri
  

• Does the J2EE RI console window show any exceptions or errors?

• Does the J2EE server.log file under the /domains/domain1/logs directory in J2EE_HOME show errors?

If you still have problems and you suspect there is a problem with the configuration of your J2EE RI, you can re-install, or you could try manually removing the deployed applications. You will find manually removing the applications easier than re-installing.

To manually remove an EJB component, you must perform the following steps, which are described in detail following this list:

You can stop the J2EE server using the command

asadmin stop-domain

or simply close down the J2EE RI window.

Once the J2EE RI has stopped you will be able to edit the configuration to manually remove an offending application.

In the J2EE home directory there is a domains sub-directory, inside which is a domain1 directory. Find the applications/j2ee-apps directory, and beneath this a subdirectory for each deployed application. Delete the offending application directory. Make sure you do not delete the supplied MejbApp and __ejb_container_timer_app directories, otherwise you will need to reinstall the J2EE RI.

In the domains/domain1 directory in the J2EE_HOME directory there is a config directory and a file called domain.xml. For safety, take a backup copy of this file before changing it. Now edit the domain.xml file and find the <applications> tag element (near the start of the file). Look for a nested <j2ee-application> with a name attribute matching your application, the entry for the example agency application will look like

<j2ee-application enabled="true"
    location="${com.sun.aas.instanceRoot}/applications/j2ee-apps/agency"
    name="agency"
    object-type="user"/>

Delete the <j2ee-application> element for your application. Make sure you do not delete the <applications> element itself or corrupt any other part of this file.

Restart the J2EE server and (hopefully) everything will still work and you can try deploying your application again. If you still have problems, your only option is to remove the J2EE SDK, reinstall and start again.