Using WebSphere MQ with WebSphere Application Server Community Edition

Krishnakumar Balachandar (krishnakumarb@in.ibm.com), Software Engineer, WebSphere Application Server Community Edition Support Team, IBM

Krishnakumar Balachandar is a Software Engineer on the Geronimo and WebSphere Application Server Community Edition Support Team with IBM India. His expertise includes business integration and J2EE technologies. You can contact Krishnakumar at krishnakumarb@in.ibm.com.

Summary: WebSphere Application Server Community Edition is an open-source J2EE application server based on Apache Geronimo. This article will explain how to use it with WebSphere MQ V6.

Tag this!

Date: 18 Jan 2006
Level: Intermediate
Activity: 787 views

Introduction

IBM® WebSphere® Application Server Community Edition (hereafter called Community Edition) provides messaging support using ActiveMQ, an open-source messaging provider. A J2EE application deployed on Community Edition can use queues and topics created in ActiveMQ, and a message-driven bean (MDB) can act as an endpoint to extract messages from a queue or topic. This article will show you how to use WebSphere MQ as a messaging provider for Community Edition. We will use JMS support provided by WebSphere MQ by means of a J2EE Connector Architecture (JCA) resource adapter. The resource adapter provides outbound communication to queues and topics, and inbound communication as the resource adapter picks a message from a queue and sends it to a message bean.

The following diagram shows the components of Community Edition and WebSphere MQ that are used for integration:

Queues/topics in WebSphere MQ
WebSphere MQ resource adapter
JNDI file bindings for WebSphere MQ
Message-driven bean for inbound communication
Servlet for outbound communication

WebSphere MQ resource adapter properties

Resource adapter properties are listed in the deployment descriptor (ra.xml). The following section shows outbound, inbound, and administered object configuration properties that are needed for the adapter to connect to WebSphere MQ.

Outbound

Outbound resource adapter configuration properties:

url: JNDI provider URL, for example: ldap://test/o=test,c=com,file:/C:/JNDI-Directory
icf: Initial Context Factory, for example: com.sun.jndi.fscontext.RefFSContextFactory
name: Factory Name, for example: wasceQCF

Listing 1. Outbound configuration in ra.xml

<outbound-resourceadapter>
    <config-property>
        <description>JNDI provider url</description>
        <config-property-name>url</config-property-name>
	    <config-property-type>java.lang.String</config-property-type>
	</config-property>
	<config-property>
		<description>Initial Context Factory</description>
		<config-property-name>icf</config-property-name>
		<config-property-type>java.lang.String</config-property-type>
	</config-property>
	<config-property>
		<description>Factory Name</description>
		<config-property-name>name</config-property-name>
		<config-property-type>java.lang.String</config-property-type>
	</config-property>
</outbound-resourceadapter>

Inbound

Inbound resource adapter configuration properties:

url: JNDI provider URL
icf: Initial Context Factory
name: Factory Name
destination: Destination to pick messages form, for example, Queue Name

Listing 2. Inbound configuration in ra.xml

<inbound-resourceadapter>
   <activationspec>
             <required-config-property>
           		<config-property-name>url</config-property-name>
             </required-config-property>
             <required-config-property>
				<config-property-name>icf</config-property-name>
             </required-config-property>
             <required-config-property>
				<config-property-name>name</config-property-name>
            </required-config-property>
            <required-config-property>
                <config-property-name>destination</config-property-name>
            </required-config-property>
   </activationspec>
</inbound-resourceadapter>

Administered objects

physical name: Name of queue or topic created in JNDI of Geronimo

Listing 3. Administered objects from ra.xml

<adminobject>
<adminobject-interface>javax.jms.Queue</adminobject-interface>
  <config-property>
            <config-property-name>PhysicalName</config-property-name>
            <config-property-type>java.lang.String</config-property-type>
  </config-property>
</adminobject>
<adminobject>
<adminobject-interface>javax.jms.Topic</adminobject-interface>
   <config-property>
 		<config-property-name>PhysicalName</config-property-name>
 		<config-property-type>java.lang.String</config-property-type>
  </config-property>

The properties of RA are mapped to a Community Edition-specific RA plan (wasce-mq.xml), which contains instance-specific properties for outbound connections and administered objects. In this file we can provide values for outbound RA config properties and admin objects. For example:

url: ldap://test/o=test,c=com OR file:/C:/JNDI-Directory
icf: com.sun.jndi.fscontext.RefFSContextFactory
name: wasceQCF
physical name for queue: SYSTEM.DEFAULT.LOCAL.QUEUE
physical name for topic: SampleTopic

Listing 4. Geronimo-specific plan

