Overview

WebSphere Application Server V5 (hereafter called Application Server) provides a new messaging feature that includes support for Java Messaging Service (JMS) providers. Application Server includes an internal JMS provider called the embedded JMS provider. This provider relies on a subset of the IBM messaging technology, WebSphere MQ V5.3, for point-to-point messaging, and WebSphere MQ Event Broker V2.1 for publish/subscribe messaging. Application Server V5 also supports WebSphere MQ as the JMS provider.

This article describes how to enable a JMS Java 2 Platform Enterprise Edition (J2EE) application to use either the embedded JMS provider or the MQ JMS provider in Application Server.

Back to top

Install the JMS providers

The following sections describe how to install the embedded JMS provider or the MQ JMS provider.

Embedded JMS provider

To use the embedded JMS support, select the Embedded Messaging Client and the Embedded Messaging Server options when installing Application Server V5. The embedded messaging client enables applications running in the Application Server to communicate with the WebSphere JMS provider. The embedded messaging server contains the messaging server functions of the WebSphere JMS provider and provides point-to-point and publish/subscribe messaging features. If Websphere MQ already exists on the system, the Application Server can use it as the JMS provider, but you must ensure you have the correct WebSphere MQ version and features installed, as described in the next section.

MQ JMS provider

Application Server V5 supports WebSphere MQ as an alternate JMS provider. To install the MQ JMS provider, do the following:

1. Install WebSphere MQ V5.3 with the required MQ features, as described in the installation instructions provided with WebSphere MQ, and supported by Application Server V5. This enables point-to-point messaging support.
2. If you need publish/subscribe messaging support, you must also install a publish/subscribe broker. Ensure that the publish/subscribe broker supports the installed Websphere MQ. IBM provides three publish/subscriber brokers:
   • WebSphere MQ Event Broker V2.1
   • WebSphere Business Integration (hereafter called BI) Event Broker V5
   • WebSphere Business Integration Message Broker V5

In this article, we'll use the BI Message Broker V5 as the publish/subscribe broker.

Back to top

Configure and start the JMS providers

The following sections describe how to configure and start the embedded JMS provider and the MQ JMS provider.

Embedded JMS provider

Once you've installed the Application Server to use the embedded JMS provider, go to the Administration Console and complete the following steps to enable your JMS resources to be used by your JMS J2EE application:

1. In the Application Server administration console, select Resources => WebSphere JMS Provider and create the JMS resources (that is, Queue Connection Factories, Queue Destinations, TopicConnectionFactories, Topic Destinations) used by the JMS J2EE application. Create Queue Connection Factories and Queue destinations for use in point-to-point messaging applications. Create Topic Connection Factories and Topic destinations for use in publish/subscribe messaging applications.
   Figure 1. Websphere JMS Provider
   
   
2. The example JMS resources SmQueueConnectionFactory, SmTopicConnectionFactory and SmQueueSub are created as shown in the examples below:
   Figure 2. Example Queue Connection Factory
   
   
   Figure 3. Example Topic Connection Factory
   
   
   Figure 4. Example Queue Destination
   
   
3. To ensure the JMS resources are correctly bound into the Java Naming and Directory Interface (JNDI) namespace, look for the following key messages in the Application Server SystemOut.log running the JMS J2EE application. The resources are bound into the namespace so that they can be looked up dynamically by an application. Use the javax.naming.InitialContext class lookup methods to locate the resources. Additionally, the administrator must configure a scope for the JMS resource when it is created. This determines whether the JMS resource can be used by an application server, all application servers running on the node or all application servers running in the Network Deployment cell.

   [10/5/04 16:11:40:062 EDT] 4d253026 ResourceMgrIm I WSVR0049I: Binding SmQueueConnectionFactory as jms/SmQueueConnectionFactory [10/5/04 16:11:40:062 EDT] 4d253026 ResourceMgrIm I WSVR0049I: Binding SmQueueSub as jms/SmQueueSub [10/5/04 16:11:40:109 EDT] 4d253026 ResourceMgrIm I WSVR0049I: Binding SmTopicConnectionFactory as jms/SmTopicConnectionFactory

   
   
