![]() |
JMS Topic Simple Sample Application |
Chapter 1 Java Message Service (JMS) Topic Simple Sample Application
This document describes how to utilize the JMS Topic Simple sample application in conjunction with Sun Java (tm) System 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 simple publish-subscribe topic application is a sample JMS application designed to demonstrate how a JMS client can publish and subscribe a message to a JMS topic destination. The application is a servlet which, based on the client's request, publishes a message to a topic and delivers the message from the topic to the subscibers. The published message is displayed on the subscibers' message text box.In order to successfully deploy and run the JMS Topic 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:
setenv IMQ_HOME $AS_HOME/imq
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 Topic Simple sample application has been tested with the following JMS providers:
Sun Java (tm) System Message Queue (MQ)
You can choose either product to test the sample application. However, it is suggested that you test with Sun Java (tm) System MQ first. Because Sun Java (tm) System MQ is bundled with Sun Java (tm) System Application Server, it is thereby faster and easier to setup and create JMS resources.
Sun Java (tm) System Message Queue (MQ)
In this section, you will learn how to test and start the Sun Java (tm) System Message Queue (MQ) Broker. The term Broker refers to the software component that routes and delivers messages.The Sun Java (tm) System MQ message service is bundled with and supported by the Sun Java (tm) System Application Server. The product resides under the $AS_HOME/imq directory.
Sun Java (tm) System MQ can consist of one or more brokers. When you install Sun Java (tm) System 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 Java (tm) System 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:
If the broker is not running, start the broker using the command imqbrokerd.
- $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:
- $IMQ_HOME/bin/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.
- $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 &
To run the JMS Topic Simple sample application, two administered objects must be created and retrievable from a JNDI namespace: a TopicConnectionFactory bound under the name jms/sampleTCF and a Topic bound under the name jms/sampleTopic
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 seting up the Sun Java (tm) System MQ, you can proceed to Compiling and Assembling the Sample Application or Deploying the Sample Application section.
Create a TopicConnectionFactory object.
- %$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
Create a Destination Topic object.
- asadmin>create-jms-resource --instance <instance_name> --resourcetype javax.jms.TopicConnectionFactory --property imqBrokerHostPort=<broker_port>:imqBrokerHostName=<broker_host> jms/sampleTCF
- 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.TopicConnectionFactory --property imqBrokerHostPort=7676:imqBrokerHostName=optimus jms/sampleTCF
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.Topic --property imqDestinationName=SampleTopic jms/sampleTopic
- Where <instance_name> is the application server instance name (e.g. server1).
- For example:
- asadmin>create-jms-resource --instance server1 --resourcetype javax.jms.Topic --property imqDestinationName=SampleTopic jms/sampleTopic
Create JMS physical destinations.
- 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/sampleTCF
- jms/sampleTopic
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 topic SampleTopic
- 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 topic SampleTopic
- 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 Topic 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 Topic 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/topic/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 topicSample.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/topic/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 Topic 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 Java (tm) System 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 Java (tm) System 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 topicSample.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 topicSample.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/topic/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/topic/simple
- $AS_HOME/bin/asadmin deploy -u <admin_username> -w <admin_password> -H <host> -p <adminserver_port> --instance <instance_name> topicSample.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 Java (tm) System Application Server Administration Tool to quickly read the EAR file and deploy it to the Application Server.
From your web browser, access the Sun Java (tm) System Application Server by entering the URL. For example:
If the deployment processes correctly, you will see the original panel displaying the topicSample 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 (topicSample.ear)
- Click OK.
- Type topicSample
- Click OK.
Verifying Deployment
As an optional step, you can use the Sun Java (tm) System 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
- TopicSample
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/topic/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 Java (tm) System 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/sampleTCF
asadmin delete-jms-resource -u admin -w asadmin -H optimus -p 9000 --instance server1 jms/sampleTopicDelete 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 topic SampleTopic
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 Topic Simple sample application, do the following:
From your browser , access the application launch page at: http://<host>:<port>/topicSample/topicSample
Once the application page is displayed on the browser; select zero or more subscribers from the check boxes A, B, C, D; type a message to publish; then click the Publish button. The message will appear on the message boxes of the subscribers.
- Where <host> is the machine on which Sun Java (tm) System application server is installed and <port> is the http server port you entered when installing the application server. For example:
- http://optimus:8080/topicSample/topicSample
Troubleshooting and Known Issues
If you receive a not found error when running the application by accessing the URL http://<host>:<port>/topicSample/topicSample, you should restart the server instance and retry. To restart the server instance, run the following commands:
There is a known issue to this Topic 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 24, 2002