IBM WebSphere Developer Technical Journal: Building an Enterprise Service Bus with WebSphere Application Server V6 -- Part 6

A simple message exchange between SIBus and WebSphere MQ

Part 6 of this series on using the new messaging engine in IBM® WebSphere® Application Server V6 to build an Enterprise Service Bus demonstrates how IBM WebSphere V6 Messaging Resources supports message exchange with IBM WebSphere MQ.

Rachel Reinitz (rreinitz@us.ibm.com), 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.



17 August 2005

Also available in Chinese Russian

Introduction

So far in this series of articles, we explored the basics of WebSphere V6 Messaging Resources, how to set up an Enterprise Service Bus (ESB), how to use JMS as a message protocol going across the bus, how to develop and install a simple mediation, and how to route SOAP requests from a client to a SOAP provider through the bus. Our overall solution has evolved from these previous articles:

Here, in Part 6, we will configure and test sending messages between IBM WebSphere MQ and WebSphere V6 Message Resources.


Concepts of connecting the SIBus to MQ

Whether an IBM WebSphere MQ queue manager is remote or coexists on the same machine as IBM WebSphere Application Server V6, it can be configured to exchange messages using WebSphere V6 Message Resources, also called the Systems Integration Bus, or SIBus. Since WebSphere MQ and the WebSphere SIBus do not share any modules or configuration data, they must each be configured with information about the other.

A core component of a SIBus is a messaging engine (ME), which is the SIBus component that applications talk to. At least one ME must be defined for each bus. The ME is associated with a specific server or server cluster that has been added to the bus as a bus member. A bus may be configured in a variety of ways to span multiple servers (that is, it can have multiple bus members), but there is always at least one messaging engine for each server in a specific bus. In our simple setup, we have one bus with one bus member with one messaging engine. The reason this is important is that when we connect MQ to the bus it is done through the messaging engine component.

Figure 1. Messaging engines
Figure 1. Messaging engines

Other SIBus components that we will use are:

  • A foreign bus is one that is external to the current SIBus; it can be another SIBus or an MQ Queue Manager.
  • A foreign destination is a type of destination that is designed to send messages to the foreign bus.

A regular queue destination can be configured to receive messages from a foreign bus.

The MQ queue manager appears to the SIBus as a foreign bus. The messaging engine will appear as another queue manager to WebSphere MQ. Connectivity on the SIBus side between the ME and queue manager is established by the MQLink component of SIBus. The MQLink converts between the formats and protocols used by MQ and SIBus. There is only one SIBus MQLink for a specific MQ Queue Manager. On the MQ side, MQ channels are defined to communicate with the specific SIBus messaging engine.

Detailed information about these bus components is available in the WebSphere Application Server V6 Information Center.

Figure 2. SIBus components
Figure 2. SIBus components

Sending messages between SIBus and WebSphere MQ

To give you an overview of what is involved, here are summaries of the major tasks that will enable messages to pass between the SIBus (TheBus) and WebSphere MQ. Each group of tasks will be expanded and described in the sections that follow.

To connect the SIBus and an MQ queue manager

  1. In WebSphere Application Server, create a foreign bus that points to an MQ queue manager.

  2. Create an MQ link in WebSphere Application Server from TheBus to the MQ queue manager.

  3. In WebSphere MQ, create a transmission queue that links to TheBus as if it were another MQ queue manager.

  4. In WebSphere MQ, define sender and receiver channels.

These definitions in both WebSphere Application Server and WebSphere MQ use common TCP/IP hostnames and ports to establish communication.

To send a message from the SIBus to WebSphere MQ

  1. In WebSphere Application Server, create a foreign destination that points to an MQ queue.

  2. Send a message to the foreign destination. For our testing, we will use the JMS client from Part 3 to send the message to a destination, which then forwards to the foreign destination.

  3. The message is sent by the bus to the MQ queue. We will use the rfhutil utility to view the messages on the MQ queue.

To send a message from WebSphere MQ to the SIBus

  1. In WebSphere Application Server, create a queue destination.

  2. In WebSphere MQ, create a remote queue that refers to the destination on TheBus.

  3. Use rfhutil or another program to place a message onto the MQ remote queue.

  4. The message is sent by WebSphere MQ to the destination on the bus. For our testing, we will use a logging mediation to see that the message gets delivered to the destination.