4. In the administration console, add the JMS Queue and Topic destination resources to the JMS server for the Application Server running the JMS J2EE application. Also, set the JMS server initial state property to started to ensure the JMS server starts up automatically when the Application Server starts. For example, add the JMS Queue destination, SmQueueSub, and set the JMS Server initial state property to started as shown in the example below:
   1. Select Servers => Application Servers. This displays a table of the application servers in the administrative domain.
   2. In the content pane, click the name of the Application Server (for example, MYServer). This displays the properties of the Application Server in the content pane.
   3. In the content pane, under Additional Properties, select Server components => JMS Servers. This displays the JMS server properties in the content pane.
   4. Add the Queue and Topic destinations that you set up to the Queue names property for the JMS server.
   5. Ensure the JMS Server Initial State property is set to started.
   
   Figure 5. JMS Server Properties
   
   
5. Look for the following key messages in the Application Server SystemOut.log running the JMS J2EE application to ensure the embedded JMS server is starting successfully:

   [5/11/04 11:28:51:234 EDT] 4dc429c9 JMSEmbeddedPr A MSGS0050I: Starting the Queue Manager [5/11/04 11:28:52:953 EDT] 4dc429c9 JMSEmbeddedPr A MSGS0051I: Queue Manager open for business [5/11/04 11:28:52:953 EDT] 4dc429c9 JMSEmbeddedPr A MSGS0052I: Starting the Broker [5/11/04 11:28:55:453 EDT] 4dc429c9 JMSEmbeddedPr A MSGS0053I: Broker open for business

   
   
6. If the JMS J2EE application uses Message Driver Beans, you'll need to create the listener ports in the administration console. Listener ports enable a JMS application to asynchronsouly listen for messages. The listener ports used by the Message Driver Beans are created in the Message Listener Services for the application server running the JMS J2EE application. The JMS J2EE application descriptor below shows a sample definition (highlighted) for a listener port:

   <?xml version="1.0" encoding="UTF-8"?> <ejbbnd:EJBJarBinding xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:ejbbnd="ejbbnd.xmi" xmlns:ejb="ejb.xmi" xmi:id="EJBJarBinding_1055163252462" currentBackendId="DB2UDBNT_V72_1"> <ejbJar href="META-INF/ejb-jar.xml#ejb-jar_ID"/> <ejbBindings xmi:id="EnterpriseBeanBinding_1055163252462" jndiName="ejb/com/ibm/pvc/ins/sm/server/SubscriptionServiceHome"> <enterpriseBean xmi:type="ejb:Session" href="META-INF/ejb-jar.xml#SubscriptionService"/> </ejbBindings> <ejbBindings xmi:id="EnterpriseBeanBinding_1055197456298" jndiName="ejb/com/ibm/websphere/startupservice/SubscriptionStartUpBean"> <enterpriseBean xmi:type="ejb:Session" href="META-INF/ejb-jar.xml#AppStartUp"/> </ejbBindings> <ejbBindings xmi:id="EnterpriseBeanBinding_1056144206631" jndiName="ejb/com/ibm/pvc/ins/sm/database/Triggers"> <enterpriseBean xmi:type="ejb:ContainerManagedEntity" href="META-INF/ejb-jar.xml#Triggers"/> </ejbBindings> <ejbBindings xmi:type="ejbbnd:MessageDrivenBeanBinding" xmi:id="MessageDrivenBeanBinding_1060968316889" listenerInputPortName="SmLpSub"> <enterpriseBean xmi:type="ejb:MessageDriven" href="META-INF/ejb-jar.xml#MessageDriven_1060968316889"/> </ejbBindings> <ejbBindings xmi:id="EnterpriseBeanBinding_1062106510434" jndiName="ejb/com/ibm/pvc/ins/sm/server/SubscriptionAdminServiceHome"> <enterpriseBean xmi:type="ejb:Session" href="META-INF/ejb-jar.xml#SubscriptionAdminService"/> </ejbBindings> <ejbBindings xmi:id="EnterpriseBeanBinding_1082140050533" jndiName="ejb/com/ibm/pvc/ins/sm/database/SubOwner"> <enterpriseBean xmi:type="ejb:ContainerManagedEntity" href="META-INF/ejb-jar.xml#SubOwner"/> </ejbBindings> <defaultCMPConnectionFactory xmi:id="CMPConnectionFactoryBinding_1056146794783" jndiName="jdbc/insdb" resAuth="Container"/> </ejbbnd:EJBJarBinding>

   
   For example, to define the listener port SmLpSub, for a JMS J2EE application, do the following:
   1. In the navigation pane of the administration console, select Servers => Application Servers.
   2. Click on the server (for example, MYServer) that contains your application.
   3. Select the Configuration tab.
   4. In theAdditional Properties section, select the Message Listener Service.
   5. In the Additional Properties section, select the Listener Ports.
   6. Click New to add the listener port SmLpSub.
   7. Specify SmLpSub in the Name
   8. In the Connection Factory jndi name field, specify jms/SmQueueConnectionFactory
   9. In the Destination jndi name field, specify jms/SmQueueSub
   
   Figure 6. Example Listener Port SmLpSub
   
   
