JMS Samples
iPlanetTM Application Server Samples

Updated June 12, 2001

The following instructions and sample applications provide an introduction to the Java Message Service support built into iPlanet Application Server.

1. Read the section entitled Using the Java Message Service, in the Developer's Guide of the iPlanet Application Server documentation.

2. Install and Configure a JMS Provider for iPlanet Application Server

iPlanet Message Queue (iMQ)
iMQ on Solaris

iMQ on Windows

IBM MQSeries
MQSeries on Solaris

MQSeries on Windows
 

3. Deploy and Exercise the JMS Sample Applications
Simple Point-to-Point Queue using a servlet to write/read a single message to/from a queue.

Simple Publish and Subscribe Topic using a servlet to write/read a single message to/from a topic (a stand-alone subscriber is also included).

Installation and Configuration of JMS Providers

iPlanet Message Queue (iMQ) on Solaris

The following instructions describe how to install and configure iMQ 2.0 for Solaris and how to configure iPlanet Application Server to use JMS to interact with iMQ.

Download and Install iMQ

If you do not already have a copy of iPlanet Message Queue 2.0, an evaluation version is available from the iPlanet Developer's web site.  A number of steps are required to uncompress the installation package:

1. Uncompress the installer by executing the file which was downloaded, ./imq2_0-dev-solsparc.sh  Note that complete installation instructions can be found in the install.pdf file which is created.

2. Uncompress the file archive that is created, uncompress imq2_0-dev-solsparc.tar.Z

3. Extract the software archive, tar xvfp imq2_0-dev-solsparc.tar, and change directories to the installation directory, cd imq2_0-pkgs

4. As the root user, install the iMQ package by running the pkgadd command, pkgadd -d ./

5. Start iMQ

Configure iMQ objects in JNDI

The next step is to execute an iMQ administrative interface to define a JMS connection factory and to add the connection factory to the iPlanet Application Server registry.

1. Stop the application server:  iascontrol stop

2. Setup the JMS provider classpath which will be used by the JMS administration and KJS scripts. To do this, execute jmssetup ([iAS-install-directory]/ias/jms/bin/jmssetup ) as root. You will be asked several questions:

3. Restart the application server:  iascontrol start

4. Set up the JMS administered objects which are used by the sample applications.

Our next step is to use the iMQ JMS administrative command line interface to define the shared objects used in the iPlanet JMS sample applications. The following objects will be registered with the application server:

iPlanet provides a wrapper script for this utility. The wrapper script first sets several environment variables and then passes calls the jmqobjmgr command line utility that is part of the iMQ installation.  The iAS wrapper script contains the name of the iPlanet class for the initial context factory (com.netscape.server.jms.RefFSContextFactory ) as well as the provide URL ( /jms).

During execution of this utility, entries defining the JMS objects will be added to the iPlanet Application Server Registry under the following location:

SOFTWARE\iPlanet\Application Server\6.0\JMSObjects\
a. Prior to executing the administration utility, you must edit the script to set iMQ's installation path (this must only be done if you did not use the default installation location, /opt/SUNWjmq).

Edit the file imqjmsadm  This file resides in [iAS-install-directory]/ias/jms/bin/

