Integrating WebSphere MQ with WebSphere Application Server Community Edition V2.0

Anish Pathadan (anishpathadan@in.ibm.com), Software Engineer, IBM Japan

Anish Pathadan is a Software Engineer in IBM India Software Labs. He holds a degree in Computer Science and Engineering from Calicut University. His areas of expertise include WebSphere Application Server Community Edition, ActiveMQ, Java EE, and messaging.

Summary: Learn how to use IBM® WebSphere® MQ as the JMS provider in IBM WebSphere Application Server Community Edition with the instructions, code examples, and sample application provided with this article.

Tag this!

Date: 09 Apr 2008
Level: Introductory
Activity: 1099 views

Introduction

A JMS provider acts as an intermediary between message producers and consumers. You need a JMS provider in IBM WebSphere Application Server Community Edition (hereafter called Community Edition) for message-driven beans (MDBs), and for sending and receiving messages to or from queues and topics. A JMS provider is configured in Community Edition as a resource adapter module. Any JMS provider can be integrated with Community Edition by deploying the corresponding resource adapter implementing J2EE™ Connector Architecture (JCA). Apache Active MQ is the default JMS provider for Community Edition. This brief article explains the steps you can take to configure WebSphere MQ to be the JMS provider in Community Edition.

Throughout this article, details are provided when necessary, but some working knowledge of WebSphere MQ and Community Edition is assumed.

Prepare WebSphere MQ

To begin this example, you need to prepare WebSphere MQ to be used with Community Edition, which involves these basic steps:

Create a queue manager; for this example, name the queue manager: WASCE_Q.
Create and start a listener that listens on port 1414, if you did not do so when creating the queue manager.
Create a queue called TestQueue (Figure 1).

Figure 1. Prepare WebSphere MQ

Install and configure a resource adapter in Community Edition

The resource adapter used here is shipped with the WebSphere MQ V6.0.2.1 fix pack. To install the resource adapter:

Locate the resource adapter.

Assuming you have installed WebSphere MQ V6.0.2.1 or later, you can find the resource adapter wmq.jmsra.rar in the directory listed below for your platform:

Platform	Directory
AIX®	/usr/mqm/java/lib/jca
HP-UX, Linux®, and Solaris™	/opt/mqm/java/lib/jca
i5/OS	/QIBM/ProdData/mqm/java/lib/jca
Windows®	install_dir\Java\lib\jca

The resource adapter also comes with a freely downloadable WebSphere MQ V6.0 client. If you need to, check the WebSphere MQ Information Center for current information on where to find the resource adapter file.

Install the dependent JAR files.
The WebSphere MQ extended transactional client lets you use XA distributed transactions with client mode connections to a WebSphere MQ queue manager. This step is applicable only if you are planning to use WebSphere MQ in XA transactions. The JAR file providing XA transaction support is com.ibm.mqetclient.jar and can be found in the MQ_xclient_install_dir/java/lib directory in Windows. (See the WebSphere MQ Information Center for the actual location of this JAR file for your platform. If you determine that you need the extended transaction client JAR file, you might need to acquire it from your IBM client representative.)

Install the com.ibm.mqetclient.jar file in Community Edition as a common library (you will have to give a dependency to this JAR file later from the resource adapter deployment plan) by selecting the Common Libs portlet in the administrative console and then selecting the JAR file. Provide appropriate values for Group, Artifact, Version, and Type, then click Install (Figure 2).

Figure 2. Install common library

This step installs the extended transactional client JAR file in the Community Edition repository. The values shown in Figure 2 are required when configuring a dependency on this JAR.

Create a resource adapter deployment plan.

You need to create a resource adapter deployment plan before you can deploy the resource adapter. The plan contains deployment specific information such as:

Connection to the WebSphere MQ broker
Queue manager name
Mapping of queues and topics managed by the queue manager and Community Edition
Connection pool size
XA transaction support
Logging details.

