IBM WebSphere Developer Technical Journal: Building an Enterprise Service Bus using WebSphere ESB, Part 4

Connecting WebSphere ESB and WebSphere MQ

In the previous two articles in this series, we discussed how to leverage the JMS and Web services support in IBM® WebSphere® Enterprise Service Bus (ESB). In this installment, we will describe how to connect WebSphere ESB mediation modules with an existing WebSphere MQ environment, leveraging a new binding type for direct MQ connectivity that was introduced with WebSphere ESB Version 6.0.2.


Rachel Reinitz (, Senior Consulting IT Specialist, IBM

Rachel ReinitzRachel Reinitz is an IBM Distinguished Engineer with IBM Software Services for WebSphere and a member of the IBM Academy of Technology. She has built much of IBM’s internal and external intellectual capital and education on SOA, Enterprise Service Bus, and Web services. Rachel focuses on how to get started with SOA and ESB best practices. She consults with clients and ISVs on how SOA and ESB can be used to achieve their business and technical objectives. She is a frequent conference presenter and written many developerWorks articles on ESB and Web services. Rachel lives in the Bay Area in California, and enjoys hiking, socializing, and international travel.

Andre Tost, Senior Technical Staff Member, IBM

Andre TostAndre Tost works as a Senior Technical Staff Member in the Software Group's Enterprise Integration Solutions organization, where he helps IBM's customers establishing Service-Oriented Architectures. His special focus is on Web services technology. Before his current assignment, he spent ten years in various partner enablement, development and architecture roles in IBM software development, most recently for the WebSphere Business Development group. Originally from Germany, he now lives and works in Rochester, Minnesota. In his spare time, he likes to spend time with his family and play and watch soccer whenever possible.

28 February 2006

Also available in Chinese

From the IBM WebSphere Developer Technical Journal.


After having covered two of the most used protocols that WebSphere Enterprise Service Bus (ESB) supports for connectivity -- namely JMS and Web services (SOAP/HTTP) -- we will now move on and add one more protocol to the mix that is commonly required in real life enterprise environments: WebSphere MQ.

Many applications already exist that support message exchange across WebSphere MQ to communicate with external applications, and an ESB is often used to transform into and expose application functions over MQ as services. Hence, we will show here how existing applications supporting MQ communication can be tied into a service-oriented environment by utilizing the WebSphere MQ support in WebSphere ESB.

The updated scenario

In Part 2, we described how each delivery of a package by Posts-R-Us results in a message being sent to the ESB, from where it is forwarded to a Java™ EE application using a message-driven bean (MDB). This level of indirection established a decoupling between the systems generating the event (that is, the event that a package had been delivered) and the one consuming it (the MDB that received the message). Putting this in an SOA context, it means that the ESB offers a virtual service interface to the client that hides the real location and interface of the service provider.

At Posts-R-Us, an existing mainframe-based application exists that also needs to receive notification messages about delivered packages. It receives those messages, formatted in XML, over a WebSphere MQ queue. The design team decides to change the ESB mediation, adding a connection to forward the incoming notification messages to the appropriate MQ queue, while continuing to send it to the original Java EE (formerly J2EE) application. Figure 1 shows the updated architecture.

Figure 1. Updated architecture for package delivery notification
Figure 1. Updated architecture for package delivery notification

As the figure shows, the message is forwarded to a queue that is managed by a remote WebSphere MQ queue manager, in a separate process, whereas the original queue is managed within WebSphere ESB, in the same process, from where it is handed to the message-driven bean.

A couple of aspects are important to note here, all showing the value the ESB brings to the architecture of the system:

  • The client application is not affected at all by this change. It continues to send the JMS message to the destination in the ESB.
  • The existing MDB application is not affected by this change either.
  • The existing mainframe application continues to receive messages from the associated WebSphere MQ queue.

Setting up WebSphere MQ

To run an example that reflects the architecture described above, you need to create a queue that will receive messages from WebSphere ESB. (In a real enterprise, the queue that the mainframe application listens on would probably already exist.) The easiest way to do so is through the WebSphere MQ Explorer. Once you start it, the main window will look like Figure 2.

Figure 2. WebSphere MQ Explorer main window
Figure 2. WebSphere MQ Explorer main window

Keep in mind that you usually have one or more WebSphere MQ queue managers. In the figure above, the queue manager we will use is called QM_atost. To create a queue under this queue manager, right click on the Queues node in the WebSphere MQ Explorer Navigator, then select the New => Local Queue... (Figure 3).

Figure 3. Creating a new Local Queue
Figure 3. Creating a new Local Queue

In the resulting dialog, name the new queue PackageReceivedQueue, leave all other default values, then click Finish.

And that's all you need to do in WebSphere MQ. There is no need to create any specific connection configuration to communicate with WebSphere ESB.

The mediation module

This article assumes that you have completed the steps described in Part 2 and already have the associated artifacts loaded in WebSphere Integration Developer, and continues through the steps necessary to update this code so that you can run the extended scenario. However, if you would prefer to import the final solution rather than go through all the steps, you will find two EAR files and one Project Interchange file in the download file included with this article.

Next, you need to update the mediation that we already used in Part 2.

  1. Open the PackageReceivedModule module in the assembly tool in WebSphere Integration Developer. This module consists of the mediation flow component, the JMSClientExport export, and the MDBImport import.

  2. Add another import by dragging it from the palette into the assembly. Name the new import MQImport and connect it to the mediation flow component, as shown in Figure 4.

    Figure 4. Add another import to the mediation module assembly
    Figure 4. Add another import to the mediation module assembly
  3. Now you will generate the bindings that connect this import with the WebSphere MQ queue created earlier. Right-click on the MQImport and select Generate Binding..=>Messaging Binding..=> MQ Binding.

    Figure 5. Create an MQ binding
    Figure 5. Create an MQ binding
  4. In the resulting dialog, enter or select the following values (Figure 6):

    • Queue manager name: enter the name of your queue manager; in this example, we use QM_atost
    • Send Destination Queue: PackageReceivedQueue
    • Host Name: localhost
    • Request Serialization type: Serialized as XML

    Leave default values for all remaining fields.

    Figure 6. MQ binding definition
    Figure 6. MQ binding definition

    This will connect the import in the mediation module to the WebSphere MQ queue you created earlier. Moreover, it specifies that the payload of the message should be sent to the queue as a serialized XML message. You will see what this looks like later when you run the final test. If you need to, you can make further changes after you have created the binding simply by opening the Properties view for the import.

    Figure 7. MQ bindings properties view
    Figure 7. MQ bindings properties view
  5. Next, you will create the mediation flow component implementation. Instead of updating the existing implementation, you will simply generate a new one, since the flow we will use is a very simple one. To do so, right-click on the mediation flow component, PackageReceivedMediation, in the assembly, and select the Regenerate Implementation menu option. The Mediation Flow Editor will open.

  6. Connect the interface node on the left to both reference nodes on the right, as shown in Figure 8. Make sure that you wire it to the PackageReceivedIFPartner1 reference first.

  7. Insert a Message Logger mediation primitive into the flow and connect it to the Input node. Connect the output terminal of the logger primitive to both Callout nodes. This will lead to the message being logged, and then forwarded to both imports, namely the JMS queue that the MDB listens to, and the MQ queue you defined earlier.

    Figure 8. Updated mediation flow
    Figure 8. Updated mediation flow
  8. Save all of your changes. Also, run the Project => Clean... menu option from the main tool menu. This will make sure that all required artifacts for the mediation module are built and updated according to the changes you just made.

Running the updated scenario

You are now ready to run a test to show the effect of the changes you made:

Making repeated changes and updates to modules and deploying them to the server can sometimes lead to problems related to resources that are not properly cleaned up or regenerated. In such a case, restart the test server frequently and run the Project => Clean... menu option to make sure that required resources are rebuilt when needed.

  1. Start the server, if it is not already started. For this test, we will assume that no enterprise applications have been deployed on the server. If you have any existing EAR files deployed, you should remove them and then restart the server.

  2. Right-click on the WebSphere ESB server in the server perspective and select Add and remove projects... Add the PackageReceivedModuleApp project first, then the PackageReceivedEAR project, then click Finish.

  3. Restart the server.

  4. Run the test client in the PackageReceivedClientEAR project. (This is exactly the same as described in Part 2.) As a result, you can see in the console how the message-driven bean receives the message (Figure 9).

    Figure 9. The server console
    Figure 9. The server console
  5. Remember that the message is also forwarded to the WebSphere MQ queue. To ensure that the message was sent successfully, open the WebSphere MQ Explorer, navigate to the PackageReceivedQueue queue, and browse the messages that are on it (Figure 10).

    Figure 10. Browsing the WebSphere MQ queue messages
    Figure 10. Browsing the WebSphere MQ queue messages
  6. Right-click on the message in the queue and select the Data tab (Figure 11). This will show you the content of the actual message which, you will notice, consists of a header portion as well as the payload as an XML string (and remember, we asked for the message to be sent in serialized XML format).

    Figure 11. The XML message
    Figure 11. The XML message

If you want to experiment with this example a bit more, you can add an XSL Transformation mediation primitive before the callout node for the MQ import. This would enable you to transform the incoming message into a format that is appropriate for the backend application.


With these instructions, you saw how to extend the scenario developed in Part 2 to include a connection to an existing WebSphere MQ system. We added an import to the mediation flow and generated MQ bindings on it that connected the import to an existing WebSphere MQ queue under the control of a remote queue manager. The configuration required to do so is minimal and the change does not affect any of the previously existing pieces of the scenario.

As a result, you have now seen how to use three protocols when communicating with WebSphere ESB: JMS, SOAP/HTTP, and WebSphere MQ. In the next part of this series, you will see how to switch from one protocol to another, including a change from an asynchronous invocation to a synchronous one, and vice versa. Stay tuned!

More in this series


Code samplepart4-downloads.zip25 KB



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Business process management on developerWorks

Zone=Business process management, WebSphere, Architecture
ArticleTitle=IBM WebSphere Developer Technical Journal: Building an Enterprise Service Bus using WebSphere ESB, Part 4