7. Look for the following key message in the Application Server SystemOut.log running the JMS J2EE application to ensure that the Listener Port is defined correctly:

   [10/5/04 16:11:55:859 EDT] 4d253026 MDBListenerIm I WMSG0042I: MDB Listener SmLpSub started successfully for JMSDestination jms/SmQueueSub

   
   
8. Once you've completed the steps above, start the Application Server, then deploy and start the JMS J2EE application from the administration console to verify the application.

MQ JMS provider

Once WebSphere MQ, the BI Message Broker, and the Application Server are installed to use the MQ JMS provider, perform the following steps to enable your JMS resources to be used by your JMS J2EE application:

1. In WebSphere MQ, create a queue manager. When creating the queue manager, note the name, host and port of the queue manager, which are needed for setting the JMS resources in the Application Server. The following WebSphere MQ command demonstrates creating an example queue manager, WAS_mytest1_MYServer:

   crtmqm WAS_mytest1_MYServer

   
   See the WebSphere MQ documentation for details on creating a queue manager.
2. In BI Message Broker, create a broker for JMS publish/subscribe messaging associated with the queue manager you created. A broker is associated with a queue manager and can be associated with only one queue manager. The following BI Message Broker command demonstrates creating an example broker, MYBroker1 associated with the queue manager WAS_mytest1_MYServer:

   mqsicreatebroker MYBroker1 -i <service_id> -a <service_pswd> -q WAS_mytest1_MYServer -n <broker_db> <db> -u <db_id> -p <db_pswd>

   
   where:
   • <service_id> must be a member of the local group mqbrkrs and authorized to access the home directory where the BI Message Broker is installed
   • <service_pwsd> is the password associated with service_id
   • <broker_db> is the ODBC data source name (DSN) of the database in which the broker tables are created
   • <db> is the ODBC data source name (DSN) of the database in which the broker tables are created
   • <db_id> is the database user ID
   • <db_pwsd> is the database password associated with db_id
   See the WebSphere Business Integration Message Broker for additional details on the creating a broker.
3. In the Application Server administration console, configure the Application Server to use the MQ JMS provider. Navigate to Environment => Manage WebSphere Variables and set the MQJMS_LIB_ROOT environment variable to the directory where WebSphere MQ is installed, as shown below:
   Figure 7. Manage WebSphere Variables
   
   
4. In the Application Server administration console, select Resources => WebSphere MQ JMS Provider and create the MQ JMS resources (that is, Queue Connection Factories, Queue Destinations, TopicConnectionFactories, Topic Destinations) used by the JMS J2EE application.
   Figure 8. WebSphere MQ JMS Provider
   
   The example MQ JMS resources SmQueueConnectionFactory, SmTopicConnectionFactory and SmQueueSub are created as shown in the examples below:
   Figure 9. Example Queue Connection Factory
   
   
   Figure 10. Example Topic Connection Factory
   
   
   Figure 11. Example Topic Connection Factory (continued)
   
   
   Figure 12. Example Queue Destination
   
   
   Figure 13. Example Queue Destination (continued)
   
   
5. Below is an example of the key messages to look for in the Application Server SystemOut.log running the JMS J2EE application to ensure that the MQ JMS resources are correctly bound into the JNDI namespace:

   [10/5/04 16:11:40:062 EDT] 4d253026 ResourceMgrIm I WSVR0049I: Binding SmQueueConnectionFactory as jms/SmQueueConnectionFactory [10/5/04 16:11:40:062 EDT] 4d253026 ResourceMgrIm I WSVR0049I: Binding SmQueueSub as jms/SmQueueSub [10/5/04 16:11:40:109 EDT] 4d253026 ResourceMgrIm I WSVR0049I: Binding SmTopicConnectionFactory as jms/SmTopicConnectionFactory

   
   