Listing 1. Sample resource adapter deployment plan

                        
<resourceadapter>

   <resourceadapter-instance>
      <resourceadapter-name>MQRA</resourceadapter-name>
      <!-- set to false if you donâ€™t need trace  -->
      <config-property-setting name="traceEnabled">true</config-property-setting>
      <!-- Trace level set to 1, this configuration will print only error 
         messages -->
      <config-property-setting name="traceLevel">1</config-property-setting>
      <config-property-setting name="traceDestination">
         System.out</config-property-setting>
      <workmanager>
         <gbean-link>DefaultWorkManager</gbean-link>
      </workmanager>
   </resourceadapter-instance>

   <outbound-resourceadapter>
      <connection-definition>
         <connectionfactory-interface>javax.jms.QueueConnectionFactory
            </connectionfactory-interface>
         <connectiondefinition-instance>
            <name>MyQueueConnectionFactory</name>
	
            <!-- Queue Manger name in Websphere MQ -->
            <config-property-setting name="queueManager">WASCE_Q
               </config-property-setting>
            <config-property-setting name="channel">SYSTEM.DEF.SVRCONN
               </config-property-setting>
			
            <!-- Trasport mode of CLIENT is used, specify BINDING if you want to use 
               binding connection mode -->
            <config-property-setting name="transportType">CLIENT
               </config-property-setting>

            <!-- name of the machine where WebSphere MQ is running -->
            <config-property-setting name="hostName">localhost
               </config-property-setting>
            <!-- TCP listener port configured in WebSphere MQ -->
            <config-property-setting name="port">1414</config-property-setting>
            <connectionmanager>
               <!-- Specify this if you want xa transaction support-->
               <xa-transaction/>
               <single-pool>
                  <max-size>50</max-size>
                  <min-size>20</min-size>
                  <blocking-timeout-milliseconds>5000</blocking-timeout-milliseconds>
                  <idle-timeout-minutes>2</idle-timeout-minutes>
                  <match-all />
              </single-pool>
            </connectionmanager>
         </connectiondefinition-instance>
      </connection-definition>
   </outbound-resourceadapter>

</resourceadapter>

<adminobject>
   <adminobject-interface>javax.jms.Queue</adminobject-interface>
   <adminobject-class>com.ibm.mq.connector.outbound.MQQueueProxy</adminobject-class>
   <adminobject-instance>
      <! - - logical name for the queue in Community Edition -->
      <message-destination-name>TestQueue</message-destination-name>
      <!-- Actual queue name in WebSphere MQ -->
      <config-property-setting name="baseQueueName">TestQueue
         </config-property-setting>
      <!-- name of the Queue Manager in which this queue is defined -->
      <config-property-setting name="baseQueueManagerName">WASCE_Q
         </config-property-setting>
   </adminobject-instance>
</adminobject>

For your reference, you can download a sample deployment plan (wasce_mq.xml) and a sample application that have been included with this article. You can edit the sample plan to suit your own WebSphere MQ configuration. For example, you can connect to other queue managers by adding more <connection-definition> instances, and you can add more queues or topics by adding new <adminobject> instances. The baseQueueName in <adminobject> specifies the queue name used in WebSphere MQ, and message-destination-name specifies the name in Community Edition. The traceEnabled property is set to true and traceLevel to 1 so that you get only error messages from the resource adapter.

Check the WebSphere MQ Information Center for detailed information of the properties supported in the resource adapter.

Deploy the resource adapter.
With the deployment plan created and the WebSphere MQ extended transaction client JAR file installed (if required), you can now deploy the resource adapter:
1. In the administrative console, select the Deploy New portlet.
2. For Archive, select the wmq.jmsra.rar RAR file, and for Plan, select wasce_mq.xml (Figure 3).
  
  Figure 3. Deploy New portlet