Configure the SIBus to communicate with WebSphere MQ

In the SIBus, we will create a foreign bus and an MQ link to communicate with WebSphere MQ.

Create a foreign bus

  1. Open the WebSphere Application Server administrative console (the server must be running).

  2. In the left navigation pane, select Service Integration => Buses.

  3. Select TheBus.

  4. In the next window, select Foreign Buses (Figure 3).

    Figure 3. Bus properties
    Figure 3. Bus properties
  5. Select New.

  6. Step1: Foreign bus properties. Provide a name that is an identifier for the foreign bus in SIBus: TheForeignBus (Figure 4).

    Figure 4. Step 1: Foreign bus properties
    Figure 4. Step 1: Foreign bus properties
  7. Step2: Routing definition type. For the Routing definition type choose Direct, WebSphere MQ link (Figure 5).

    Figure 5. Step 2: Routing definition type
    Figure 5. Step 2: Routing definition type
  8. For Step 3, no user IDs are required, so select Next.

  9. Click Finish and Save.

  10. You will now see TheForeignBus in the foreign bus list for TheBus (Figure 6).

    Figure 6. Foreign bus list
    Figure 6. Foreign bus list

Create a WebSphere MQ link

Next, we need to setup the link from the SIBus to WebSphere MQ, which includes identifying the SIBus as a queue manager to WebSphere MQ. We then need to configure send and receive channels which will match up with channels in the queue manager.

  1. In the left navigation pane of the admin console, select Service Integration => Buses => TheBus.

  2. In the next panel, select Messaging engines (Figure 7).

    Figure 7. Bus properties
    Figure 7. Bus properties
  3. Select Node1.server1-TheBus.

  4. On right of the next panel, select WebSphere MQ links (Figure 8).

    Figure 8. Messaging engine configuration
    Figure 8. Messaging engine configuration
  5. Select New.

  6. Step 1: General WebSphere MQ link properties. Enter or select the following values (Figure 9):

    • Name (just for the SIBus): LocalMQLink
    • Foreign bus name: TheForeignBus (which we created in the last step, and will probably be the only one)
    • Queue manager name: QM_TheBus (the name by which you want the messaging engine to be known by the MQ queue manager -- not the name of the MQ queue manager)

    Select Next.

    Figure 9. General WebSphere MQ link properties
    Figure 9. General WebSphere MQ link properties
  7. Step2: Sender channel WebSphere MQ link properties. The sender and receiver channels act in pairs. This channel will be the connection that is used to send messages from the bus to WebSphere MQ. It will need to match the name, hostname, and port used by the queue manager to receive messages from the bus. The queue manager, by default, uses port 1414 to receive incoming messages. Enter or select the following values (Figure 10):

    • Sender MQ channel name: busToMQ (This can be any name of your choosing, but it must match the receiver channel name in the MQ queue manager. )
    • Host name (of the queue manager): localhost
    • Port (shows default of queue manager): 1414
    • Transport chain: OutboundBasicMQLink

    Select Next.

    Figure 10. Step 2: Sender channel WebSphere MQ link properties
    Figure 10. Step 2: Sender channel WebSphere MQ link properties
  8. Step3: Receiver channel WebSphere MQ link properties. This channel will be the connection used to receive messages into the bus from WebSphere MQ. It must match the name, hostname, and port used by the MQ queue manager to send messages to the bus. The SIBus, by default, uses port 5558 for embedded messaging (part of your general WebSphere setup) to receive incoming messages. Enter or select the following values (Figure 11):

    • Receiver MQ channel name: MQToBus (This is a name of your choosing, but it must match the sender channel name in the queue manager.)
    • You do not have to define a hostname and a port because the WebSphere embedded messaging configuration is used for receiving messages; that is, it uses the hostname of the application server and port 5558 by default.
    • Select Next.
    Figure 11. Step 3: Receiver channel WebSphere MQ link properties
    Figure 11. Step 3: Receiver channel WebSphere MQ link properties
  9. Step 4: Summary of WebSphere MQ link properties. Finish and Save your changes

  10. Restart the server to make the new link available externally.


Configure the queue manager to communicate with SIBus

The sample screen shots for WebSphere MQ are from the Windows® platform. Although the appearance of the panels will vary somewhat by platform, the information entered will be the same.