6. In the Application Server administration console, select Servers => Application Servers and create the Listener Ports in the Message Listener Service for the application server running the JMS J2EE application. This step is the same as for the embedded JMS provider.
7. In Websphere MQ, create queue(s) on the queue manager to correspond to the JMS Queue destinations created in Application Server. The following WebSphere MQ commands create the example queue SmQueueSub on the queue manager WAS_mytest1_MYServer:

   strmqm WAS_mytest1_MYServer runmqsc WAS_mytest1_MYServer < sm_mq.mqsc end endmqm WAS_mytest1_MYServer

   
   where the contents of the file sm_mq.mqsc are:

   ********************************************************************/ * */ * SM Subscriber Queue */ * */ ********************************************************************/ ** Create a local queue DEFINE QLOCAL(SmQueueSub) REPLACE + DESCR(Subscription Manager Subscriber Queue) + * Persistent messages OK DEFPSIST(YES) + * Shareable SHARE DEFSOPT(SHARED) + * Maximum queue depth MAXDEPTH(100000)

   
   
8. In WebSphere MQ create the internal JMS publish/subscribe queues in the WebSphere MQ queue manager for JMS publish/subscribe messaging. The following WebSphere MQ commands create the internal JMS publish/subscribe queues for the example queue manager, WAS_mytest1_MYServer:

   strmqm WAS_mytest1_MYServer runmqsc WAS_mytest1_MYServer < mq_jms.mqsc end endmqm WAS_mytest1_MYServer

   
   where the contents of the file mq_jms.mqsc are:

   ********************************************************************/ * */ * JMS Publish/Subscribe Administration Queue */ * */ ********************************************************************/ ** Create a local queue DEFINE QLOCAL(SYSTEM.JMS.ADMIN.QUEUE) REPLACE + DESCR(Websphere MQ - JMS Classes - admin queue) + * Persistent messages OK DEFPSIST(YES) + * Non-Shareable NOSHARE ********************************************************************/ * */ * JMS Publish/Subscribe Subscriber Status Queue */ * */ ********************************************************************/ ** Create a local queue DEFINE QLOCAL(SYSTEM.JMS.PS.STATUS.QUEUE) REPLACE + DESCR(Websphere MQ - JMS Classes - PS status queue) + * Persistent messages OK DEFPSIST(YES) + * Shareable SHARE DEFSOPT(SHARED) ********************************************************************/ * */ * JMS Publish/Subscribe Report Queue */ * */ ********************************************************************/ ** Create a local queue DEFINE QLOCAL(SYSTEM.JMS.REPORT.QUEUE) REPLACE + DESCR(Websphere MQ - JMS Classes - Report queue) + * Persistent messages OK DEFPSIST(YES) + * Shareable SHARE DEFSOPT(SHARED) ********************************************************************/ * */ * JMS Publish/Subscribe Subscribers Model Queue */ * */ * Create model queue used by subscribers to create a permanent */ * queue for subsciptions */ * */ ********************************************************************/ * General reply queue */ DEFINE QMODEL(SYSTEM.JMS.MODEL.QUEUE) REPLACE + DESCR(Websphere MQ - JMS Classes - Model queue) + * Queue Definition Type DEFTYPE(PERMDYN) + * Shareable SHARE DEFSOPT(SHARED) ********************************************************************/ * */ * JMS Publish/Subscribe Default Non-Durable Shared Queue */ * */ * Create local queue used as the default shared queue by */ * non-durable subscribers */ * */ ********************************************************************/ ** Create a local queue DEFINE QLOCAL(SYSTEM.JMS.ND.SUBSCRIBER.QUEUE) REPLACE + DESCR(Websphere MQ - JMS Classes - PS ND shared queue) + * Persistent messages OK DEFPSIST(YES) + * Shareable SHARE DEFSOPT(SHARED) + * Maximum queue depth MAXDEPTH(100000) ********************************************************************/ * */ * JMS Publish/Subscribe Default Non-Durable Shared Queue for */ * ConnectionConsumer functionality */ * */ * Create local queue used as the default shared queue by */ * non-durable connection consumers */ * */ ********************************************************************/ ** Create a local queue DEFINE QLOCAL(SYSTEM.JMS.ND.CC.SUBSCRIBER.QUEUE) REPLACE + DESCR(Websphere MQ - JMS Classes - PS ND CC shared q) + * Persistent messages OK DEFPSIST(YES) + * Shareable SHARE DEFSOPT(SHARED) + * Maximum queue depth MAXDEPTH(100000) ********************************************************************/ * */ * JMS Publish/Subscribe Default Durable Shared Queue */ * */ * Create local queue used as the default shared queue by durable */ * subscribers */ * */ ********************************************************************/ ** Create a local queue DEFINE QLOCAL(SYSTEM.JMS.D.SUBSCRIBER.QUEUE) REPLACE + DESCR(Websphere MQ - JMS Classes - PS D shared queue) + * Persistent messages OK DEFPSIST(YES) + * Shareable SHARE DEFSOPT(SHARED) + * Maximum queue depth MAXDEPTH(100000) ********************************************************************/ * */ * JMS Publish/Subscribe Default Durable Shared Queue for */ * ConnectionConsumer functionality */ * */ * Create local queue used as the default shared queue by durable */ * connection consumers */ * */ ********************************************************************/ ** Create a local queue DEFINE QLOCAL(SYSTEM.JMS.D.CC.SUBSCRIBER.QUEUE) REPLACE + DESCR(Websphere MQ - JMS Classes - PS D CC shared q) + * Persistent messages OK DEFPSIST(YES) + * Shareable SHARE DEFSOPT(SHARED) + * Maximum queue depth MAXDEPTH(100000) ********************************************************************/ * */ * WAS Subscription Manager Publication Queue */ * */ ********************************************************************/ ** Create a local queue DEFINE QLOCAL(SYSTEM.BROKER.DEFAULT.STREAM) REPLACE + DESCR(Websphere MQ - Broker Deafult Stream) + * Persistent messages OK DEFPSIST(YES) + * Shareable SHARE DEFSOPT(SHARED) + * Maximum queue depth MAXDEPTH(100000)

   
   
