Simple Publish-and-Subscribe JMS Topic
iPlanet^TM Application Server Samples

Updated June 12, 2001

If you already went through the deployment process of this sample, you can run the application by clicking here. Otherwise, deploy the application based on the following instructions.

This sample is based on a servlet accessing a publish-and-subscribe JMS topic and displaying the results via a JSP. The servlet subscribes to the topic, creates a publisher which sends a simple message to the topic, and receives the same message from the topic. The servlet then displays its results using a JSP.

Setting Up the Environment

Getting Started includes a checklist of prerequisites for deploying sample applications to iPlanet.
Before exercising this sample, please review the instructions for installing a JMS provider and configuring it to work with iPlanet Application Server. In order for the sample to work successfully, a JMS provider must be installed and configured.

Deploying and Running the HelloWorld 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.
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 J2EE 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 jms-simpletopic.ear file is a Enterprise ARchive file that contains the Web Archive (WAR) application. Within this JAR file resides the XML deployment descriptor files, application class files, JSPs and other content required by the application.

Deploying the pre-built jms-simpletopic.ear file is simple.

1. Go to the root of the sample directory:

<iPlanet install path>/ias/ias-samples/jms/simpletopic/

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

iasdeploy deployapp jms-simpletopic.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 "jms-simpletopic" in the iPlanet Registry within the directory server
registers the embedded J2EE WAR module in the iPlanet Registry within the directory server
extracts the WAR module to the JAR/ directory.
expands the content of the J2EE WAR module to the APPS/jms-simpletopic/ directory.

If you would like to verify the registration of the application, proceed to Verifying Registration.

Otherwise, you're ready to exercise the application by Running the 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 sample application to iPlanet using the Deployment Tool. None of the application assembly steps are covered by this section. On average, this approach will take 5-10 minutes.
or
Assemble the Application to learn how to use Deployment Tool to assemble the sample application from scratch and to deploy it to the application server. On average, this approach will take from 15-20 minutes.

Import Pre-existing EAR File

Since a pre-built Enterprise ARchive (EAR) file for the sample application is included with the application server, you can use the Deployment Tool to quickly read in the .ear file and deploy it to the application server.

Open the pre-existing sample EAR file.

Launch the Deployment Tool.

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

Open the EAR file

In the startup dialog, select "Browse for more applications" to find the jms-simpletopic.ear file.
Navigate to ias/ias-samples/jms/simpletopic/ and open the jms-simpletopic.ear file.
Click on the file name to expand the EAR file.
Proceed to Deploying the Application

Assemble the Application

This approach involves assembling the sample application from scratch. After compiling the Java sources, you will start Deployment Tool and create the application WAR and EAR files. Then you will deploy the application to the application server.

Compile Application Sources
Create jms-simpletopic.war Module
Assemble jms-simpletopic.ear
Deploy Application

Compile Application Sources

To compile the application sources, you can use either the simple script file with the servlet source file or the more complex build facility described in Compiling and Assembling the Application section at the end of this document. If the script file is used to compile the servlet, it's necessary to verify that IAS_HOME is set correctly at the top of the script.

If you choose to use the build facility, then you will need to issue the command "build compile" after you have established the build environment.

You might want to use the compile scripts first and then try out the build facility after you successfully deploy and run the application. The compile script is located in the ias-samples/jms/simpletopic/src/samples/jms/simpletopic/ directory.

Create WAR Module

Identify the Content for WAR File

1. Create assembly location:

Create the new directory install_dir/ias/ias-samples/jms/simpletopic/assemble/ outside the Deployment Tool. You will assemble the application into archive files and save them to this directory.

2. Launch the Deployment Tool:

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

3. Create jms-simpletopic.war:

In the welcome dialog, select the Create a New Application radio button and click OK
Alternatively, if Deployment Tool is already started, select File -> New...
Make the following selections in the New Application or Module dialog box:

Select the Web Application (.war) radio box in the Application Type panel
Use the filename jms-simpletopic.war
To select the destination directory, left-click the Browse... button and choose the directory install_dir/ias/ias-samples/jms/simpletopic/assemble
Click OK

4. Now insert all class files needed in the jms-simpletopic.war file:

Select the jms-simpletopic.war file from the Web Applications pane (it may be in either FileView or ComponentView)
Right-click on the jms-simpletopic.war file and select Insert Files... from the pop-up menu (this may also be done by selecting Edit -> Insert Files... from the menubar
Navigate to the directory in which the sample application's servlet class resides. The location of the class file will vary depending on how you compiled the sample:

Compile script: ias-samples/jms/simpletopic/src/samples/jms/simpletopic/
Build facility: ias-samples/jms/simpletopic/build/lib/classes/samples/jms/simpletopic/

Highlight the SimpleTopicServlet.class file and click the right arrows to add it to the list of classes to be added to the WAR file
Click the Resolve button. This ensures that all of the servlet's dependent classes can be resolved before it's added to the WAR file (you'll notice that the servlet name in the right-hand pane changed from red to blue--indicating that all of it's dependent classes can be resolved)
Click the Insert button to add the servlet to the WAR file

5. Add JSP file to the .war file

Select the WAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
Navigate to path install_dir/ias/ias-samples/jms/simpletopic/src/docroot directory.
Press Shift key, then select the JSP file.
Click on the double arrows (>>) to move the file into right side of the dialog window.
Click on Resolve to modify the location of the file relative to the root of the WAR file.
Select all files using the Shift key.
Set the Update Destination Path to blank since the application requires that the file be located at the root of the WAR module. 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 file to the WAR.

6. Review the SimpleTopicServlet XML descriptor (this is an optional step):

In the Web Applications pane, expand the jms-simpletopic.war by clicking on the switch to the left of the file name. Once the WAR file is expanded, you should be able to see the SimpleTopicServlet.class.
Click on the SimpleTopicServlet.class to select it and then right-click on the servlet and select Edit Descriptor (this may also be done by selecting from the menubar Edit -> Edit Descriptor)
You can review the descriptor settings by clicking on each of the tabs at the top of the descriptor window. It's not necessary to modify any of these values for this sample application. When you're through reviewing the settings, you can simply close the descriptor window by clicking the close box in the upper right-hand corner

7. Modify the Web Application XML descriptor

In the Web Applications pane, right-click on the jms-simpletopic.war file and select Edit Descriptor (this may also be done by selecting the WAR file and choosing Edit -> Edit Descriptor from the menubar)
Under the References tab, click the Add button beneath the References to resource factories table. This will add a new row to the table. Enter the following values in the newly created row:

Resource Name: jms/SampleTopic
Description: (any descriptive text you may want to use)
Resource Class: javax.jms.Topic
Authorization: Container
JNDI Name: jms/theTopic

Click the Add button beneath the References to resource factories table again. This will add another row to the table. Enter the following values in the newly created row:

Resource Name: jms/SampleTopicFactory
Description: (any descriptive text you may want to use)
Resource Class: javax.jms.TopicConnectionFactory
Authorization: Container
JNDI Name: jms/theTopicFactory

close the descriptor window by clicking the close box in the upper right-hand corner. When prompted, choose to save the descriptor settings

8. Save and close the web application archive

In the Web Applications pane, click on the jms-simpletopic.war file to select it
From the menubar, select File -> Save to save the WAR file
Right-click on the jms-simpletopic.war file and select Close to close the WAR file (this may also be done by selecting File -> Close)

Now that you've assembled the WAR module, you are ready to create the Enterprise ARchive (EAR) file.

Assemble jms-simpletopic.ear

1. Create jms-simpletopic.ear:

Choose File -> New... from the Deployment Tool menubar
Make the following selections in the New Application or Module dialog box:

Select the J2EE Application (.ear) radio box in the Application Type panel
Use the filename jms-simpletopic.ear
To select the destination directory, left-click the Browse... button and choose the directory install_dir/ias/ias-samples/jms/simpletopic/assemble
Click OK

2. Add jms-simpletopic.war:

Select the jms-simpletopic.ear file from the J2EE Applications pane (it may be in either FileView or ComponentView)
Right-click on the jms-simpletopic.ear file and select Insert Files... from the pop-up menu (this may also be done by selecting Edit -> Insert Files... from the menubar
Navigate to the directory in which the jms-simpletopic.war file resides: install_dir/ias/ias-samples/jms/simpletopic/assemble/
Highlight the jms-simpletopic.war file and click the right arrows to add it to the list of modules to be added to the EAR file
Click the Resolve button. This ensures that all of the module's dependent classes can be resolved before it's added to the EAR file. It will ask you to update the file destination paths--simply select the file from the list and click Update and then click OK
Click the Insert button to add the web application to the EAR file.

3. Review the application XML descriptor (this is an optional step):

In the J2EE Applications pane, right-click on the jms-simpletopic.ear file and select Edit Descriptor (this may also be done by selecting Edit -> Edit Descriptor from the menubar)
You can review the descriptor settings by clicking on both of the tabs at the top of the descriptor window. It's not necessary to modify any of these values for this sample application. When you're through reviewing the settings, you can simply close the descriptor window by clicking the close box in the upper right-hand corner

4. Modify the Web Application Context Root

In the J2EE Applications pane, right-click on the EAR file and select Edit Descriptor.
Under the Context Root tab, enter jms-simpletopic as the WAR name and simpletopic as the context root name of the web application. This is the name used in URLs that access the servlet housed in this web application.
Close the descriptor window by clicking the close box in the upper right-hand corner. When prompted, choose to save the descriptor settings

4. Save jms-simpletopic.ear:

In the J2EE Applications pane, click on the jms-simpletopic.ear file to select it.
From the menubar, select File -> Save to save the EAR file

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, registration occurs. After deployment completes, you will be able to run the application. No server restart is required.

If you followed the assembly instructions, then jms-simpletopic.ear is opened in Deployment Tool. If you opened the pre-existing EAR file, you are working with install_dir/ias/ias-samples/jms/simpletopic/jms-simpletopic.ear. If you are following the "Create EAR File from Scratch" instructions, you are modifying install_dir/ias/ias-sample/jms/simpletopic/assemble/jms-simpletopic.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 jms-simpletopic.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 iAS Administrative Console.

4. If you deployed jms-simpletopic.ear previously, then select Overwrite Modules.

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. The deployment may take several minutes to complete.

Verifying Registration

As an optional step, you can use the iPlanet Application Server Administration Tool to verify that the application has been registered. If you do not want to verify that the application has been registered, proceed directly to Running the Application.

Start the iPlanet Application Server Admin 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 iPlanet 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 one folder for the "jms-simpletopic" J2EE application. The "jms-simpletopic" folder with the world icon represents the web application module.

To see more details associated with the sample application, you can browse the iPlanet Application Server Registry using a tool named kregedit:

Execute kregedit to start the iAS 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 "jms-simpletopic" application.
Expand the "jms-simpletopic" folder and explore this portion of the directory tree.
Now open the J2EE-Module/ tree and look for the "jms-simpletopic" web application module entry.
Expand each of these folders and explore their contents.
Once you find the GUID associated with servlet in the sample application, you can navigate through the SOFTWARE/iPlanet/Application Server/ClassDef/ folders to find out more details on the servlet. Expanding the matching GUID folder under the ClassDef folder will show you the detailed settings associated with the servlet.

Now you're ready to exercise the sample application.

Running the Application

Before the sample application is executed, a stand-alone Java application has been written which will subscribe to the Topic and receive messages published by the iAS application. While it's not required that this application be started prior to running the sample application, doing so will confirm that subscribers outside of iAS may receive messages from your web-based applications. To start the stand-alone application:

Compile the program. To do this, change directories to the source directory (cd install_dir/ias/ias-samples/jms/simpletopic/src) and build the classes with the folowing command: build compile
Change directories to the SimpleTopic application directory: cd install_dir/ias/ias-samples/jms/simpletopic/src/bin
Edit the script used to start the Java application to ensure the environment variables at the top of the script are set appropriately. IMQ_HOME (if iMQ is being used), MQ_HOME (if MQSeries is being used), and OTHERPROVIDER_CLASSPATH (if another provider is being used) must be set correctly. On Unix, the script is called runSubscriber.sh , and on Windows, the script is called runSubscriber.bat
Start the application by executing the script which is appropriate for the platform being used

runSubscriber -imq

runSubscriber -mq

runSubscriber [fully qualified class name of the provider's TopicConnectionFactory implementation]

To run the application, go to the following URL:

http://<web server hostname>:<port>/NASApp/simpletopic/SimpleTopicServlet

The browser should display a page that looks similar to this:

Simple Publish-And-Subscribe Topic
iPlanet Application Server JMS Sample Applications
Simple topic publisher sample was: SUCCESSFUL
Message received:
JMSMessageID: D:PHYSICAL:gnelson-nt/DEF_CLASS:[183773208, 0][183773210, 1]
JMSTimestamp: 975534724274
JMSDeliveryMode: 1
PT_DATACLASS: [0, 27]
Text: This is a sample message. It was sent at Wed Nov 29 15:52:04 CST 2000
JMSType: null
JMSExpiration: 0
PT_TAG: [183773210, 1]
PT_SRCDOMAIN: PHYSICAL:gnelson-nt/DEF_CLASS:[183773208, 0]
JMSPriority: 4
PT_ACKNDX: [9, 0]
JMSReplyTo: null
PT_ORIGACKNDX: [6, 0]
JMSRedelivered: false
PT_LIFETIME: com.sun.messaging.ia.IAObjectLifetime@1ba640
JMSDestination: SampleTopic
JMSCorrelationID: null
Check any other subscribers to verify the message was successfully received.

If the stand-alone subscriber is also being used, you should see a message similar to this in it's console window:

Received: This is a sample message. It was sent at Wed Nov 29 15:52:04 CST 2000

Troubleshooting

If you encounter problems when running the application, review the General Troubleshooting section to learn how to view logs files.

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 the Web Application

Execute "build" under jms/simpletopic/src/
The default target core will be executed to rebuild the WAR and EAR files.

2. Redeploy Application

Execute "build deploy" under jms/simpletopic/src/

3. Restart Application Server

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

To clean the web application project area, execute "build clean".

Simple Publish-and-Subscribe JMS Topic iPlanetTM Application Server Samples