Set IMQ_HOMEto the iMQ installation directory (by default, this is /opt/SUNWjmq)
b. Add the queue to the iAS registry using the iMQ JMS administration utility.  The utility requires three arguments:  the type of the shared object (in this case "q" for queue), the JNDI name of the queue, and the name of the queue itself: c. Add the queue connection factory to the iAS registry using the iMQ JMS administration utility.  The administration script takes two arguments: the type of shared object (in this case "qf" for queue factory) and the JNDI name of the queue factory:
[iAS-install-directory]/ias/jms/bin/imqjmsadm qf providerFactory
d. Because creating and destroying JMS connections can be expensive, iAS supports JMS connection pooling to improve system performance.  The application server does this using a proxy class that interposes between application requests and the standard QueueConnectionFactory.  Applications can lookup the QueueConnectionFactoryProxy in JNDI and use it as if it's an ordinary QueueConnectionFactory--the proxy will transparently provide the pooling functionality.  To create a QueueConnectionFactoryProxy (which implements the standard JMS interface QueueConnectionFactory) for the factory created in the previous step, the following command is used:
[iAS-install-directory]/ias/jms/bin/jmspadm theFactory providerFactory
e. Add the topic to the iAS registry using the iMQ JMS administration utility.  The utility requires three arguments:  the type of the shared object (in this case "t" for topic), the JNDI name of the topic, and the name of the topic itself: f. Add the topic connection factory to the iAS registry using the iMQ JMS administration utility.  Two arguments are required: the type of shared object (in this case "tf" for topic factory) and the JNDI name of the topic factory:
[iAS-install-directory]/ias/jms/bin/imqjmsadm tf providerTopicFactory
g. To create a TopicConnectionFactoryProxy (which implements the standard JMS interface TopicConnectionFactory), execute this script with the name of the proxy as well as the name of the TopicConnectionFactory created in the previous step:
[iAS-install-directory]/ias/jms/bin/jmspadm theTopicFactory providerTopicFactory
For more information on using the iMQ JMS Administration Tool, see chapter seven of the Java Message Queue Administration Guide:
[iMQ-install-directory]/doc/en/userguides/admin.pdf
Now that iMQ and the application server are configured, proceed to setting up the JMS sample applications.
 

iPlanet Message Queue (iMQ) on Windows

The following instructions describe how to install and configure iMQ 2.0 for Windows and how to configure iPlanet Application Server to use JMS to interact with iMQ.

Download and Install iMQ

If you do not already have a copy of iPlanet Message Queue 2.0, an evaluation version is available from the iPlanet Developer's web site.  A number of steps are required to uncompress the installation package.  Begin the installation of iMQ by executing the installer, imq2_0-dev-win.exe

1. Choose "Typical" installation

2. Accept the default installation folder (C:\Program Files\iPlanetMessageQueue2.0) or specify your own

3. Choose to install the iMQ broker as a Windows Service--this is done simply as a convenience and not strictly necessary to use iMQ with iAS

4. If installed as a Windows Service, the broker will start automatically the next time your restart the machine.  To start the broker without restarting the machine, use the Services Control Panel and start the JMQ_Broker service

Configure iMQ objects in JNDI

The next step is to execute an iMQ administrative interface to define the JMS objects and environment in the iPlanet Application Server Registry.

1. Setup the JMS provider classpath which will be used by the JMS administration scripts. The setjmscp script creates the file ias/jms/bin/setcp.bat file. The purpose of this file is to set the IAS_JMS_CLASSPATH environment variables used by the JMS administration scripts.

To do this, execute the following utility (it takes only one parameter: your iMQ installation directory):

[iAS-install-directory]\ias\jms\setup\setjmscp imq [iMQ-install-directory]
If you installed both iAS and iMQ in their default directories (c:\iPlanet\ias6 and c:\Program Files\iPlanetMessageQueue2.0), the command will look like this:
c:\iPlanet\ias6\ias\jms\setup\setjmscp imq c:\Progra~1\iPlanetMessageQueue2.0
2. Configure the iAS registry with the default JMS entries.  JMS is enabled in the application server by loading default values into the registry.  To do this, execute the following command:
[iAS-install-directory]\ias\jms\setup\jmssetup
3. Set up the JMS administered objects which are used by the sample applications.

Our next step is to use the iMQ JMS administrative command line interface to define the shared objects used in the iPlanet JMS sample applications. The following objects will be registered with the application server:

iPlanet provides a wrapper script for this utility. The wrapper script first sets several environment variables and then passes calls the jmqobjmgr.bat command line utility that is part of the iMQ installation.  The iAS wrapper script contains the name of the iPlanet class for the initial context factory (com.netscape.server.jms.RefFSContextFactory ) as well as the provider URL ( /jms).

During execution of this utility, entries defining the JMS objects will be added to the iPlanet Application Server Registry under the following location:

SOFTWARE\iPlanet\Application Server\6.0\JMSObjects\
a. Prior to executing the administration utility, you must edit the batch script to set the application server's installation path.

Edit the file imqjmsadm.bat This file resides in ias\jms\bin

Set IMQ_HOME to the iMQ installation directory (by default, this is C:\Progra~1\iPlanetMessageQueue2.0)
b. Add the queue to the iAS registry using the iMQ JMS administrative utility.  The utility requires three arguments:  the type of the shared object (in this case "q" for queue), the JNDI name of the queue, and the name of the queue itself: c. Add the queue connection factory to the iAS registry using the iMQ JMS administrative utility.  The administration script takes two arguments: the type of shared object (in this case "qf" for queue factory) and the JNDI name of the queue factory:
[iAS-install-directory]\ias\ias-samples\jms\docs\imqjmsadm qf providerFactory
d. Because creating and destroying JMS connections can be expensive, iAS supports JMS connection pooling to improve system performance.  The application server does this using a proxy class that interposes between application requests and the standard QueueConnectionFactory.  Applications can lookup the QueueConnectionFactoryProxy in JNDI and use it as if it's an ordinary QueueConnectionFactory--the proxy will transparently provide the pooling functionality.  To create a QueueConnectionFactoryProxy (which implements the standard JMS interface QueueConnectionFactory), execute this script with the name of the proxy as well as the name of the QueueConnectionFactory created in the previous step:
[iAS-install-directory]\ias\jms\bin\jmspadm theFactory providerFactory
e. Add the topic to the iAS registry using the iMQ JMS administrative utility.  The utility requires three arguments:  the type of the shared object (in this case "t" for topic), the JNDI name of the topic, and the name of the topic itself: f. Add the topic connection factory to the iAS registry using the iMQ JMS administrative utility.  Two arguments are required: the type of shared object (in this case "tf" for topic factory) and the JNDI name of the topic factory:
[iAS-install-directory]\ias\ias-samples\jms\docs\imqjmsadm tf providerTopicFactory
g. To create a TopicConnectionFactoryProxy (which implements the standard JMS interface TopicConnectionFactory), execute this script with the name of the proxy as well as the name of the TopicConnectionFactory created in the previous step:
[iAS-install-directory]\ias\jms\bin\jmspadm theTopicFactory providerTopicFactory
For more information on using the iMQ JMS Administration Tool, see chapter seven of the iPlanet Message Queue Administration Guide:
[iMQ-install-directory]\doc\en\userguides\admin.pdf

Configure iPlanet Runtime for iMQ

The iPlanet Application Server runtime environment must be modified to enable the application server to access the iMQ JMS classes. This modification involves setting the CLASSPATH variable in the application server's Registry.  (Setting the Windows system environment variable CLASSPATH will not affect the setting used by the application server.) To modify the registry: Now that iMQ and the application server are configured, proceed to setting up the JMS sample applications .
 

MQSeries on Solaris

The following instructions describe how to install and configure MQSeries version 5.1 for Solaris and how to configure iPlanet Application Server to use JMS to interact with MQSeries.

Install MQSeries

If you already have MQSeries installed, then proceed to the next section, Download and Install MQSeries Classes for JMS.  Basic installation instructions are provided below. For more detailed instructions, please refer to "MQSeries for Sun Solaris V5.1 Quick Beginnings" (once the distribution is uncompressed, this and other manuals can be found in [MQSeries-installer]/books/html/en_US/index.htm). As root, the following steps are used to install MQSeries on Solaris:

1. Create a new group named mqm and create a new user named mqm that is part of this group.  In addition, make root a member of the mqm group by editing the /etc/group file

2. Unzip and untar the MQSeries installation package.  When completed, a folder named mq_solaris will be created.  Change directories to the mq_solaris folder

3. Install the MQSeries package by running the pkgadd command, pkgadd-d ./

