Currency Converter EJB
J2EE Developer's Guide Samples on iPlanet Application Server

Updated June 8, 2001

This sample is based on the Currency Converter EJB sample included in Sun's J2EE Developer's Guide, version 1.2.1 . The following instructions describe how to assemble and deploy the same EJB to iPlanet Application Server and how to access the EJB from both a simple Java client application using RMI/IIOP as well as from a Servlet client using HTTP. Although the client application and EJB offer minimal functionality, this sample should provide you with a basic understanding of RMI/IIOP support in iPlanet Application Server.

Setting Up the Environment

Getting Started includes a checklist of prerequisites for deploying sample applications to iPlanet.

J2EE Developer's Guide Samples Notes describes special considerations when deploying these sample.

Enable RMI/IIOP Support in the application server. (Performed automatically in a Test Drive installation).

Deploying and Running the Application

Select one of two approaches to deploying the application:

Command Line-based Deployment describes how to manually register the application in iPlanet using a Command Line Interface (CLI). This is the fastest means of deploying the application.

GUI-based Deployment describes how to use the iPlanet Deployment Tool to import and deploy the application. It also addresses assembling the application from scratch using the Deployment Tool.

Deploying the Client Application describes how to deploy the Java client application.

Running the Application describes how to start the application, navigate through it and how to troubleshoot in the event of problems.

Further Exploration

Compiling and Assembling the Application describes how to use command line tools to recompile the sources and rebuild the WAR and EJB modules and the overall EAR file.

Command Line-based Deployment

You have a choice of deploying and registering the application through either command line utilities or the iPlanet Application Server Deployment Tool GUI. Since a complete EAR file is supplied, the fastest means of setting up the application is to use the command line utilities as described in this section. If you would like to experience either deploying through a GUI tool or assembling an application from scratch, then follow instructions in GUI-based Deployment.

The pre-built j2eeguide-converter.ear file is a Enterprise ARchive file that contains the Web Archive (WAR) and EJB JAR files for the Converter application. Within each of these JAR files reside the XML deployment descriptor files, application class files, JSPs and other content required by the application.

Deploying the pre-built j2eeguide-converter.ear file is simple.

1. Go to the root of the Converter sample directory:

install_dir/ias/ias-samples/j2eeguide/converter/

2. Execute iasdeploy to deploy application to the local application server instance:

iasdeploy deployapp j2eeguide-converter.ear

Refer to the Getting Started section for more information on using the iasdeploy command.

The deployment process involves the following operations:

iasdeploy authenticates against the local application server's administrative server.
the EAR file is transferred to the administrative server.
the administrative server begins the registration process:
- parses the EAR file and embedded WAR and EJB JAR files
- registers the J2EE application "j2eeguide-converter" in the iPlanet Registry within the directory server
- registers the embedded J2EE modules (WARs and EJB JARs) in the iPlanet Registry within the directory server
- extracts the EJB JAR and WAR modules to the JAR/ directory.
- expands the content of the J2EE modules to the APPS/j2eeguide-converter/ directory.

Now you're ready to exercise the application by Deploying the Client Application.

GUI-Based Deployment

The Deployment Tool provides an easy-to-use means of assembling J2EE applications and deploying applications to iPlanet Application Server. For most cases, use of Deployment Tool is recommended over the approach of manually creating XML-based deployment descriptors and manually assembling J2EE modules and application JAR files.

Two approaches to using the Deployment Tool are described:

Import Pre-existing EAR File to quickly deploy the application to iPlanet using the Deployment Tool. None of the application assembly steps are covered by this section. On average, this approach will take 10 minutes.
or
Assemble the Application to learn how to use Deployment Tool to assemble the application from scratch and to deploy it to the application server. On average, this approach will take from 15-25 minutes.

Import Pre-existing EAR File

Since a pre-built Enterprise ARchive (EAR) file for the Converter application is shipped with the application server, you can use the Deployment Tool to quickly read in the .ear file, modify deployment settings and deploy to the application server.Open the pre-existing sample EAR file.