3. Select Start app after install.
4. Click Install to complete deployment.
5. Use the JMS Resources portlet to view the new JMS resource group that you just created (Figure 4).
  
  Figure 4. JMS Resources portlet

Configure inbound resource adapter.

An inbound resource adapter is not configured in wasce_mq.xml. Instead, it is configured in MDBs using the activation-spec properties of the openejb-jar.xml deployment plan. For an MDB to listen to TestQueue, you need to specify the queue manager name, host, port and channel in activation-spec properties. Refer to the openejb-jar.xml file in the sample application (MQMdb.jar) included with this article to see how an inbound resource adapter is configured for WebSphere MQ running on localhost.

Listing 2. Activation-spec properties

                        
<activation-config>
	
   <!--  WebSphere MQ queue to listen - ->

   <activation-config-property>
      <activation-config-property-name>destination</activation-config-property-name>
      <activation-config-property-value>TestQueue</activation-config-property-value>
   </activation-config-property>

   <activation-config-property>
      <activation-config-property-name>destinationType
         </activation-config-property-name>
      <activation-config-property-value>javax.jms.Queue
         </activation-config-property-value>
   </activation-config-property>

   <!-- Queue Manager name in WebSphere MQ - ->

   <activation-config-property>
      <activation-config-property-name>brokerQueueManager
         </activation-config-property-name>
      <activation-config-property-value>WASCE_Q</activation-config-property-value>
   </activation-config-property>

   <activation-config-property>
      <activation-config-property-name>hostName</activation-config-property-name>
      <activation-config-property-value>localhost</activation-config-property-value>
   </activation-config-property>

   <!â€”TCP Listener port configured in WebSphere MQ - ->

   <activation-config-property>
      <activation-config-property-name>port</activation-config-property-name>
      <activation-config-property-value>1414</activation-config-property-value>
   </activation-config-property>

   <!--<activation-config-property>
      <activation-config-property-name>channel</activation-config-property-name>
      <activation-config-property-value>SYSTEM.DEF.SVRCONN
         </activation-config-property-value>
   </activation-config-property>-->

</activation-config>

Test the resource adapter

A sample Web module (MQWebApp.war) and an EJB module (MQMdb.jar) are provided in the included download file to demonstrate the inbound and outbound communication between Community Edition and WebSphere MQ.

Test outbound communication.
Outbound communication refers to sending messages from Community Edition to WebSphere MQ. MQWebApp is a simple Web application that sends messages to TestQueue. It provides a Web page into which you can type a message to demonstrate outbound messaging. Deploy the application using the Deploy New portlet on the admin console, then use a browser to access the application at http://localhost:8080/MQWebApp (Figure 5).

Figure 5. WebApp_home outbound test application

Enter a message in the text field and click Send Message. The message will be sent to the TestQueue configured in WebSphere MQ. If the message is sent successfully, the message shown in Figure 6 will display.

Figure 6. WebApp_MessageSend_success
Test inbound communication.
Inbound communication refers to Community Edition receiving messages from WebSphere MQ. MQMdb is a sample application that listens to TestQueue in WebSphere MQ, demonstrating inbound communication. The MDB will process any messages send to TestQueue.

Deploy MQMdb.jar using the Deploy New portlet on the admin console. The MDB will print the message it receives to the console (Figure 7).

Figure 7. MQMdb_console

Conclusion

You can now configure WebSphere MQ to be the JMS provider in WebSphere Application Server Community Edition, using the information in this article and the sample applications, which were deployed to verify inbound and outbound communication between both products.

Download

Description	Name	Size	Download method
Sample application	mqwace_samples.zip	9 KB	HTTP

Information about download methods

Resources

Learn

Get products and technologies

Discuss

WebSphere forums

About the author

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=WebSphere

ArticleID=300377

ArticleTitle=Integrating WebSphere MQ with WebSphere Application Server Community Edition V2.0

publish-date=04092008

author1-email=anishpathadan@in.ibm.com

author1-email-cc=