This sample is based on the Confirmer 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 offers minimal functionality, this sample should provide you with a basic understanding of using the JavaMail API from within an EJB. For a more complex example of using the JavaMail within a J2EE application, see the Java Pet Store application setup instructions.
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).
Registering JavaMail Session in the application server.
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.
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.
Since the sample EJB uses JavaMail to send an e-mail message, you must first register a mail session in the JNDI name space of the application server.
1. Go to the install_dir/ias/ias-samples/j2eeguide/confirmer/src/schema/ directory and edit the mail-resource.xml file. Change the host, mail server user name and reply to address fields to suit your environment.
<ias-resource>
<resource>
<jndi-name>mail/j2eeguide/confirmer/MailSession</jndi-name>
<mail>
<host>mailhost.iplanet.com</host>
<name>mailuser</name>
<address>mailuser@iplanet.com</address>
</mail>
</resource>
</ias-resource>
2. Use the iasdeploy CLI, register the mail resource:
iasdeploy regdatasource mail-resource.xml
If you browse the application's ejb-jar.xml and ias-ejb-jar.xml files, you will see the linkage between the logical mail session name and the actual JNDI name used to register mail server information.
Java Source Code in
The Confirmer EJB performs a lookup for the mail session resource using logical name of the resource. The value of this reference is identified in the EJB's ejb-jar.xml file.
Session session = (Session) initial.lookup("java:comp/env/TheMailSession");
ejb-jar.xml File
The logical name mail/TheMailSession is mapped to an absolute name of the resource in the ias-ejb-jar.xml file.
<resource-ref>
<description>description</description>
<res-ref-name>mail/TheMailSession</res-ref-name>
<res-type>javax.mail.Session</res-type>
<res-auth>Container</res-auth>
</resource-ref>
ias-ejb-jar.xml File
The absolute name as specified in the ejb-jar.xml file matches the absolute name specified in the resource's XML registration file.
<resource-ref>
<res-ref-name>mail/TheMailSession</res-ref-name>
<jndi-name>mail/j2eeguide/confirmer/MailSession</jndi-name>
</resource-ref>
Mail Session Resource File
<ias-resource>
<resource>
<jndi-name>mail/j2eeguide/confirmer/MailSession</jndi-name>
<mail>
<host>mailhost.iplanet.com</host>
<name>mailuser</name>
<address>mailuser@iplanet.com</address>
</mail>
</resource>
</ias-resource>
The pre-built j2eeguide-confirmer.ear file is a Enterprise ARchive file that contains the Web Archive (WAR) and EJB JAR files for the Confirmer 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-confirmer.ear file is simple.
1. Go to the root of the Confirmer sample directory:
install_dir/ias/ias-samples/j2eeguide/confirmer/
2. Execute iasdeploy to deploy application to the local application server instance:
iasdeploy deployapp j2eeguide-confirmer.ear
Refer to the Getting Started section for more information on using the iasdeploy command.
The deployment process involves the following operations:
Now you're ready to exercise the application by Deploying the Client Application.
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.
1. Launch the Deployment Tool.
UNIX:Execute install_dir/ias/bin/deploytoolWindows:Start->Programs->iPlanet Application Server 6.0->iAS Deployment Tool
2. Open the EAR file
Proceed to Deploying the Application
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.
Create the new directory install_dir\ias\ias-samples\j2eeguide\confirmer\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&3. Create j2eeguide-confirmerEjb.jar:Windows: Programs->iPlanet Application Server 6.0->iAS Deployment Tool
4. Now insert all class files needed in the j2eeguide-confirmerEjb.jar file:
1. Modify Descriptor for Confirmer EJB
2. Begin Modifying the Confirmer EJB Descriptor
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.
Now that we've assembled the EJB JAR module, we're ready to move on to assembling the Web Application aRchive (WAR) file.
1. Create j2eeguide-confirmer.war:
2. Now insert all class files needed in the j2eeguide-confirmer.war file:
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-confirmerEjb.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-confirmer 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 MyConfirmer Session j2eeguide.confirmer.ConfirmerHome j2eeguide.confirmer.Confirmer MyConfirmer
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.
1. Create j2eeguide-confirmer.ear:
2. Add j2eeguide-confirmerEjb.jar and j2eeguide-confirmer.war Files:
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-confirmer/ConfirmerServlet the "j2eeguide-confirmer" value is the context root of the web application.
4. Save j2eeguide-confirmer.ear:
Now that the EAR file has been assembled, the next step is to deploy the application to an application server instance.
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-confirmer.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-confirmer.ear is opened in Deployment Tool. If you opened the pre-existing EAR file, you are working with install_dir\ias\ias-samples\j2eeguide\confirmer\j2eeguide-confirmer.ear. If you are following the "Create EAR File from Scratch" instructions, you are modifying install_dir\ias\ias-sample\j2eeguide\confirmer\assemble\j2eeguide-confirmer.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-confirmer.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.
UNIX:install_dir/ias/bin/ksvradminWindows:Start->Programs->iPlanet Application Server->iAS Administration Tool
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.
For example, on UNIX:
For example, on Windows:/opt/rmi-client/
d:\rmi-client\
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.
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%
Copy ConfirmerClient.class to...
UNIX: /opt/rmi-client/j2eeguide/confirmer/Set your client's CLASSPATH to include the Confirmer client directory path:Windows: d:\rmi-client\j2eeguide\confirmer\
UNIX:
This setting will enable both the application main class as well as the Confirmer-specific EJB interfaces and stubs to be accessed at run time.Windows:export CLASSPATH=/opt/rmi-client:$CLASSPATH
set CLASSPATH=d:\rmi-client;%CLASSPATH%
Confirmer EJB Interface Classes:
EJB-Specific iPlanet Client Stubs:
Before running the sample, first double check your work thus far by ensuring that:
java j2eeguide.confirmer.ConfirmerClient <hostname> <port> <mail address>
For example,
java j2eeguide.confirmer.ConfirmerClient hamlet 9010
Where:
The application should emit the following messages (these are the currency values returned from the ConfirmerEJB):<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 application server.
<mail address> is e-mail address of the intended recipient.
Message sent succesfully to: <mail address>
If you've configured the target mail server settings correctly in the mail resource XML file, then you should see the message arrive in the recipient's mailbox shortly after running the client.
Go to the following URL to exercise the servlet front end:
http://<hostname>/NASApp/j2eeguide-confirmer/ConfirmerServlet
Enter the recipient's e-mail address and click on submit to send the message. If you've configured the target mail server settings correctly in the mail resource XML file, then you should see the message arrive in the recipient's mailbox shortly after running the web application.
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.
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/confirmer/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/confirmer/src/
3. Install the Java Client Application
Execute "build install_client" under j2eeguide/confirmer/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".
Copyright
(c) 2001 Sun Microsystems, Inc. All rights reserved.