![]() |
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
Compiling and Assembling the Sample Application
Deploying the Sample Application
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
Set Environment Variables
The following environment variables need to be set. For example:
You can set these environment variables in a command window or you can have them set in a shell script of your choice.
Install and Configure Java Message Service (JMS) Providers
The JMS Queue Simple sample application has been tested with the following JMS providers:
Sun ONE Message Queue (MQ)
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:
Access the Sun ONE Application Server Administration Tool from a web browser.
To Test if the broker is running, do the following: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.
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
If the broker is not running, start the broker using the command imqbrokerd.
- 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.
- $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:
Run the asadmin command using the multi mode feature in which you can enter multiple asadmin subcommands.
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.
Create QueueConnectionFactory objects.
- $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
- 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:
Create Destination Queue objects.
- asadmin>create-jms-resource --instance server1 --resourcetype javax.jms.QueueConnectionFactory --property imqBrokerHostPort=7676:imqBrokerHostName=optimus jms/sampleQCF1
List JMS resources to verify the list of all JMS objects added to a given server instance.
- 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
- 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:
Create JMS physical destinations.
- The list of JMS resources are:
- jms/sampleQCF
- jms/sampleQCF1
- jms/sampleQCF1
- jms/sampleQCF3
- jms/sampleQ
- jms/sampleQ1
- jms/sampleQ2
- jms/sampleQ3
Reconfigure the server instance to make sure the changes you made have been propagated to the server.xml file. For example:
- 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
- asadmin>reconfig <instance_name>
- Where <instance_name> is the application server instance name (e.g. server1).
IBM WebSphere MQ
The following links provide instructions to test the JMS Queue Simple sample application using IBM WebSphere MQ:
Installing IBM TM 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).
Go to the src directory of the sample. For example:
The default target core will be executed to compile java files and rebuild the WAR file.
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.
- cd $AS_HOME/samples/jms/queue/simple/src
The default name and password is guest/guest. You can remove the value and leave the name and password attributes blank.Compile and assemble the application. For example:
- $AS_HOME/bin/asant
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.
Deploy the application.
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:
Clean the web application project area using the asant clean command. For example:
- Once you have re-created the sample application from scratch proceed to Deploying the Sample Application.
Generate javadocs (optional). For example:
- $AS_HOME/bin/asant clean
After javadocs have been generated, you may access them at $AS_HOME/samples/jms/queue/simple/javadocs
- $AS_HOME/bin/asant javadocs
$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.
Go to the src directory of the sample. For example:
Run asant using deploy task. For example:
- cd $AS_HOME/samples/jms/queue/simple/src
- $AS_HOME/bin/asant deploy
Go to the root of the sample directory. For example:
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).
Execute asadmin to deploy application to the local application server instance. For example:
- cd $AS_HOME/samples/jms/queue/simple
- $AS_HOME/bin/asadmin deploy -u <admin_username> -w <admin_password> -H <host> -p <adminserver_port> --instance <instance_name> queueSample.ear
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.
From your web browser, access the Sun ONE Application Server by entering the URL. For example:
If the deployment processes correctly, you will see the original panel displaying the queueSample application as deployed.
Enter the server administrator's username and password to access the admin server.
- http://<server-host>:<admin-port>
On the left panel, navigate the tree by clicking on the following:
On the right panel, click on the Deploy button.
- App Server Instances->server1->Applications->Enterprise Apps
You will be prompted for the application name.
- Select the file (from disk) to be deployed (queueSample.ear)
- Click OK.
- Type queueSample
- Click OK.
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>
$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:
- cd to $AS_HOME/samples/jms/queue/simple/src
- 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:
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/sampleQDelete 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
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:
From your browser , access the application launch page at: http://<host>:<port>/queueSample/queueSample
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.
- 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
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:
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.
- $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
Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated July 10, 2002