1. Launch the Deployment Tool.

UNIX:
Execute install_dir/ias/bin/deploytool
Windows:
Start->Programs->iPlanet Application Server 6.0->iAS Deployment Tool

2. Open the EAR file

In the startup dialog, select "Browse for more applications" to find the j2eeguide-converter.ear file.
Navigate to ias/ias-samples/j2eeguide/converter/ and open the j2eeguide-converter.ear file.
Select Component View
Click on the file name to expand the EAR file.

Proceed to Deploying the Application

Assemble Converter Application

These instructions describe how to assemble the Converter application from scratch using only the compiled source files and the Deployment Tool.

Compile Application Sources
Create EJB JAR Module
Create WAR Module
Assemble EAR File
Deploy Application

1. Compile Application Sources

To compile the application sources, simply execute "build compile" under the application's src/ directory. See the section Compiling and Assembling the Application for more information on recompiling the application using the supplied build facility.

2. Create EJB JAR Module

Insert EJB Classes

1. Create assembly location:

Create the new directory install_dir\ias\ias-samples\j2eeguide\converter\assemble\ outside the Deployment Tool. You will assemble the application into JAR files and save them to this directory.

2. Launch the Deployment Tool:

UNIX: Execute install_dir/ias/bin/deploytool&
Windows: Programs->iPlanet Application Server 6.0->iAS Deployment Tool

3. Create j2eeguide-converterEjb.jar:

In the startup dialog, select New EJB Application (.jar file)
Alternatively, if Deployment Tool is already started, select File -> New.
Click on EJB JAR Module.
Enter "j2eeguide-converterEbj.jar" as the archive file name.
Click on Browse to navigate to the directory install_dir\ias\ias-samples\j2eeguide\converter\assemble\
Click on OK to exit the dialog window.
The EJB JAR module appears in the EJB pane of the Deployment Tool window.
Click on Component View to see only the name of the EJB JAR module without the directory path.

4. Now insert all class files needed in the j2eeguide-converterEjb.jar file:

Select the EJB JAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
Choose the path install_dir\ias\ias-samples\j2eeguide\converter\build\classes. (Merely select the "classes" folder. Do not drill down into the classes folder).
In the left hand pane, select all classes except for the servlet class files. Click on the double arrows (>>) to move the selected classes into right side of the dialog window. For this sample, we're placing all of the class files save for servlet classses in the EJB JAR module and only servlet classes in the WAR module.
Click on Resolve to determine if any of the included classes depend on classes that are not part of the EJB JAR module. (You'll notice that the classes change from red to blue as they are resolved. Any files remaining as red are dependent on classess not included in the EJB JAR module. The unresolved references do not inhibit you from adding the classes to the EJB JAR module.) You might encounter a warning of unresolved class dependencies. Click on Resolve again to attempt the resolution again.
Click on Insert to add the classes to the EJB JAR module.
Since you selected Component View, you'll see the EJB listed in the EJB module window. Deployment Tool introspects the classes to determine the EJBs, if any, contained in the inserted classes.
Click on File View to see the complete list of files added to the module.

Modify Deployment Descriptor Settings for Converter EJB

1. Modify Descriptor for Converter EJB

Click on Component View.
Select the ConverterEJB component, right mouse click and select Edit Descriptor.
Adjust the EJB descriptor window size to see all of the settings.
Note the unique GUID (Globally Unique IDentifier) assigned to the EJB. This ID is used by the application server to manage the EJB as a unique component throughout the application server.
The next steps in this section lead you through modifications to the EJB descriptor.

2. Begin Modifying the Converter EJB Descriptor

Set Bean Name to MyConverter
Set Transaction Management Type to Bean
Set State Management Type to Stateless
Click on Enable RMI/IIOP

3. Close the Descriptor for the EJB

Now we can close the EJB descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes.

Save and close j2eeguide-converterEjb.jar

Before closing the EJB JAR file, you might find it useful to double check your settings against the previous instructions.
Select the j2eeguide-converterEjb module in the EJB Modules window.
Select File->Close to save and close the j2eeguide-converterEjb.jar file.

Now that we've assembled the EJB JAR module, we're ready to move on to assembling the Web Application aRchive (WAR) file.

3. Create WAR Module

Identify the Content for WAR File

1. Create j2eeguide-converter.war:

In the startup dialog, select New Web Application (.war file)
Alternatively, if Deployment Tool is already started, select File -> New.
Click on Web Application.
Enter "j2eeguide-converter.war" as the archive file name.
Click on Browse to navigate to the directory install_dir\ias\ias-samples\j2eeguide\converter\assemble\
Click on OK to exit the dialog window.
The WAR module appears in the Web Applications pane of the Deployment Tool window.
Click on Component View to see only the name of the WAR module without the directory path.

2. Now insert all class files needed in the j2eeguide-converter.war file:

Select the WAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
Choose the path install_dir\ias\ias-samples\j2eeguide\converter\build\classes\j2eeguide\converter
Click on the double arrows (>>) to move the servlet class into right side of the dialog window.
Click on Resolve to determine if any of the included classes depend on classes that are not part of the WAR module.
Click on Insert to add the classes to the WAR module.
Click on File View to see the complete list of files added to the module.
Click on Component View to see a component view of the included web components.

Modify Web Application Descriptor

Now we need to make several changes to settings at the WAR module level. To do so, select either the WAR file path if in File View or the WAR module name if in Component View. Right click and select Edit Descriptor.

As described for the j2eeguide-converterEjb.jar, in the following paragraphs, the title gives the tab name, where you have to enter the data given below.

1. General Tab

Name: j2eeguide-converter

Distributable checked

Session Timeout (seconds): -1 (take server default)

2. iAS Tab

Distributed Session checked

Timeout (seconds): -1

Timeout Type Since last access

Data Synchronization Distributed

3. References Tab

EJB References:

Reference Bean Type Bean Home Interface Bean Remote Interface Linked to Bean

MyConverter Session j2eeguide.converter.ConverterHome j2eeguide.converter.Converter MyConverter

Save and close j2eeguide-converter.war

Before closing the WAR file, you might find it useful to double check your settings against the previous instructions.
Select the WAR module in the Web Applications window.
Select File->Close to save and close the WAR file.

Now that we've assembled both J2EE modules (EJB JAR and WAR), we're ready to move on to assembling the modules into an EAR file.

4. Assemble EAR File

1. Create j2eeguide-converter.ear:

In the startup dialog, select New J2EE Application (.ear file)
Alternatively, if Deployment Tool is already started, select File -> New.
Click on J2EE Application.
Enter "j2eeguide-converter.ear" as the archive file name.
Click on Browse to navigate to the directory install_dir\ias\ias-samples\j2eeguide\converter\assemble\
Click on OK to exit the dialog window.
The EAR file appears in the J2EE Applications pane of the Deployment Tool window.
Click on Component View to see only the name of the EAR without the directory path.

2. Add j2eeguide-converterEjb.jar and j2eeguide-converter.war Files:

Select the j2eeguide-converter EAR entry.
Right click, select Insert Files.
Navigate to the install_dir\ias\ias-samples\j2eeguide\converter\assemble\ directory.
Select both the EJB JAR and WAR files.
Click on the double arrows (>>) to move these files into right side of the dialog window.
Click on Resolve to modify the location of this file relative to the root of the EAR file.
Select all files using the Shift key.
Set the Update Destination Path to blank since the J2EE modules should appear at the root of the EAR file. Click on Update to modify the relative location. Click on OK to close the resolve dialog window.
Click on Insert to close the insert dialog window and to add the files to the EAR.

3. Set Context Root for Web Application

Next, we need to set the context root of the web application. This value will appear in URLs that access web application components. For example, in the URL http://localhost/NASApp/j2eeguide-converter/ConverterServlet the "j2eeguide-confirmer" value is the context root of the web application.

Select the EAR, right click and select Edit Descriptor
Click the Context Root tab.
Click on Add to add a new mapping. Set the Module name to "j2eeguide-converter" and the Context Root to "j2eeguide-converter".
Close the descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes.

4. Save j2eeguide-converter.ear:

Select the EAR file in the J2EE Applications window.
Select File->Close to save and close the EAR file

Now that the EAR file has been assembled, the next step is to deploy the application to an application server instance.

5. Deploy the Application

Now you're about to deploy the application by transferring the EAR file to a target iPlanet Application Server. First, you will identify the target server. After the EAR file is deployed to the server, post processing is performed. The post processing step involves running iasdeploy against the transferred j2eeguide-converter.ear file. You will see the output from iasdeploy fed back to the deployment window. After this step, you will be able to run the application. No server restart is required.

Although you could perform the deployment steps manually by transferring the EAR file to the remote application server and executing j2eeappreg to register the EAR file, Deployment Tool provides a point and click means of deploying applications to remote iPlanet Application Servers.

If you followed the assembly instructions, then j2eeguide-converter.ear is opened in Deployment Tool. If you opened the pre-existing EAR file, you are working with install_dir\ias\ias-samples\j2eeguide\converter\j2eeguide-converter.ear. If you are following the "Create EAR File from Scratch" instructions, you are modifying install_dir\ias\ias-sample\j2eeguide\converter\assemble\j2eeguide-converter.ear.

If you entered all deployment information manually, you can skip the following steps 1 to 3, because you have entered this information already.

1. Select the j2eeguide-converter.ear file under the J2EE Application window.

2. Select File -> Deploy

3. If you have not already registered a target application server, do so now by clicking on the Register button. Enter the host name, administrative port number and username/password for the target application server. Otherwise, select a pre-registered target server.

Note: You may authorize additional users to deploy applications to an iAS server by using the iAS Administrative Console. See the Security settings tab in the application server's Administrative Console.

4. Click on Overwrite modules in case you are repeating the deployment step.

5. Click on Deploy to start the deployment process.

6. Now the file transfer and application registration begins. See the Deploy tab for the status of the deployment. Once the status of the deployment changes to Success, proceed to the next section.

Verifying Registration

After you've deployed the application, you're ready to use several iAS administrative tools to verify that the application is available. The first

Start the application server Administrative Tool

UNIX:
install_dir/ias/bin/ksvradmin
Windows:
Start->Programs->iPlanet Application Server->iAS Administration Tool

Connect to your application server instance by selecting File->New->Server. Click on Localhost to specify the default connection settings. Enter the application server's administrator's password and click on OK.
Select the server name (default name of iAS1) and select the Application button in the top right hand corner of the window to see the applications registered in this instance of the application server.
You should see several folders for the j2eeguide-converter J2EE application. The j2eeguide-converter folder with the world icon represents the web application module while thej2eeguide-converterEjb folder represents the EJB module packaged as part of the sample application.

To see more details associated with the sample application, you can use the lower level tool kregedit:

Execute kregedit to start the iPlanet Application Server Registry Editor GUI.
Navigate to the SOFTWARE/iPlanet/Application Server/6.0/ portion of the tree.
Browse the J2EE-Application/ tree and look for the j2eeguide-converter application.
Expand the j2eeguide-converter folder and explore this portion of the directory tree.
Now open the J2EE-Module/ tree and look for the j2eeguide-converter web application module entry and the j2eeguide-converterEjb EJB module entry.
Expand each of these folders and explore their contents.
Once you find the GUID associated with each EJB in the sample application, you can navigate through the SOFTWARE/iPlanet/Application Server/ClassDef/ folders to find out more details on each EJB. Expanding the matching GUID folders under the ClassDef folder will show you the detailed settings associated with each EJB. Many of these settings appear in the XML deployment descriptors for EJBs.

Deploy the Client Application

Although in practice, you will most likely script the following client application deployment steps, the manual steps are described below in order to provide you with a sense of deploying an RMI/IIOP client. Since manual steps such as setting CLASSPATH variables and such are prone to error, please review each step carefully.

As you review the sample build facility described in Compiling and Assembling the Application, you'll note the install_client target that automates steps 1, 5 and 6. Since the other steps are one time configuration changes, using the "build install_client" command will prove to be a great time saver for local client redeployments.

Compile Client Source File
Setup Client Directories
Install RMI/IIOP Client Support
Set the Client Environment Variables
Copy Client Application Main Class
Copy EJB Interfaces and iPlanet-Specific Stubs
Check Your Client Setup

1. Compile Client Source File

2. Setup Client Directories

Establish a directory on your client system to support the client application class files, the EJB home and remote interface classes as well as the RMI/IIOP stub classes. The specific directory names shown below are not required and may be changed to suit your environment.

For example, on UNIX:

/opt/rmi-client/

For example, on Windows:

d:\rmi-client\

3. Install RMI/IIOP Client Support

If you are planning to run the Java application client on a machine other than the one on which the application server resides, refer to the RMI/IIOP chapter of the Developer's Guide for details on the configuration of the remote client environment.

4. Set the Client Environment Variables

Ensure that the PATH and CLASSPATH variables reference the appropriate JDK, javax.jar and iasclient.jar files.

Testing RMI/IIOP Client Access to EJBs on Same System
If you are experimenting with RMI/IIOP client access using a client that is on the same machine as the application server, you can take a shortcut to setting up the PATH and CLASSPATH variables. Simply reference the existing, pre-installed copies of the javax.jar, iasclient.jar and usr/java/bin/. For example, to test RMI/IIOP access locally, set the CLASSPATH variable as follows (since the Windows System PATH environment variable already contains usr/java/bin/ of the bundled JDK, there is no need to set this again on Windows):

Windows:

set CLASSPATH=d:\iplanet\ias6\ias\lib\java\javax.jar;d:\iplanet\ias6\ias\classes\java\iasclient.jar;%CLASSPATH%

You could set the Windows System CLASSPATH to avoid having to manually set the variable.

UNIX:

export CLASSPATH=/usr/iplanet/ias6/ias/classes/java/javax.jar:/usr/iplanet/ias6/ias/classes/java/iasclient.jar:$CLASSPATH

On UNIX, you will also need to modify the PATH to include the bundled JDK directory:

export PATH=/usr/iplanet/ias6/ias/usr/java/bin:$PATH

Testing RMI/IIOP Client Access to EJBs from a Remote System
If you are using a remote client system, then follow these steps to establish the appropriate PATH and CLASSPATH settings.

UNIX

Set your PATH environment variable to include the appropriate Java 2 bin/ directory:

export PATH=Java_2_install/usr/java/bin:$PATH

Set your CLASSPATH to include the standard Java Extension classes and the iPlanet RMI/IIOP client support JAR:

export CLASSPATH=/opt/rmi-client/iasclient.jar:/opt/rmi-client/javax.jar:$CLASSPATH

Doublecheck the CLASSPATH to ensure that it is set correctly (your CLASSPATH may vary from the one shown below).

echo $CLASSPATH
/opt/rmi-client/iasclient.jar:/opt/rmi-client/javax.jar:

Windows

Set your PATH environment variable to include the appropriate Java 2 bin/ directory:

set PATH=Java_2_install\usr\java\bin;%PATH%

Set your CLASSPATH to include the standard Java Extension classes (javax.jar) and the iPlanet client support JAR (iasclient.jar).

set CLASSPATH=d:\rmi-client\javax.jar;d:\rmi-client\iasclient.jar;%CLASSPATH%

5. Copy Client Application Main Class

Copy the ConverterClient.class file from the compile location to the same package directory structure under your client application directory. (Typically, the client application would most likely belong to a different Java package, but for simplicity reasons, we've packaged the client and EJB in the same Java package).

Copy ConverterClient.class to...

UNIX: /opt/rmi-client/j2eeguide/converter/
Windows: d:\rmi-client\j2eeguide\converter\

Set your client's CLASSPATH to include the Converter client directory path:

UNIX:

export CLASSPATH=/opt/rmi-client:$CLASSPATH
Windows:

set CLASSPATH=d:\rmi-client;%CLASSPATH%

This setting will enable both the application main class as well as the Converter-specific EJB interfaces and stubs to be accessed at run time.

6. Copy EJB Interfaces and Application Server-Specific Stubs

From the APPS/j2eeguide-converter/j2eeguide-converterEjb/ deployment area on the application server, copy the following files to the same package location (j2eeguide/converter/) under the client application directory.

Converter EJB Interface Classes:

ConverterHome.class
Converter.class

EJB-Specific iPlanet Client Stubs:

_Converter_Stub.class
_ConverterHome_Stub.class

7. Check Your Client Setup

Go to the rmi-client/ directory and navigate to the j2eeguide/converter/ directory. You should see the following files:

ConverterClient.class
Converter.class
ConverterHome.class
_ConverterHome_Stub.class
_Converter_Stub.class

Running the Sample

Review Configuration

Before running the sample, first double check your work thus far by ensuring that:

Client CLASSPATH and PATH environment variables are set per the instructions above.
Necessary class files have been copied to the client side.
Application server is started and an RMI/IIOP Bridge (cxs) process is started.

Executing the Java Application Client

From the rmi-client/ directory, execute the following command:

java j2eeguide.converter.ConverterClient <hostname> <port>

For example,

java j2eeguide.converter.ConverterClient hamlet 9010

Where:

<hostname> is the host name of the application server.

<port> is the IIOP port number of the RMI-IIOP bridge or cxs process on the iAS server.

The application should emit the following messages (these are the currency values returned from the ConverterEJB):

12160.0
0.77

Execute Servlet Client

Go to the following URL to exercise the servlet front end:

http://<hostname>/NASApp/j2eeguide-converter/ConverterServlet

As you execute the servlet client, the same output as generated by the Java application client should be generated.

Troubleshooting

If you encounter problems when running the application, review the General Troubleshooting section to learn how to view logs files. Also review the Troubleshooting section of the RMI/IIOP chapter of the Developer's Guide.

Compiling and Assembling the Application

To easily recompile, assemble and deploy the application, see the Sample Application Build Facility document for details on using a build facility to quickly perform these tasks.

For example, to rebuild the entire application from scratch, follow these steps:

1. Compile and Assemble EJB JAR Components and Web Application

Execute "build" under j2eeguide/converter/src/

The default target core will be executed to rebuild the EJB JAR and WAR files as well as the web application's EAR file.

2. Redeploy Application

Execute "build deploy" under j2eeguide/converter/src/

3. Install the Java Client Application

Execute "build install_client" under j2eeguide/converter/src/

Executing this target will install the class files required to run the client application under:

install_dir/ias/rmi-client/

4. Restart Application Server

An application server restart will be necessary if you've modified either deployment descriptors or EJBs. For servlet and/or JSP modification, no restart is is necessary.

To clean the application build and assembly areas, execute "build clean".

Name:	j2eeguide-converter
Distributable	checked
Session Timeout (seconds):	-1 (take server default)

Distributed Session	checked
Timeout (seconds):	-1
Timeout Type	Since last access
Data Synchronization	Distributed

Reference	Bean Type	Bean Home Interface	Bean Remote Interface	Linked to Bean
MyConverter	Session	j2eeguide.converter.ConverterHome	j2eeguide.converter.Converter	MyConverter

Currency Converter EJB J2EE Developer's Guide Samples on iPlanet Application Server