Simple Point-to-Point JMS Queue
iPlanet^TM Application Server Samples

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 point-to-point JMS queue and displaying the results via a JSP. The servlet sends a simple message to a queue and then receives the same message from the queue and displays it via 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.

Known Issues describes the known issues with the sample.

Command Line-based Deployment

The pre-built jms-simplequeue.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-simplequeue.ear file is simple.

1. Go to the root of the sample directory:

install_dir/ias/ias-samples/jms/simplequeue/

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

iasdeploy deployapp jms-simplequeue.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-simplequeue" 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-simplequeue/ 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

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

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 jms-simplequeue.ear file.
• Navigate to ias/ias-samples/jms/simplequeue/ and open the jms-simplequeue.ear file.
• Click on the file name to expand the EAR file.
• Proceed to Deploying the Application

Assemble the Application

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

Compile Application Sources

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/simplequeue/src/samples/jms/simplequeue/ directory.

Create WAR Module

Identify the Content for WAR File

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

UNIX:

Execute install_dir/ias/bin/deploytool

Windows:

Start->Programs->iPlanet Application Server 6.0->iAS Deployment Tool

• 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-simplequeue.war
• To select the destination directory, left-click the Browse... button and choose the directory install_dir\ias\ias-samples\jms\simplequeue\assemble
• Click OK

• Select the jms-simplequeue.war file from the Web Applications pane (it may be in either FileView or ComponentView)
• Right-click on the jms-simplequeue.war file and select Insert Files... from the pop-up menu (this may also be done by selecting Edit -> Insert Files... from the menu bar.
• 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/simplequeue/src/samples/jms/simplequeue/
• Build facility: ias-samples/jms/simplequeue/build/lib/classes/samples/jms/simplequeue/
• Highlight the SimpleQueueServlet.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

• 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/simplequeue/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.

• In the Web Applications pane, expand the jms-simplequeue.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 SimpleQueueServlet.class.
• Click on the SimpleQueueServlet.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

• In the Web Applications pane, right-click on the jms-simplequeue.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/SampleQueue
• Description:  (any descriptive text you may want to use)
• Resource Class:  javax.jms.Queue
• Authorization:  Container
• JNDI Name:  jms/theQueue
• 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/SampleFactory
• Description:  (any descriptive text you may want to use)
• Resource Class:  javax.jms.QueueConnectionFactory
• Authorization:  Container
• JNDI Name:  jms/theFactory
• close the descriptor window by clicking the close box in the upper right-hand corner.  When prompted, choose to save the descriptor settings

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

Assemble jms-simplequeue.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-simplequeue.ear
• To select the destination directory, left-click the Browse... button and choose the directory install_dir/ias/ias-samples/jms/simplequeue/assemble
• Click OK

• Select the jms-simplequeue.ear file from the J2EE Applications pane (it may be in either FileView or ComponentView)
• Right-click on the jms-simplequeue.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-simplequeue.war file resides:  install_dir/ias/ias-samples/jms/simplequeue/assemble/
• Highlight the jms-simplequeue.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.

• In the J2EE Applications pane, right-click on the jms-simplequeue.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

• In the J2EE Applications pane, right-click on the EAR file, right click and select Edit Descriptor
• Under the Context Root tab, enter jms-simplequeue as the web application name and simplequeue 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

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

Deploy the Application

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

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

1. Start the iPlanet Application Server Admin Tool

UNIX:

install_dir/ias/bin/ksvradmin

Windows:

Start->Programs->iPlanet Application Server->iAS Administration Tool

2. 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.
3. 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.
4. You should one folder for the "jms-simplequeue" J2EE application. The "jms-simplequeue" folder with the world icon represents the web application module.

1. Execute kregedit to start the iAS Registry Editor GUI.
2. Navigate to the SOFTWARE/iPlanet/Application Server/6.0/ portion of the tree.
3. Browse the J2EE-Application/ tree and look for the "jms-simplequeue" application.
4. Expand the "jms-simplequeue" folder and explore this portion of the directory tree.
5. Now open the J2EE-Module/ tree and look for the "jms-simplequeue" web application module entry.
6. Expand each of these folders and explore their contents.
7. 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.

Running the Application

http://<web server hostname>:<port>/NASApp/simplequeue/SimpleQueueServlet

Simple Point-to-Point Queue
iPlanet Application Server JMS Sample Applications

Simple queue sample was: SUCCESSFUL

Message received:
  JMSMessageID:  ID:414d5120514d5f676e656c736f6e5f6eab33253a13600200
  JMSXDeliveryCount:  1
  JMSTimestamp:  975545248260
  JMSDeliveryMode:  2
  JMSXAppID:  iplanet\ias6\ias\bin\kjs.exe
  Text:  This is a sample message. It was sent at Wed Nov 29 18:47:21 CST 2000
  JMS_IBM_PutApplType:  11
  JMSType:  null
  JMSExpiration:  0
  JMSPriority:  4
  JMSReplyTo:  null
  JMS_IBM_Format:  MQSTR
  JMSRedelivered:  false
  JMSXUserID:  SYSTEM
  JMS_IBM_MsgType:  8
  JMSDestination:  queue:///SYSTEM.DEFAULT.LOCAL.QUEUE
  JMSCorrelationID:  null

Troubleshooting

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

Further Exploration

After running the sample successfully, modify the servlet source code to not issue a receive on the queue. This modification will help you verify that a message is actually being placed on the specified queue.

1. Modify the SimpleQueueServlet to comment out the message receive step.
2. Rebuild the application using the sample application build facility (see next section).
3. Reregister the application.
4. Restart the application server.
5. Access the servlet again. (You should see an unsuccessful message)
6. Use the JMS provider's administrative utilities to browse the messages on the queue. Refer to the JMS provider setup instructions for details.

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/simplequeue/src/

The default target core will be executed to rebuild the WAR and EAR files.

2. Redeploy Application

Execute "build deploy" under jms/simplequeue/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".

Known Issues

A message is printed out in the log - "unable to load message > catalog - mqji".

This typically happens the first time the sample is executed. This can be safely ignored.

Copyright (c) 2001 Sun Microsystems, Inc. All rights reserved.