Basically, configuring the MQ queue manager to communicate with the SIBus is the same procedure used to configure two MQ queue managers to communicate with each other. If you performed a default installation of WebSphere MQ, you have a queue manager with the name QM_machine; this is the queue manager we we will use. For our example, we will use the queue manager named QM_reinitz.

  1. Open the WebSphere MQ Explorer. Navigate to Start menu => Programs => IBM WebSphere MQ => WebSphere MQ Explorer.

Create a transmission queue

Create a transmission queue that provides the QM_reinitz queue manager with a link to the SIBus as a queue manager.

  1. Expand WebSphere MQ => QM_reinitz.

    Figure 12. Create a new queue
    Figure 12. Create a new queue
  2. Right-click on Queues then select New => Local Queue.

  3. On the Create Local Queue dialog (Figure 13), select the General tab.

  4. Enter or select the following values:

    • Queue Name: QM_TheBus (must be the queue manager name that you used in the MQ link definition)
    • Usage: Transmission

    Select OK.

    Figure 13. Create Local Queue dialog
    Figure 13. Create Local Queue dialog

    Under the list of queues you now see QM_TheBus (Figure 14).

    Figure 14. Queue list
    Figure 14. Queue list

Define sender channel

  1. Expand QM_reinitz => Advanced.

  2. Right-click on Channels, then select New => Sender channel.

  3. On the Create Sender Channel dialog, select the General tab (Figure 15)

  4. Enter or select the following values:

    • Channel Name: MQToBus (must be the exact name used when you defined the Receiver queue on the MQ link)
    • Transmission Protocol: TCP/IP
    • Connection Name: The hostname of machine running the SIBus(port). For the default standalone WebSphere Application Server installation, the value is localhost(5558).
    • Transmission Queue: QM_TheBus.

    Select OK.

    Figure 15. Create Sender Channel dialog
    Figure 15. Create Sender Channel dialog
  5. Expand the Explorer channel window to show the status of the MQToBus channel; it will most likely be inactive. Select the newly created MQToBus channel, right- click, then select Start.

  6. After a minute or so, select Refresh from the context menu. You should see the status change to Running (Figure 16).

    Figure 16. Check channel status
    Figure 16. Check channel status

Define receiver channel

  1. Right-click on Channels, then select New => Receiver Channel.

  2. On the Create Receiver Channel dialog, select the General tab (Figure 17).

  3. Enter or select the following values:

    • Channel Name: busToMQ (this must be the exact name used when you defined the sender queue on the MQ link)
    • Transmission Protocol: TCP/IP

    Connection name and transmission queue are not needed for receiving; defaults are used.

    Figure 17. Create Receiver Channel dialog
    Figure 17. Create Receiver Channel dialog

Do not start the receiver channel, busToMQ; it will be automatically started when requests are received into it. You will see two channels defined in WebSphere MQ, as shown in Figure 18.

Figure 18. WebSphere MQ queues
Figure 18. WebSphere MQ queues

We have now completed the steps to connect TheBus to WebSphere MQ. Next, we will step through how to send a message from WebSphere MQ into SIBus.


Messaging test utilities

When we send a message from WebSphere MQ into the bus, the format of that message is an array of bytes. Our logging mediation (Part 4) will log JMS:Text messages. We have added code to that mediation to also handle byte arrays. This code is provided in the LoggingMediationRevised file included in the download file for this article

There are several ways to place messages on and read messages from WebSphere MQ for testing purposes. One that we particularly like is a free utility we mentioned earlier that is available as a WebSphere MQ support pack, rfhutil. Download it from the IBM Software Support page. Simply unzip the download ZIP file and run rfhutil.exe. We will use this utility throughout the rest of this article to view and remove messages from queues and to place messages onto WebSphere MQ queues. Since we will need to view what messages are received by a destination as part of our testing, we will assign the logging mediation (see sidebar) to destinations we want to monitor.


Send a message from SIBus to WebSphere MQ

In Part 3 of this series of articles, we implemented a simple JMS client that sends a package delivery confirmation message to a destination. That message is read by a message-driven bean (MDB) and then processed. As part of Posts-R-Us ESB strategy, the company is now changing how they deliver delivery confirmations to their CICS backend systems: rather than using an MDB, which in the production system would make a JCA call to CICS, they will now use WebSphere MQ for communication to and from CICS.

