Sun ONE logo      Next     
JMS Queue Simple Sample Application



Chapter 1   Java Message Service (JMS) Queue Simple Sample Application


This document describes how to utilize the JMS Queue Simple sample application in conjunction with Sun ONE Application Server version 7.

This sample application document contains the following sections:



Overview

The JMS Queue Simple sample application is a sample JMS client application designed to demonstrate how a JMS client can send and receive a message to a point-to-point JMS queue. The application is a servlet which handles the message delivery to the target queues based on the request of a client. The servlet also takes care of retrieving the message and displaying it to the message box of the target receiver. The following diagram illustrates the technology involved:



In order to successfully deploy and run the JMS Queue Simple sample application, the following tasks need to be completed:


Set Environment Variables

The following environment variables need to be set. For example:

  • setenv IMQ_HOME $AS_HOME/imq

  • setenv JAVA_HOME $AS_HOME/jdk

  • setenv PATH $JAVA_HOME/bin:$AS_HOME/bin:$PATH

You can set these environment variables in a command window or you can have them set in a shell script of your choice.



Note The AS_HOME variable must be set to the directory where Sun ONE Application Server is installed. For example, when installing the application server in /export/sun/appserver7, the AS_HOME is set to /export/sun/appserver7.




Install and Configure Java Message Service (JMS) Providers

The JMS Queue Simple sample application has been tested with the following JMS providers:

You can choose either product to test the sample application. However, it is suggested that you test with Sun ONE MQ first. Because Sun ONE MQ is bundled with Sun ONE Application Server, it is thereby faster and easier to setup and create JMS resources.


Sun ONE Message Queue (MQ)

In this section, you will learn how to test and start the Sun ONE Message Queue (MQ) Broker. The term Broker refers to the software component that routes and delivers messages.

The Sun ONE MQ message service is bundled with and supported by the Sun ONE Application Server. The product resides under the $AS_HOME/imq directory.

Sun ONE MQ can consist of one or more brokers. When you install Sun ONE Application Server, a default broker is created on localhost, instance server1. Port number 7676 will be selected as the port of the default broker if it has not been used. Otherwise, a different port number will be selected.

To find out the port number designated for the default broker, do the following:

  1. Access the Sun ONE Application Server Administration Tool from a web browser.

  2. Navigate down the following folders by clicking on them in the left hand frame:

    App Server Instances->server1->JMS->Service

    You will see the default broker service information displayed on the right hand frame, including the port number.