4. After installation is complete, it's necessary to update some of the default system settings in order for MQSeries to function correctly.  To do this, edit the /etc/system file and add the following lines:
set shmsys:shminfo_shmmax=4194304
set shmsys:shminfo_shmmin=1
set shmsys:shminfo_shmmni=1024
set shmsys:shminfo_shmseg=1024
set semsys:seminfo_semaem=16384
set semsys:seminfo_semmni=1024
set semsys:seminfo_semmap=1026
set semsys:seminfo_semmsl=100
set semsys:seminfo_semmns=16384
set semsys:seminfo_semopm=100
set semsys:seminfo_semvmx=32767
set semsys:seminfo_semmnu=2048
set semsys:seminfo_semume=256
set msgsys:msginfo_msgmap=1026
set msgsys:msginfo_msgmax=4096
5. After the /etc/system file has been updated, it's necessary to reboot the machine for the changes to take effect

6. To verify that MQSeries has been installed correctly and is functioning normally, we'll create a default queue manager named mqseries.queue.manager , a local queue named IAS.QUEUE and test both of them:

Download and Install MQSeries Classes for JMS

In addition to the MQSeries software, you will also need the MQSeries classes for JMS. If you already installed these classes, then proceed to the next section, Download and Install Support for Publish-and-Subscribe.  The installation steps should be done as root

1. Download the installation archive (ma88_sol.tar.Z)and save it in the /tmp folder

2. Uncompress the installation archive by executing uncompress -fv /tmp/ma88_sol.tar.Z

3. Untar the archive using the command  tar -xvf /tmp/ma88_sol.tar

4. Install the MQSeries JMS Classes package by executing pkgadd -d /tmp mqjava

Download and Install MQSeries Support for Publish-and-Subscribe

In addition to the MQSeries classes for JMS, you will also need the MQSeries SupportPac for publish-and-subscribe (if you intend to use this functionality). The SupportPac can be downloaded from the MQSeries support site. If you already installed these classes, then proceed to the next section, Configure MQSeries for JMS.

1. Download the installation archive (ma0c_sol.tar.Z) and save it in the /tmp folder

2. Uncompress the installation archive by executing uncompress -fv /tmp/ma0c_sol.tar.Z

3. As root, untar the archive using the command  tar -xvf /tmp/ma0c_sol.tar  As long as you are using the default MQSeries installation location, the files will be extracted directly to the appropriate MQSeries folders

4. Before the publish-and-subscribe functionality can be used, however, it's necessary to start a broker using the default queue manager.  To do this, execute the following commands as the mqm user:

To start the broker:  strmqbrk -m mqseries.queue.manager
To verify the broker is running (it will display a message with the broker's current status):  dspmqbrk -m mqseries.queue.manager
5.  It is also necessary to create several queues that MQSeries uses to implement its publish-and subscribe functionality.  A command script has been provided which automatically creates these queue:
Change directories to the location of the command script: cd /opt/mqm/java/bin
Execute the commands found in the script:  runmqsc mqseries.queue.manager < MQJMS_PSQ.mqsc

Configure MQSeries for JMS

The next step is to execute an MQSeries Classes for Java administrative interface to define the JMS objects and environment in the iPlanet Application Server Registry.

1. If the application server is running, it must be stopped prior to configuring it for MQSeries

iascontrol stop


2. Before the administrative interface can be used, it's necessary to set the Java CLASSPATH and library path settings so the correct MQSeries code is included.  A script has been provided which accomplishes this (the script must be run as root):

[iAS-install-directory]/ias/jms/bin/jmssetup
When the utility asks if MQSeries v5.1 is messaging provider, answer y and the script will update the iAS settings appropriately

3. Restart the application server (note that the web server and directory server must be started first if they reside on the same server)

iascontrol start
4. Set up the JMS administered objects which are used by the sample applications.

Our next step is to use the MQSeries JMS administrative command line interface to define the shared objects used in the iPlanet JMS sample applications. The following objects will be registered with the application server:

iPlanet provides a wrapper script for this utility. The wrapper script first sets several environment variables and then passes a configuration file to the command line utility. The configuration file, mqjmsadm.cfg, contains the name of the iPlanet class for the initial context factory (com.netscape.server.jms.RefFSContextFactory ) as well as the provide URL ( /jms). Trace and log file locations for MQSeries JMS are also specified on the command line.

During execution of this utility, entries defining the JMS objects will be added to the iPlanet Application Server Registry under the following location:

SOFTWARE\iPlanet\Application Server\6.0\JMSObjects\
Execute the MQSeries JMS administrative utility (note: if an error occurs, it's possible that current user cannot access the /opt/mqm directory -- if that is the case, enable access by executing chmod +rx /opt/mqm ):
[iAS-install-directory]/ias/jms/bin/mqjmsadm

At the InitCtx> command prompt, enter the following definitions

define q(theQueue) queue(IAS.QUEUE)
define qcf(providerFactory) qmgr(mqseries.queue.manager)
define t(theTopic) topic(SampleTopic)
define tcf(providerTopicFactory)
end

Output from administration utility will look like this:

# mqjmsadm
5648-C60 (c) Copyright IBM Corp. 1999. All Rights Reserved.
Starting MQSeries Classes for Java(tm) Message Service Administration

Connected to LDAP server on cowboys.mcom.com port 389
InitCtx> define q(theQueue) queue(IAS.QUEUE)
[16/Nov/2000 17:31:47:7] info: GDS-007: finished a registry load

InitCtx> define qcf(providerFactory) qmgr(mqseries.queue.manager)
[16/Nov/2000 17:32:07:8] info: GDS-007: finished a registry load

InitCtx> define t(theTopic) topic(SampleTopic)
[16/Nov/2000 17:32:47:7] info: GDS-007: finished a registry load

InitCtx> define tcf(providerTopicFactory)
[16/Nov/2000 17:33:07:8] info: GDS-007: finished a registry load

InitCtx> end
Stopping MQSeries Classes for Java(tm) Message Service Administration

For more information on using the MQ JMS Administration Tool, see the documentation located under the java/doc/En_US/html/text/ of the MQSeries installation directory. For example, use the DISPLAY command to display properties of the defined objects:
InitCtx> display q(theQueue)
    CCSID(1208)
    PERSISTENCE(APP)
    TARGCLIENT(JMS)
    QUEUE(IAS.QUEUE)
    EXPIRY(APP)
    QMANAGER()
    ENCODING(NATIVE)
    VERSION(1)
    PRIORITY(APP)

InitCtx> display qcf(providerFactory)
    TRANSPORT(BIND)
    TEMPMODEL(SYSTEM.DEFAULT.MODEL.QUEUE)
    QMANAGER(mqseries.queue.manager)
    VERSION(1)

InitCtx> display t(theTopic)
    CCSID(1208)
   PERSISTENCE(APP)
    TARGCLIENT(JMS)
    EXPIRY(APP)
    ENCODING(NATIVE)
    VERSION(1)
    PRIORITY(APP)
    TOPIC(SampleTopic)

InitCtx> display tcf(providerTopicFactory)
    BROKERPUBQ(SYSTEM.BROKER.DEFAULT.STREAM)
    BROKERVER(V1)
    TRANSPORT(BIND)
    BROKERQMGR()
    QMANAGER()
    BROKERCONQ(SYSTEM.BROKER.CONTROL.QUEUE)
    VERSION(1)

5. Because creating and destroying JMS connections can be expensive, iAS supports JMS connection pooling to improve system performance.  The application server does this using a proxy class that interposes between application requests and the standard QueueConnectionFactory.  Applications can lookup the QueueConnectionFactoryProxy in JNDI and use it as if it's an ordinary QueueConnectionFactory--the proxy will transparently provide the pooling functionality.  To create a QueueConnectionFactoryProxy (which implements the standard JMS interface QueueConnectionFactory) for the factory created in the previous step, the following command is used:
[iAS-install-directory]/ias/jms/bin/jmspadm theFactory providerFactory
6. To create a TopicConnectionFactoryProxy (which implements the standard JMS interface TopicConnectionFactory), execute this script with the name of the proxy as well
as the name of the TopicConnectionFactory created in the previous step:
[iAS-install-directory]/ias/jms/bin/jmspadm theTopicFactory providerTopicFactory
Now that MQSeries and the application server are configured, proceed to setting up the JMS sample applications.
 

MQSeries on Windows

The following instructions describe how to install and configure MQSeries version 5.1 for Windows and how to configure iPlanet Application Server to use JMS to interact with MQSeries.

Download and Install MQSeries

If you do not already have a copy of MQSeries for Windows, a 60-day evaluation copy is available for download from the IBM web site.  If you already have MQSeries installed, then proceed to the next section, Download and Install MQSeries Classes for JMS.

1. Unzip the MQSeries downloaded archive (MQ51Demo.zip)into a temporary folder -- it will unzip into a folder entitled [tmp]\MQ51Demo

2. If you have not installed the Active Directory Service Interfaces (ADSI) Version 2.0, you must do so before MQSeries is installed.  You may install it by executing [tmp]\MQ51Demo\Prereqs\Adsi\adsx86.exe

3. If you have not installed the Microsoft Management Console Version 1.1, you must do so before MQSeries is installed.  You may install it by executing [tmp]\MQ51Demo\Prereqs\Mmc\en_us\immc.exe

4. Begin the installation of MQSeries by executing [tmp]\MQ51Demo\Setup.exe

Accept the default installation folders or specify your own.

Choose "Typical" installation.

5. After installation copies files, choose to Choose MQSeries First Steps and select Default Configuration.
It is not necessary to enable remote administration and create a default cluster to run the sample applications.  You may choose to do (or not do) either of these depending on your local requirement.
6. Start the MQSeries Explorer to view your MQSeries configuration.
Start the MQSeries Explorer to view the underlying MQSeries configuration. Since the examples use the system queue SYSTEM.DEFAULT.LOCAL.QUEUE and system objects are not shown in the explorer by default, select the Queues folder, right click and select View->Show System Objects to view the configuration of the default local queue. You can view messages sent to the queue via the explorer.

Download and Install MQSeries Classes for JMS

In addition to the MQSeries software, you will also need the MQSeries classes for JMS. If you already installed these classes, then proceed to the next section, Download and Install Support for Publish-and-Subscribe.

1. Unzip the MQSeries Product Extension MA88 (MQSeries classes for JMS) downloaded archive (ma88_win.zip )into a temporary folder -- it will unzip into a folder entitled [tmp]\ma88_win

2. Begin the installation of the MQSeries classes for JMS by executing ...\ma88_win\Setup.exe

Accept the default installation folder or specify your own

Install all three options (Java programming interface, JMS programming interface, and Documentation)

Download and Install MQSeries Support for Publish-and-Subscribe

In addition to the MQSeries classes for JMS, you will also need the MQSeries SupportPac for publish-and-subscribe (if you intend to use this functionality). The SupportPac can be downloaded from the MQSeries support site. If you already installed these classes, then proceed to the next section, Configure MQSeries for JMS.

1. Unzip the MQSeries SupportPac MAOC (MQSeries Publish/Subscribe) downloaded archive (ma0c_nt.zip )into a temporary folder -- it will unzip into a folder entitled [tmp]\ma0c_nt

2. Begin the installation of the MQSeries Publish/Subscribe by executing [tmp]\ma0c_nt\install.bat [MQSeries install directory]

If you installed MQSeries in it's default location, for example, this command would look like this:  [tmp]\ma0c_nt\install.bat c:\Progra~1\MQSeries
3. Before the publish-and-subscribe functionality can be used, however, it's necessary to start a broker using the default queue manager.  To do this, execute the following commands:
To start the broker:  strmqbrk -m [queue manager name]
To verify the broker is running (it will display a message with the broker's current status):  dspmqbrk -m [queue manager name]
If you don't know the queue manager name, it can be found in the MQSeries Explorer (which was described and illustrated above).  By default, the queue manager is named QM_[fully qualified machine name] (for example, the queue manager is named QM_kampfire.sun.com in the illustration above)

4.  It is also necessary to create several queues that MQSeries uses to implement its publish-and subscribe functionality.  A command script has been provided which automatically creates these queue:

Change directories to the location of the command script: cd [MQSeries install directory]\java\bin
Execute the commands found in the script:  runmqsc [queue manager name] < MQJMS_PSQ.mqsc

Configure MQSeries for JMS

The next step is to execute an MQSeries administrative interface to define the JMS objects and environment in the iPlanet Application Server Registry.

1. Setup the JMS provider classpath which will be used by the JMS administration scripts. The setjmscp script creates the file ias/jms/bin/setcp.bat file. The purpose of this file is to set the IAS_JMS_CLASSPATH environment variables used by the JMS administration scripts.

To do this, execute the following utility (it takes only one parameter: your MQSeries installation directory):

[iAS-install-directory]\ias\jms\setup\setjmscp mq [MQSeries-install-directory]
If you installed both iAS and MQSeries in their default directories (c:\iPlanet\ias6 and c:\Program Files\MQSeries), the command will look like this:
c:\iPlanet\ias6\ias\jms\setup\setjmscp mq c:\Progra~1\MQSeries
2. Configure the iAS registry with the default JMS entries.  JMS is enabled in the application server by loading default values into the registry.  To do this, it's necessary to modify the file [iAS-install-directory]\ias\jms\bin\jmsreg.bat to ensure that IAS_BASEPATH correctly reflects the installation location for iAS.  Once this is set correctly, execute the following command:
[iAS-install-directory]\ias\jms\setup\jmssetup
3. Set up the JMS administered objects which are used by the sample applications.

Our next step is to use the MQSeries JMS administrative command line interface to define the shared objects used in the iPlanet JMS sample applications. The following objects will be registered with the application server:

iPlanet provides a wrapper script for this utility. The wrapper script first sets several environment variables and then passes a configuration file to the command line utility. The configuration file, mqjmsadm.cfg, contains the name of the iPlanet class for the initial context factory (com.netscape.server.jms.RefFSContextFactory )as well as the provide URL ( /jms). Trace and log file locations for MQSeries JMS are also specified on the command line.

During execution of this utility, entries defining the JMS objects will be added to the iPlanet Application Server Registry under the following location:

SOFTWARE\iPlanet\Application Server\6.0\JMSObjects\
a. Prior to executing the administration utility, you must edit the batch script to set the application server's installation path.

Edit the file mqjmsadm.bat . This file exists in the ias/jms/bin/ directory of your installation.

Set IAS_BASEPATH to your application server installation directory (by default, this is C:\iplanet\ias6\ias)  [In a future version of the application server, this may be done automatically by the installer]

Put enclosing quotes around all of the command-line parameters for the java.exe command that's executed (the second to the last line of the script).  Once changed, the java.exe command will look like this in the script:

%IAS_BASEPATH%\usr\java\bin\java -classpath "%IAS_JMS_CLASSPATH%" -DMQJMS_LOG_DIR= "%MQ_JAVA_INSTALL_PATH%\log" -DMQJMS_TRACE_DIR="%MQ_JAVA_INSTALL_PATH%\trace" -DMQJMS_INSTALL_PATH="%MQ_JAVA_INSTALL_PATH%" com.ibm.mq.jms.admin.JMSAdmin -cfg "%ias_basepath%\jms\bin\mqjmsadm.cfg" %1 %2 %3 %4 %5

b. Execute the MQSeries JMS administrative utility:
[iAS-install-directory]\ias\jms\bin\mqjmsadm

At the InitCtx> command prompt, enter the following definitions

define q(theQueue) queue(SYSTEM.DEFAULT.LOCAL.QUEUE)
define qcf(providerFactory)
define t(theTopic) topic(SampleTopic)
define tcf(providerTopicFactory)
end

Output from administration utility will look like this:

C:\iPlanet\iAS6\ias\jms\bin> mqjmsadm
5648-C60 (c) Copyright IBM Corp. 1999. All Rights Reserved.
Starting MQSeries Classes for Java(tm) Message Service Administration
Connected to LDAP server on pc541443 port 389
[19/Jul/2000 14:27:36:3] info: ENGINE-class_loader_created: New class loader com.kivasoft.engine.EngineClassLoaderNonVersionable@7c6768 has just been created
[19/Jul/2000 14:27:36:3] info: ENGINE-class_loader_created: New class loader com.kivasoft.engine.EngineClassLoader@12f614 has just been created
InitCtx> define q(theQueue) queue(SYSTEM.DEFAULT.LOCAL.QUEUE)
InitCtx> define qcf(providerFactory)
InitCtx> define t(theTopic) topic(SampleTopic)
InitCtx> define tcf(providerTopicFactory)
InitCtx> end
Stopping MQSeries Classes for Java(tm) Message Service Administration
For more information on using the MQ JMS Administration Tool, see the documentation located under the java/doc/En_US/html/text/csqzaw10.htm#HDRJMS77H1 of the MQSeries installation directory. For example, use the DISPLAY command to display properties of the defined objects:
InitCtx> display q(theQueue)
QUEUE(SYSTEM.DEFAULT.LOCAL.QUEUE)
QMANAGER()
PERSISTENCE(APP)
CCSID(1208)
TARGCLIENT(JMS)
ENCODING(NATIVE)
PRIORITY(APP)
EXPIRY(APP)
VERSION(1)

InitCtx> display qcf(providerFactory)
QMANAGER()
TEMPMODEL(SYSTEM.DEFAULT.MODEL.QUEUE)
TRANSPORT(BIND)
VERSION(1)

InitCtx> display t(theTopic)
PRIORITY(APP)
CCSID(1208)
EXPIRY(APP)
PERSISTENCE(APP)
TOPIC(SampleTopic)
ENCODING(NATIVE)
TARGCLIENT(JMS)
VERSION(1)

InitCtx> display tcf(providerTopicFactory)
QMANAGER()
BROKERQMGR()
TRANSPORT(BIND)
BROKERVER(V1)
VERSION(1)
BROKERCONQ(SYSTEM.BROKER.CONTROL.QUEUE)
BROKERPUBQ(SYSTEM.BROKER.DEFAULT.STREAM)

c. Because creating and destroying JMS connections can be expensive, iAS supports JMS connection pooling to improve system performance.  When using queue connection pooling, the application server does this using a proxy class that interposes between application requests and the standard QueueConnectionFactory.  Applications can lookup the QueueConnectionFactoryProxy in JNDI and use it as if it's an ordinary QueueConnectionFactory--the proxy will transparently provide the pooling functionality.  Before creating the proxy, it's necessary to modify the file [iAS-install-directory]\ias\jms\bin\jmspadm.bat to ensure that IAS_BASEPATH correctly reflects the installation location for iAS.  To create a QueueConnectionFactoryProxy (which implements the standard JMS interface QueueConnectionFactory), execute this script with the name of the proxy as well as the name of the QueueConnectionFactory created in the previous step:
[iAS-install-directory]\ias\jms\bin\jmspadm theFactory providerFactory
d. To create a TopicConnectionFactoryProxy (which implements the standard JMS interface TopicConnectionFactory), execute this script with the name of the proxy as well
as the name of the TopicConnectionFactory created in the previous step:
[iAS-install-directory]\ias\jms\bin\jmspadm theTopicFactory providerTopicFactory

Configure iPlanet Runtime for MQSeries

The iPlanet Application Server runtime environment must be modified to enable the application server to access the MQSeries JMS classes. This modification involves setting the CLASSPATH and LIBPATH variables in the application server's Registry.

Modify the CLASSPATH  and LIBPATH of the application server to include the MQSeries JMS implementation classes and binaries.  On Windows, the application server uses the CLASSPATH and LIBPATH setting defined in the application server's registry. (Setting the Windows system environment variable CLASSPATH or PATH will not affect the setting used by the application server). To modify the registry:

Now that MQSeries and the application server are configured, proceed to setting up the JMS sample applications.
 

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