We will modify our configuration from Part 3 so that it now forwards the message to WebSphere MQ.

  1. If you already have the setup for the JMS example in Part 3, you will need to disable the MDB to stop it from reading the messages sent into the bus. You can do this by changing the activationSpec for the MDB, or by stopping the EAR file. If you do not have the JMS setup, follow steps 1 through 12 in Part 3 to setup the destination; you do not need the activation spec since we will not be using an MDB. For the JMS client to to send a message into the destination, your setup needs to contain the PackageReceivedDestination and the JMS entities.

  2. (Optional) To maximize our visibility to the process and to help our debugging, install LoggingMediationRevised (rather than LoggingMediation) by following the instructions in Part 4. Assign LoggingMediationRevised to PackageReceivedDestination.

  3. (Optional) Follow the instructions in either article to have the JMS client send a message to the destination and confirm that the message is logged in SystemOut.log.

Create a queue in WebSphere MQ to receive messages from the bus

We need to create a queue in WebSphere MQ that will receive the message from the bus. In a production environment, the backend systems would then read the messages from this queue. In our test environment, we will use the rfhutil utility to read the messages.

  1. In the WebSphere MQ Explorer, navigate to WebSphere MQ => QM_reinitz => Queues.

  2. Right-click on Queues, then select New => Local Queue.

  3. On the Create Local Queue dialog, select the General tab (Figure 19).

  4. For Queue Name, enter DeliveryConfirmationQueue, then OK.

Figure 19. Create Local Queue dialog
Figure 19. Create Local Queue dialog

You should see the following queue definitions:

Figure 20. Queue definitions
Figure 20. Queue definitions

Create a foreign destination to send messages from the bus to WebSphere MQ

In the bus, we need to create a foreign destination that is a virtual queue in WebSphere MQ. Because a foreign destination represents an endpoint in WebSphere MQ, you cannot attach a mediation to it.

  1. In the WebSphere Application Server admin console, select Buses => TheBus => Destinations.

  2. Select New.

  3. Select Foreign.

  4. Select Next.

  5. Step1: Set foreign destination attributes. Enter or select the following values (Figure 21):

    • Identifier: DeliveryConfirmationQueue@QM_reinitz (queue in WebSphere MQ)
    • Bus: TheForeignBus (the bus you are sending the message to)

    Select Next.

    Figure 21. Step1: Set foreign destination attributes
    Figure 21. Step1: Set foreign destination attributes
  6. Step2: Confirm foreign destination creation. Select Finish then Save. You should have the destinations shown in Figure 22.

    Figure 22. Destinations list
    Figure 22. Destinations list

Complete routing and test

We now need to route from the destination in Part 3, which the JMS client calls, and the foreign destination we just created.

  1. From the Destinations list (Figure 22), select PackageReceivedDestination.

  2. Set the Default forward routing path to TheForeignBus: DeliveryConfirmationQueue@QM_reinitz.

  3. Select OK and Save.

  4. Restart the server. We are now ready to test messaging from the JMS client to WebSphere MQ.

  5. Run the JMS client from a command prompt:
    launchclient packagedReceivedClient.ear

  6. (Optional) Check the SystemOut.log file to output from the logging mediation on the PackageReceivedDestination.

  7. Run rfhutil.exe.

  8. Select queue manager QM_reinitz.

  9. Select queue DeliveryConfirmationQueue.

  10. Select Read Q.

  11. You should see the message on the queue shown in Figure 23.

    Figure 23. Delivery confirmation
    Figure 23. Delivery confirmation

You can also check the SystemOut.log file to see the output of the logging mediation on the PackageReceivedDestination:

SystemOut  O Message logged. The payload of the message is Package Received - 24595023

Send a message from WebSphere MQ to the SIBus

In Part 5 of our series, we created a package tracking Web service available on the ESB to support a variety of client applications that require package tracking data. One type of access needed is via WebSphere MQ. In this case, the system making the request is not SOAP-enabled, so it will send the XML body of the SOAP message to the bus via WebSphere MQ. (In a future article in this series, we will show how to convert this XML message into a SOAP message.) For now, we will focus on getting the message from WebSphere MQ onto the bus.

Create a bus destination to receive messages from WebSphere MQ