To Test if the broker is running, do the following:

  1. Use the imqcmd utility to display the information about the broker. For example:

    $IMQ_HOME/bin/imqcmd query bkr -u <admin_user> -p <admin_password> -b <host>:<jms_port>

    Where <admin-user> is the admin user name ("admin" by default), <admin_password> is the admin password ("admin by default), <host> is the machine the broker is on, and <jms-port> is the jms-service port assigned to the broker.

    If the broker is running, you will receive an output similar to the one below:

    imqcmd query bkr -u admin -p admin -b localhost:7676

    Querying the broker specified by:

    -------------------------
    Host Primary Port
    -------------------------
    localhost 7676

    Auto Create Queues true
    Auto Create Topics true
    Auto Created Queue Delivery Policy Single
    Cluster Broker List (active) optimus/192.18.114.108:7676 (domain1_server1)
    Cluster Broker List (configured)
    Cluster Master Broker
    Cluster URL
    Current Number of Messages in System 0
    Current Size of Messages in System (bytes) 0
    Instance Name domain1_server1
    Log Level INFO
    Log Rollover Interval (seconds) 604800
    Log Rollover Size (bytes) 0 (unlimited)
    Max Message Size 70m
    Max Number of Messages in System 0 (unlimited)
    Max Size of Messages in System 0 (unlimited)
    Primary Port 7676
    Version 3.0

    Successfully queried the broker.

  2. If the broker is not running, start the broker using the command imqbrokerd.

    $IMQ_HOME/bin/imqbrokerd -tty -port <jms_port> -name <instance_name> &

    Where <jms_port> is the jms-service port, and <instance_name> is your application server instance name.

    For example:

    $IMQ_HOME/bin/imqbrokerd -tty -port 7676 -name server1 &


Creating JMS Resources
The Sun ONE MQ provides 2 types of administered objects: ConnectionFactory and Destination. The JMS Queue Simple sample application will access these objects through JNDI lookup.

To create these objects using the asadmin command line tool, do the following:

  1. Run the asadmin command using the multi mode feature in which you can enter multiple asadmin subcommands.


    Note For every sub command you enter, you are required to provide global parameters such as user name, password, host, etc. In the multi mode, you can pre-set the global parameter once and thus will not have to enter them every time.



    $AS_HOME/bin/asadmin multimode

    asadmin>export AS_ADMIN_USER=<admin_username> AS_ADMIN_PASSWORD=<admin_password> AS_ADMIN_HOST=<host> AS_ADMIN_PORT=<adminserver_port> AS_ADMIN_INSTANCE=<instance_name>

    Where <admin_username> is application server admin user name, <admin_password> is the admin password, <host> is the machine on which the application server is installed , < adminserver_port> is admin server port of the application server, and < instance_name> is the application server instance name (e.g. server1).

    For example:

    asadmin>export AS_ADMIN_USER=admin AS_ADMIN_PASSWORD=iasadmin AS_ADMIN_HOST=optimus AS_ADMIN_PORT=9000 AS_ADMIN_INSTANCE=server1

  2. Create QueueConnectionFactory objects.

    asadmin>create-jms-resource --instance <instance_name> --resourcetype javax.jms.QueueConnectionFactory --property imqBrokerHostPort=<broker_port>:imqBrokerHostName=<broker_host> jms/sampleQCF

    asadmin>create-jms-resource --instance <instance_name> --resourcetype javax.jms.QueueConnectionFactory --property imqBrokerHostPort=<broker_port>:imqBrokerHostName=<broker_host> jms/sampleQCF1

    asadmin>create-jms-resource --instance <instance_name> --resourcetype javax.jms.QueueConnectionFactory --property imqBrokerHostPort=<broker_port>:imqBrokerHostName=<broker_host> jms/sampleQCF2

    asadmin>create-jms-resource --instance <instance_name> --resourcetype javax.jms.QueueConnectionFactory --property imqBrokerHostPort=<broker_port>:imqBrokerHostName=<broker_host> jms/sampleQCF3

    Where <instance_name> is the application server instance name (e.g. server1), <broker_port> is the port of the broker, and <broker_host> is the host the broker is running on.

    For example:

    asadmin>create-jms-resource --instance server1 --resourcetype javax.jms.QueueConnectionFactory --property imqBrokerHostPort=7676:imqBrokerHostName=optimus jms/sampleQCF1

  3. Create Destination Queue objects.

    asadmin>create-jms-resource --instance <instance_name> --resourcetype javax.jms.Queue --property imqDestinationName=SampleQueue jms/sampleQ

    asadmin>create-jms-resource --instance <instance_name> --resourcetype javax.jms.Queue --property imqDestinationName=SampleQueue1 jms/sampleQ1

    asadmin>create-jms-resource --instance <instance_name> --resourcetype javax.jms.Queue --property imqDestinationName=SampleQueue2 jms/sampleQ2

    asadmin>create-jms-resource --instance <instance_name> --resourcetype javax.jms.Queue --property imqDestinationName=SampleQueue3 jms/sampleQ3

    Where <instance_name> is the application server instance name (e.g. server1).

    For example:

    asadmin>create-jms-resource --instance server1 --resourcetype javax.jms.Queue --property imqDestinationName=SampleQueue3 jms/sampleQ3

  4. List JMS resources to verify the list of all JMS objects added to a given server instance.

    asadmin>list-jms-resources <instance_name>

    Where <instance_name> is the application server instance name (e.g. server1).

    You should receive a list similar to the one displayed below:

    The list of JMS resources are:

    jms/sampleQCF
    jms/sampleQCF1
    jms/sampleQCF1
    jms/sampleQCF3
    jms/sampleQ
    jms/sampleQ1
    jms/sampleQ2
    jms/sampleQ3

  5. Create JMS physical destinations.

    asadmin>create-jmsdest --instance <instance_name> --desttype queue SampleQueue

    asadmin>create-jmsdest --instance <instance_name> --desttype queue SampleQueue1

    asadmin>create-jmsdest --instance <instance_name> --desttype queue SampleQueue2

    asadmin>create-jmsdest --instance <instance_name> --desttype queue SampleQueue3

    Where <instance_name> is the application server instance name (e.g. server1).

    For example:

    asadmin>create-jmsdest -u admin -w iasadmin -H optimus -p 9000 --instance server1 --desttype queue SampleQueue

  6. Reconfigure the server instance to make sure the changes you made have been propagated to the server.xml file. For example:

    asadmin>reconfig <instance_name>

    Where <instance_name> is the application server instance name (e.g. server1).

After you have finished setting up the Sun ONE MQ, you can proceed to Compiling and Assembling the Sample Application or Deploying the Sample Application section.


IBM WebSphere MQ

The following links provide instructions to test the JMS Queue Simple sample application using IBM WebSphere MQ:

After you have finished installing and configuring WebSphere MQ, you may proceed to Compiling and Assembling the Sample Application or Deploying the Sample Application.



Compiling and Assembling the Sample Application



This section contains instructions to build and assemble the JMS Queue Simple sample application from scratch using Command Line Interface (CLI).

  1. Go to the src directory of the sample. For example:

    cd $AS_HOME/samples/jms/queue/simple/src

  2. If you wish deploy the application to run with WebSphere MQ, you have to modify the sun-web.xml to take out the name and password of the default-resource-principal element.
    The default name and password is guest/guest. You can remove the value and leave the name and password attributes blank.

  3. Compile and assemble the application. For example:

    $AS_HOME/bin/asant

The default target core will be executed to compile java files and rebuild the WAR file.

Note If you have $AS_HOME/bin set in your PATH as shown in the section Set Environment Variables, then simply type asant instead of $AS_HOME/bin/asant.



  1. Deploy the application.

    Once you have re-created the sample application from scratch proceed to Deploying the Sample Application.

  2. Clean the web application project area using the asant clean command. For example:

    $AS_HOME/bin/asant clean

  3. Generate javadocs (optional). For example:

    $AS_HOME/bin/asant javadocs

    After javadocs have been generated, you may access them at $AS_HOME/samples/jms/queue/simple/javadocs

You can run asant all command to compile and assemble the application, verify the queueSample.ear file, generate javadocs, and deploy the application all in one step. For example:

$AS_HOME/bin/asant all



Deploying the Sample Application

In this section, you will learn how to deploy the JMS Queue Simple sample application.

Select one of the following approaches to deploying the application:

  • Command Line-based Deployment describes how to manually register the application in Sun ONE Application Server using a Command Line Interface (CLI). This is the fastest means of deploying the sample application.

  • GUI-based Deployment describes how to use the Sun ONE Application Server Deployment Tool to import and deploy the sample application.


Command Line-based Deployment

Since a complete EAR file is supplied, the fastest means of setting up the application is to use the command line utilities described in this section.

The pre-built queueSample.ear file is an Enterprise Archive file that contains the Web Archive (WAR) file of the application. Within the WAR file resides the XML deployment descriptor files, application class files, JSPs and other content required by the application.

Deploying the pre-built queueSample.ear file is simple. Deploy either Using the asant script or by Using the asadmin command.


Using the asant script

  1. Go to the src directory of the sample. For example:

    cd $AS_HOME/samples/jms/queue/simple/src

  2. Run asant using deploy task. For example:

    $AS_HOME/bin/asant deploy



Note If you run asant deploy for the first time, you'll be asked to enter your Sun ONE app-server host name, admin port, admin user, password and instance name The subsequent runs of asant will get this information from a properties file create after the first time you ran asant deploy.




Using the asadmin command

  1. Go to the root of the sample directory. For example:

    cd $AS_HOME/samples/jms/queue/simple

  2. Execute asadmin to deploy application to the local application server instance. For example:

    $AS_HOME/bin/asadmin deploy -u <admin_username> -w <admin_password> -H <host> -p <adminserver_port> --instance <instance_name> queueSample.ear

Where <admin_username> is application server admin user name, <admin_password> is the admin password, <host> is the machine on which the application server is installed, <adminserver_port> is admin server port of the application server, and <instance_name> is the application server instance name (e.g. server1).

If you would like to verify the registration of the application, you may proceed to Verifying Deployment. Otherwise, proceed to Running the Sample Application.


GUI-based Deployment

Since a pre-built Enterprise Archive (EAR) file for the sample application is included with the application server, you can use the Sun One Application Server Administration Tool to quickly read the EAR file and deploy it to the Application Server.

  1. From your web browser, access the Sun ONE Application Server by entering the URL. For example:

    http://<server-host>:<admin-port>

  2. Enter the server administrator's username and password to access the admin server.

  3. On the left panel, navigate the tree by clicking on the following:

    App Server Instances->server1->Applications->Enterprise Apps

  4. On the right panel, click on the Deploy button.

    Select the file (from disk) to be deployed (queueSample.ear)

    Click OK.

  5. You will be prompted for the application name.

    Type queueSample

    Click OK.

If the deployment processes correctly, you will see the original panel displaying the queueSample application as deployed.


Verifying Deployment

As an optional step, you can use the Sun ONE Application Server Administration Tool to verify that the application has been registered. Otherwise, proceed directly to Running the Sample Application.

To verify the registration of the application, do the following:

Execute the command asadmin list-components to display applications deployed with a server instance.

$AS_HOME/bin/asadmin list-components -u <admin_username> -w <admin_password> -H <host> -p <adminserver_port> <instance_name>

For example:

$AS_HOME/bin/asadmin list-components -u admin -w iasadmin -H optimus -p 9000 server1

You should see output similar to what is displayed below:

List of Deployed Applications
queueSample


Undeploying the Sample Application

You can undeploy the sample application without deleting all the JMS resources that you have already set up. To undeploy the sample application, run the following command:

  1. cd to $AS_HOME/samples/jms/queue/simple/src
  2. Execute asant undeploy

If you want to delete the JMS resources which you've created with IBM Websphere MQ , please refer to the product document for how to delete the JMS resources.
For JMS resources that have been created with Sun ONE MQ , do the following to delete them:

  1. Delete JMS resoures.

    $AS_HOME/bin/asadmin delete-jms-resource -u <admin_username> -w <admin_password> -H <host> -p <adminserver_port> --instance <instance_name> <jndiname>

    Where <jndiname> is the JNDI name associated with the JMS resources that you have created.

    For example:

    asadmin delete-jms-resource -u admin -w asadmin -H optimus -p 9000 --instance server1 jms/sampleQCF
    asadmin delete-jms-resource -u admin -w asadmin -H optimus -p 9000 --instance server1 jms/sampleQ

  2. Delete JMS physical destination.

    $AS_HOME/bin/asadmin delete-jmsdest -u <admin_username> -w <admin_password> -H <host> -p <adminserver_port> --instance <instance_name> --desttype <type> <destination_name>

    Where <type> is the destination type which is either queue or topic. <destination_name> is the named destinations that you have created.

    For example:

    asadmin delete-jmsdest -u admin -w asadmin -H optimus -p 9000 --instance server1 --desttype queue SampleQueue

  3. Reconfigure the server instance.

    $AS_HOME/bin/asadmin reconfig -u <admin_username> -w <admin_password> -H <host> -p <adminserver_port> <instance_name>



Running the Sample Application



To run the JMS Queue Simple sample application, do the following:

  1. From your browser , access the application launch page at: http://<host>:<port>/queueSample/queueSample

    Where <host> is the machine on which Sun ONE application server is installed and <port> is the http server port you entered when installing the application server. For example:

    http://optimus:8080/queueSample/queueSample

  2. Once the application page is displayed on the browser, select a Message Sender and Message Receiver, type a message to send to the receiver from the sender, then click the Process button. You should see the message displayed on the message box of the selected receiver.



Troubleshooting and Known Issues

  • If you receive a not found error when running the application by accessing the URL http://<host>:<port>/queueSample/queueSample, you should restart the server instance and retry. To restart the server instance, run the following commands:

    $AS_HOME/bin/asadmin

    asadmin> stop-instance -u <admin_username> -w <admin_password> -H <host> -p <adminserver_port> <instance_name>

    asadmin> start-instance -u <admin_username> -w <admin_password> -H <host> -p <adminserver_port> <instance_name>

    asadmin> exit

  • There is a known issue to this Queue Simple sample application. That is User Session is not implemented. As a result, if two or more users access the application from different browsers, they can see each others' messages.

Next     
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated July 10, 2002