<outbound-resourceadapter>
 <connection-definition>
   <connectiondefinition-instance>
     <name>MQQueueFactory</name>
		<config-property-setting name="url"></config-property-setting>
		<config-property-setting name="icf"></config-property-setting>
		<config-property-setting name="name"></config-property-setting>
		<connectionmanager>
  </connection-definition>
  <adminobject>
	<adminobject-instance>
            <message-destination-name>ivtQ</message-destination-name>
            <config-property-setting name="PhysicalName">
                SYSTEM.DEFAULT.LOCAL.QUEUE
            </config-property-setting>
	</adminobject-instance>
  </adminobject>
  <adminobject>
    <adminobject-instance>
            <message-destination-name>ivtT</message-destination-name>
            <config-property-setting name="PhysicalName">
                SampleTopic
            </config-property-setting>
	</adminobject-instance>
  </adminobject>

Creating the enterprise application plan

To communicate with WebSphere MQ, you can use J2EE artifacts such as servlets or session beans. Listing 5 below shows an enterprise application plan consisting of a Web module and bean module for outbound and inbound communication with WebSphere MQ. Community Edition specific configuration is added to geronimo-application.xml. The Web module contains a reference to ra/MQQueueFactory and ra/MQTopicFactory, and the Bean module contains a reference to the RA instance MQRA_1. The Activation Spec properties required for inbound communication from RA are specified in the message bean Activation config.

Listing 5. Geronimo application plan

<application xmlns="http://geronimo.apache.org/xml/ns/j2ee/application" 
configId="wasce/mq.ear"  parented=”wasce/mq.rar”>

<module>
	<web>WASCEMQWAR.war</web>
	<web-app xmlns="http://geronimo.apache.org/xml/ns/web" 
	xmlns:naming="http://geronimo.apache.org/xml/ns/naming" configId="wasce/mq.war" 
	parentId="wasce/mq.ear">
	<context-priority-classloader>false</context-priority-classloader>
	<naming:resource-ref xmlns="http://geronimo.apache.org/xml/ns/naming">
		<naming:ref-name>ra/MQQueueFactory</naming:ref-name>
		<naming:resource-link>MQQueueFactory</naming:resource-link>
	</naming:resource-ref>
	<naming:resource-ref xmlns="http://geronimo.apache.org/xml/ns/naming">
		<naming:ref-name>ra/MQTopicFactory</naming:ref-name>
		<naming:resource-link>MQTopicFactory</naming:resource-link>
	</naming:resource-ref>
</web-app>
</module>
<module>
	<ejb>WASCEMQEJB.jar</ejb>
	<openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar" 
	xmlns:naming="http://geronimo.apache.org/xml/ns/naming" configId="wasce/mq.ejb"
	parentId="wasce/mq.ear">
      <enterprise-beans>
      <message-driven>
      <ejb-name>MQMDB</ejb-name>
      <resource-adapter>
      
    	<resource-link>MQRA_1</resource-link>
      </resource-adapter>
     <activation-config>
	<activation-config-property>
	<activation-config-property-name>url</activation-config-property-name>
		<activation-config-property-value>
		  file://C:/JNDI-Directory
		</activation-config-property-value>
	</activation-config-property>
	<activation-config-property>
	<activation-config-property-name>icf</activation-config-property-name>
		<activation-config-property-value>
		  com.sun.jndi.fscontext.RefFSContextFactory
		</activation-config-property-value>
	</activation-config-property>
	<activation-config-property>
	<activation-config-property-name>name</activation-config-property-name>
		<activation-config-property-value>
		  wasceQCF
		</activation-config-property-value>
	</activation-config-property>
	<activation-config-property>
	<activation-config-property-name>destination</activation-config-property-name>
		<activation-config-property-value>
		  SYSTEM.DEFAULT.LOCAL.QUEUE
		</activation-config-property-value>
	</activation-config-property>
    </activation-config>
    </message-driven>
    </enterprise-beans>
</openejb-jar>
</module>
<ext-module>
<connector>MQRA_1</connector>
	<external-path>mq/rars/wascemq.rar</external-path>
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector" configId="wasce/mq.rar.1" 
parentId="wasce/mq.ear">

<resourceadapter>
	<resourceadapter-instance>
		<resourceadapter-name>MQRA_1</resourceadapter-name>
	<workmanager>
		<gbean-link>DefaultWorkManager</gbean-link>
	</workmanager>
	</resourceadapter-instance>
		<outbound-resourceadapter>
...( Same as Listing 4 )
</connector>
<ext-module>
</application>

Configuring Websphere MQ for Community Edition

The previous sections described resource adapter and application plans for resource adapter and J2EE applications. The next section explains how to configure WebSphere MQ and Community Edition and run the sample.

Prerequisites

WebSphere MQ V6.0
WebSphere Application Server Community Edition V1.0

Configuring WebSphere MQ

To configure WebSphere MQ:

Create a Queue Manager (WASCE_Q) for Queues. A default local Queue is created called SYSTEM.DEFAULT.LOCAL.QUEUE.
If you did not create and start a Listener than listens on Port 1414 while creating the Queue Manager, then do so now.
Create and start a Server Connection Channel CHANNEL1.
Create a Queue Manager (WASCE_T) for Topics and start it as broker from Services.
Create and start a Listener on Port 1434 for this QueueManager.
Create and start a Server Connection Channel CHANNEL1.
Run the MQSC command using the file MQJMS_PSQ.mqsc, containing the line: runmqsc WASCE_T < MQJMS_PSQ.mqsc.

Create JNDI bindings for QueueConnectionFactory and TopicConnectionFactory using the JMSAdmin tool. Set JMSAdmin.config to use File Context JNDI and point to C:/JNDI-Directory. Run the JMSAdmin tool and create the bindings:

QueueConnectionfactory
DEFINE QCF(wasceQCF) HOST(localhost) PORT(1414) CHANNEL(CHANNEL1) QMGR(WASCE_Q) TRAN(client)
TopicConnectionFactory
DEFINE TCF(wasceTCF) HOST(localhost) PORT(1434) CHANNEL(CHANNEL1)qmgr(WASCE_T) TRAN(client)
Subscriber
DEFINE T(wasceTopic) TOPIC(SampleTopic)

Configuring Community Edition

To configure Community Edition:

Create the following folder structure under Community Edition and copy the following WebSphere MQ JAR and RAR files. MQ JAR files are in the WebSphere MQ home/java/lib directory:
Start the server using Java: <community edition home>/bin/java -jar server.jar. Do not use the Windows shortcut.
Deploy the Resource Adapter with server scope to the server using the command line or console. Applications can now create instances of this RA and use it within the scope of the application: <CE HOME>/bin/deploy deploy wasce-mq.xml<path>/wascemq.rar
Deploy the EAR that contains MDB for inbound communication from WebSphere MQ, the WAR for outbound communication to Queue/Topic, and an instance of RA deployed in Step 2:

Running the sample

To run the sample and check outbound and inbound communication to WebSphere MQ:

Outbound communication

Use the deployed WAR to check outbound communication to a Queue or Topic:
Go to http://localhost:8080/mq:
Enter details and click Queue or Topic
This message is sent to Queue: SYSTEM.DEFAULT.LOCAL.QUEUE in WASCE_Q.
For Topic the message is sent to SampleTopic:
Start a sample subscriber to check if the message is received. WebSphere MQ has a sample program called JMSPubSub.java, which you can use to run a subscriber to SampleTopic. It resides in <MQ-DIR>/Tools/Java/jms/PubSub.java. After running the subscriber, you can see the message posted to the Topic:

Inbound communication

Post a test message in the Queue in WebSphere MQ (SYSTEM.DEFAULT.LOCAL.QUEUE).
The onMessage of the MDB should be invoked and you should see the message below in the Community Edition console. It can be extended to Topic by adding another ActivationSpec for Topics.

Conclusion

This article showed how to configure WebSphere MQ with WebSphere Application Server Community Edition. We can add XA transactions to Resource Adapter to support distributed transactions in Community Edition with WebSphere MQ.

Download

Description	Name	Size	Download method
Code samples in zip format	wasce_mq.zip	56 KB	FTP\|HTTP

Information about download methods

Resources

developerWorks WebSphere Application Server Community Edition zone
For developers, access to how-to articles, downloads, tutorials, education, product information, support information, and more.
Getting started with WebSphere Application Server Community Edition
Community Edition is an open-source Java application server based on Apache Geronimo. This article describes the product and will help you get up and running quickly with instructions for choosing the right download package, setting up your environment, and deploying applications.
Apache Geronimo project
Project site for the open-source J2EE application server from the Apache Software Foundation.
WebSphere MQ product page
Product descriptions, product news, training information, support information, and more.
WebSphere MQ documentation library
WebSphere MQ manuals in PDF format.
WebSphere MQ V6 Information Center
A single Eclipse-based Web interface for all WebSphere MQ V6 documentation.
Introduction to J2EE Connector Architecture
A detailed overview of JCA, including the base elements of the architecture, followed by descriptions, examples, and a sample application that shows how the parts of a JCA-compliant and enabled system work together.
Developing a standalone Java application for WebSphere MQ
Shows you how to develop a Java application that sends and receives messages using WebSphere MQ, using standard JMS and JNDI APIs.
developerWorks WebSphere Business Integration zone
For developers, access to how-to articles, downloads, tutorials, education, product information, support information, and more.
WebSphere Business Integration products page
For both business and technical users, a handy overview of all WebSphere Business Integration products
Trial downloads for IBM software products
No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products.
Safari Bookshelf: e-library designed for developers
Complete search and download access to thousands of technical books for a one-time subscription fee. Free trial for new subscribers.
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, to which you can add your comments. Check out Grady Booch's blog on software architecture.

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=101971

ArticleTitle=Using WebSphere MQ with WebSphere Application Server Community Edition

publish-date=01182006

author1-email=krishnakumarb@in.ibm.com

author1-email-cc=