We need a bus destination to receive the messages placed onto the remote queue in WebSphere MQ. This will be a regular queue destination.

  1. From the WebSphere admin console, select Buses => TheBus => Destinations.

  2. Select New.

  3. Select Queue.

  4. Select Next.

  5. Step 1: Set queue attributes. For Identifier, select PackageTrackingFromMqDestination, then Next.

  6. Step 2: Assign the queue to a bus member. Select node1:server1, then Next.

  7. Step 3: Confirm queue creation. Select Finish.

  8. To know that the message reaches the destination on the bus, install the LoggingMediationRevised (rather than LoggingMediation), following the instructions in Part 4, and assign it to PackageTrackingFromMqDestination.

  9. Save.

You should have the destinations listed in Figure 24. (If you have the results from Part 3 or Part 5 setup in the same server, you will see additional destinations listed.)

Figure 24. Destinations list
Figure 24. Destinations list

Create a remote queue to send messages from WebSphere MQ to the bus

  1. In WebSphere MQ Explorer, expand WebSphere MQ => QM_reinitz => Queues.

  2. Right-click Queues, then select New => Remote Queue Definition.

  3. On the Create Remote Queue Definition dialog, select the General tab (Figure 25).

  4. Enter or select the following values:

    • Queue Name (local to the WMQ Queue Manager): PackageTrackingRequestRemoteQueue
    • Remote Queue Name (a queue destination in WebSphere Application Server): PackageTrackingFromMqDestination
    • Remote Queue Manager Name: QM_TheBus (the name that WebSphere MQ knows your bus as; this was specified when you created an MQ link)
    • Transmission Queue Name: QM_TheBus (You created a transmission queue when you created a sender channel to talk from MQ to your bus; here, it just happens to have the same name as the remote queue manager name.)

    Select OK.

Figure 25. Create Remote Queue Definition dialog
Figure 25. Create Remote Queue Definition dialog

After the queue is created you will have something similar to Figure 26.

Figure 26. Queue list
Figure 26. Queue list

Test using a remote queue to send a message from WebSphere MQ to the bus

As you test sending messages into the SIBus, you may need a way to remove the messages in the bus. Navigate to Buses => TheBus => Destinations => PackageTrackingFromMqDestination => Queue Points => node1.server1-TheBus => Messages. You can view the details of messages sent to the destination and also delete individual or all messages. This is an alternative way to use LoggingMediationRevised to see the messages sent from WebSphere MQ.

We have included an XML file for our sample application that contains the code needed to request package status for a specific trackingNumber. We will use this file, track123.xml, to test sending a message from WebSphere MQ to a bus destination.

Remember: the MQToBus channel in WebSphere MQ must be running. If you restart your machine, or WebSphere MQ, or WebSphere Application Server, you may have to restart the channel. The status should be Running.

To put a message onto the remote WebSphere MQ queue PackageTrackingRequestRemoteQueue, we will use rfhutil:

  1. Run rfhutil.exe.

  2. Select the Main tab (Figure 27).

    Figure 27. Run rfhutil utility, Main tab
    Figure 27. Run rfhutil utility, Main tab
  3. Enter or select the following values:

    • Queue Manager Name: QM_reinitz
    • Queue Name: PackageTrackingRequestRemoteQueue

    Select Read File to load the contents from track123.xml.

  4. To see the contents of the file, select the Data tab (Figure 28), then select XML as the Data Format.

    Figure 28. Run rfhutil utility, Data tab
    Figure 28. Run rfhutil utility, Data tab
  5. Return to the Main tab (Figure 27), and select Write Q.

  6. In the WebSphere Application Server Systemout.log file, you should see the output from the LoggingMediationRevised mediation:

    SystemOut     O Message logged. The payload of the message is <?xml version="1.0" encoding="UTF-8"?>
    <p843:getPackageStatus xmlns:p843="http://service.postrus">
             <trackingNumber>123</trackingNumber>
    </p843:getPackageStatus>

Conclusion

In Part 6 of this article series, we described the support in WebSphere Application Server V6 Message Resources for exchanging messages with WebSphere MQ. We described the steps to setup connectivity between the SIBus and WebSphere MQ, how to test sending a message from MQ to the SIBus, and how to test sending a message from SIBus to MQ.


Download

DescriptionNameSize
Code sampleesb_part6_code.zip  ( HTTP | FTP )5 KB

Resources

Comments

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Open source
ArticleID=92121
ArticleTitle=IBM WebSphere Developer Technical Journal: Building an Enterprise Service Bus with WebSphere Application Server V6 -- Part 6
publish-date=08172005