9. In BI Message Broker Toolkit, create a message flow (MYPubSub.msgflow) to process publish messages. Then save the message flow into a file called a BAR (Broker Archive) file. The BAR file is used when the message flow is deployed.

   The simple message flow example here, once deployed, enables the broker to receive input publish messages and transmit them to subscribers who have registered an interest in a particular topic. The simple message flow example consists of an MQ input node SmPublication and a publication node SmPublishResults. The MQInputNode enables the broker to accept publish messages via the default broker queue SYSTEM.BROKER.DEFAULT.STREAM. The Publication Node enables the broker to transmit messages to subscribers that have an interest in this topic.

   
   Figure 15. Message Brokers Toolkit
   
   

   Once the message flow is created, ensure the queue manager and broker are started, then deploy the message flow into the broker to enable the broker to process the publish messages. The following BI Message Broker command deploys a message flow to the example broker MYBroker1:

   strmqm WAS_mytest1_MYServer mqsistart MYBroker1 mqsideploy -b MYBroker1 -e <execution_group_name> -bar <broker_archive_file_name>

   
   

   where:

   • <execution_group_name> is the name of the broker execution group to which to deploy
   • <broker_archive_file_name> is the name of the BAR file that is created in the create message flow step

   See the WebSphere Business Integration Message Broker documentation for details on deploying message flows.

10. Once you've completed these tasks, start WebSphere MQ, BI Message Broker and Application Server, then deploy and start the JMS J2EE application in the administration console to verify the application.

Back to top

Conclusion

This article described what you, as a JMS application developer or administrator, need to be aware of to enable your application to run on Application Server V5 using either the embedded JMS provider or the MQ JMS provider. It described how to install both JMS providers, as well as how to configure JMS resources and listener ports for JMS applications and verify the configuration set-up. It also provided the WebSphere MQ and BI Message Broker commands and set-up code you need to be able to use the MQ JMS provider.

Resources

• For more information about WebSphere Application Server V5, check out the WebSphere Application Server InfoCenter
  
  
• For more information about WebSphere MQ, see the MQ library
  
  
• For more information about WebSphere Event Broker, see the Event Broker MQ library
  
  
• For more information about WebSphere BI Message Broker, see the BI Message Broker library
  
  
• developerWorks Wireless with WebSphere zone. Access to Wireless with WebSphere how-to articles, downloads, tutorials, education, product information, and more.
  
  
• Browse for books on these and other technical topics.
  
  
• WebSphere forums. Product-specific forums where you can ask questions and share your opinions with other WebSphere users.
  
  
• developerWorks blogs. Ongoing, free-form columns by software experts, with space for you to add your comments. Check out Grady Booch's blog on Software architecture and engineering.
  
  

About the author

Andrew Capella is a software engineer in IBM Pervasive Computing. He has led product development teams in TCP/IP networking, WebSphere Application Server, and PerVasive Computing (PVC) Location-Based Services. He has participated in key open technology forums, including IETF, J2EE, WAP and OGC. He is currently working on PVC Intelligent Notification Services.

Rate this article

Comments

Back to top

Table of contents

• Overview
• Install the JMS providers
• Configure and start the JMS providers
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into WebSphere on developerWorks

Discover knowledge paths

Skill-building guides for WebSphere, Linux, open source, cloud, Java, business analytics, and more.

Special offers