A flexible and scalable WebSphere MQ topology pattern: Part 3: Workload-balanced WebSphere MQ client connections for SCA applications

Part 3 of this article series contains SCA code examples to create workload-balanced client connections to a WebSphere MQ queue manager cluster configured as an MQ hub – the "flexible and scalable topology pattern" described in Part 1.

Peter Broadhurst (peter.broadhurst@uk.ibm.com), Level-3 Service Architect, IBM

Photo of Peter BroadhurstPeter Broadhurst is a Level-3 Service Architect who works on WebSphere MQ, WebSphere ESB, WebSphere Service Registry and Repository, and various components of WebSphere Application Server, including transactions, MQ support, and web services standards. He has many years of experience working with WebSphere MQ, WebSphere Message Broker, and other IBM integration products. His experience includes Development and Level-3 Service, as well as helping design solutions for customers in the field, and he travels regularly on assignment to work with customers in ASEAN. You can contact Peter at peter.broadhurst@uk.ibm.com.

Luberto Klaassen (luberto.klaassen@nl.ibm.com), Application Architect and Developer, IBM

Photo of Luberto KlaassenLuberto Klaassen works in IBM Global Business Services for several customers in the Netherlands on the design, implementation, and administration of Java EE, SOA, and BPM integration solutions. His product focus areas include WebSphere ESB, WebSphere Process Server, and IBM Business Process Manager. Peter's previous articles on a flexible and scalable WebSphere MQ topology pattern inspired him to create the SCA example for this pattern that is described in this article. You can contact Luberto at luberto.klaassen@nl.ibm.com.

12 March 2014


This article provides Service Component Architecture (SCA) code examples that show how an application creates workload-balanced connections to an IBM® WebSphere® MQ queue manager cluster. The code examples are similar to the Java™ Enterprise Edition (Java EE) code examples provided in Part 2 of this series, and they use the same WebSphere MQ sandbox environment. The article also shows you how to deploy the sample applications to IBM Business Process Manager Advanced (hereafter called IBM BPM) single-server and Network Deployment environments. The sample applications can also be deployed on WebSphere Enterprise Service Bus. You can use these examples as the basis for any SCA application that performs JMS messaging, including the following JMS use cases:

  • Message listener -- Beginning a long-running listener for messages arriving for processing on a queue or a durable subscription.
  • Fire-and-forget -- Sending a message to a queue, or publishing to a topic, where no response is expected. Examples include sending a data update, emitting an event, or sending a reply to a request.
  • Synchronous request-response -- Sending a request message where the response is immediately required for processing to continue, such as querying essential data.
  • Two-way asynchronous messaging -- Using fire-and-forget for requests and a message listener for responses, where the responses can be handled at any time.

Like the Java EE code examples in Part 2 of this series, the code examples in this part are provided as-is, and they show you how to achieve continuous service availability and workload-balanced connections using features in WebSphere MQ V7.0.1, V7.1, and V7.5. The examples in Part 3 do not exploit any of the built-in workload-balancing or reconnection capabilities provided by the WebSphere MQ Client Channel Definition Table (CCDT), Connection Namelist, or Automatic Client Reconnection features in order to support two-phase (XA/JTA) transactions and provide maximum flexibility compared to use of Java EE connection pooling and other features of IBM BPM.

The scripting examples provided with Part 2 to set up WebSphere MQ and WebSphere Application Server can also be used to set up the environment to run the SCA examples in this article. The advanced request-response example, however, can't be easily implemented with SCA and is not covered in this article. At the bottom of this article, you can download a reduced version of these WebSphere MQ and WebSphere Application Server scripts that do not create the resources for the advanced request-response example.

SCA workload management

As in Part 2, the examples in this article assume a WebSphere MQ topology in which you do not have WebSphere MQ queue managers running locally on the application server machines. Instead, applications connect over a network to a WebSphere MQ hub consisting of an WebSphere MQ cluster containing multiple active queue managers. Therefore the applications must be configured to connect to one or more queue managers in the WebSphere MQ hub as WebSphere MQ clients over the network. For availability and scalability reasons, you should provide multiple queue managers for an individual application to connect to with workload balancing between a set of queue managers in the WebSphere MQ cluster. The sections below show you how to do this for outbound and inbound messaging scenarios.

Outbound workload management

SCA applications depend on the same connection pooling and transaction management features of the application server as Java EE applications. Therefore SCA applications encounter the same restrictions as Java EE applications when using WebSphere MQ Client Channel Definition Tables (CCDT) or connection namelists (for more information, see Part 2). To cope with these restrictions, an extension to the Java EE example code library is provided to perform outbound workload-management for SCA applications.

Outbound WebSphere MQ connections in MQ applications are configured using WebSphere MQ or WebSphere MQ JMS import bindings. In order to perform workload-management for each outbound connection, you must configure two or more import bindings to point to different sending gateways. An SCA Java component can be used to route the outbound messages to these imports, using the API provided by the WLMSCAAttach class included in the code library.

Figure 1. API provided by the WLMSCAAttach class
API provided by the WLMSCAAttach class

The SCA Java component implements the same interfaces as the WebSphere MQ JMS imports, and functions as an adapter for the WLMSCAAttach class. The SCA export or component that needs to use the workload-managed outbound connections can just refer to the SCA Java component instead of referring to a single WebSphere MQ JMS import directly. Therefore the implementation of an existing SCA component doesn't have to be changed in order to use the workload-management capabilities of the WLMSCAAttach class. In the methods of the SCA Java component that implement the interfaces, one or both methods of the WLMSCAAttach class can be used, depending on the required interaction style. A short description of the methods provided by the WLMSCAAttach class is given in the table below. For a more complete description of Java service invocations, see the developerWorks article Asynchronous processing in WebSphere Process Server.

Table 1. API provided by the WLMSCAAttach class
invokeAsyncThis method implements an asynchronous invocation of the target service. After the request message has been sent control is returned immediately.
invokeAsyncWithResponseThis method implements a synchronous invocation of the target service. After the request message is sent, the thread blocks until the response is returned. The method offers the option to define a timeout.

Inbound listener workload management using multiple endpoints

The primary challenge for managing inbound listener connections to WebSphere MQ is to ensure that each cluster queue has an application instance attached, even if one application instance fails. The solution described in this article is for each application instance to listen to multiple queue managers concurrently, as described in Part 1. A WebSphere MQ JMS resource adapter activation specification only supports connecting to a single queue manager and a single queue, but in an SCA module, you can avoid this restriction by using a WebSphere MQ JMS export for each instance of the cluster queue. This approach has been used in the SCA code examples explained below.

Example SCA applications

This article provides a set of SCA applications that demonstrate workload-balanced inbound and outbound WebSphere MQ client connections. They are designed to work together to give you a sandbox environment, where you can explore various aspects of the behavior. There are a set of sending components with web service interfaces that send request messages using the fire-and-forget and synchronous request-response patterns, and a single listener component that services the messages sent by both sending components.

Figure 2. Overview of downloadable SCA applications
Figure 2. Overview of downloadable SCA applications

The examples are provided as IBM Integration Designer projects (created with V7.5.1.1), with a set of precompiled deployable EAR files, as described below:

  • WLMJMSAttachLibrary – This code library is an extension of the library provided with Part 2. The library includes the WLMSCAAttach class that provides the outbound workload-management functionality as explained in a previous section of this article.
  • WLMSCAReceiver – An example SCA mediation flow component that listens for requests using two WebSphere MQ JMS exports and, for the request-response example, sends back a response via the export that delivered the request.
  • WLMSCAReceiverApp – The Enterprise Application project that was automatically generated for the SCA module containing the WLMSCAReceiver component.
  • WLMSCAAsyncSender – An example SCA Java component that forwards a fire-and-forget request message received via a web service export.
  • WLMSCASyncSender – An example SCA Java component that forwards a request message received via a web service export and synchronously returns the received response.
  • WLMSCASenderApp – The Enterprise Application project that was automatically generated for the SCA module containing the WLMSCAAsyncSender and WLMSCASyncSender components.

Fire-and-forget example

The WLMSCAAsyncSender SCA Java component uses the invokeAsync method of the WLMSCAAttach class to put a request message to the (clustered) WLMMDB.REQUEST queue. The WLMSCAAttach class performs efficient round-robin workload management to put the request message via one of the WebSphere MQ sending gateways. The functionality of this component is exposed via a web service export, which can be invoked by any suitable web service client.

The request message is received by the WLMSCAReceiver SCA mediation component, which just prints the message to the SystemOut or trace log using the WLMJMSLogger class.

Request-response example

The WLMSCASyncSender SCA Java component uses the invokeAsyncWithResponse method of the WLMSCAAttach class to put a request message to the (clustered) WLMMDB.REQUEST queue. It then waits for a response message in the (non-clustered) SENDINGAPP.REPLY queue. This response message is then returned to the web service client that sent the request message.

In order to effectuate the sending of the request, it must be committed immediately, before waiting for the response, by setting the Asynchronous Invocation quality-of-service qualifier of both SCA references to Call. Reference qualifiers are also used to set both the request and response expiration of the messages to 30 seconds.

The request message is received by the WLMSCAReceiver SCA mediation component. This component prints the request message to the SystemOut or trace log, and creates a response message using a BO map after a random delay (which can be configured via a promotable property). The response message is returned via the WebSphere MQ JMS export that received the request, in order to make sure that the SCA runtime will return the response message to the WebSphere MQ JMS import that was used to send the request message.

WebSphere MQ hub sandbox environment

The WebSphere MQ hub sandbox environment used in this article is a reduced version of the one used in Part 2. As shown in Figure 3 below, it contains a WebSphere MQ cluster of two queue managers. Both queue managers act as both sending gateways and receiving gateways. The queue managers are configured to accept client connections from the SCA applications, and have all of the queues required to run the applications defined.

Figure 3. WebSphere MQ sandbox environment created via the supplied MQSC scripts

To create the WebSphere MQ hub sandbox environment on your Linux®, UNIX®, or Windows® machine with WebSphere MQ V7.0.1 or later installed, run the following commands from the directory where you have extracted the MQSC scripts: Gateway1.MQSC and Gateway2.MQSC:

crtmqm GATEWAY1
crtmqm GATEWAY2
strmqm GATEWAY1
strmqm GATEWAY2
runmqsc GATEWAY1 < Gateway1.MQSC
runmqsc GATEWAY2 < Gateway2.MQSC

The MQSC scripts included with this article are reduced versions of the scripts provided with Part 2. So if you already ran these scripts in the environment in which you want to test these examples, there is no need to change anything. Part 2 also described the limitations of this environment, which you must take into account.

IBM BPM environment

You can choose to deploy both applications to an existing single server or clustered IBM BPM environment. Before deploying the applications, the WebSphere MQ resource adapter must be tuned, and the required JMS resources must be properly configured.

Tuning the WebSphere MQ resource adapter

To meet the non-functional criteria described in Part 1, you need to ensure that the WebSphere MQ resource adapter in the IBM BPM environment is tuned to maximize the reliability of the applications. Part 2 provided a full description of this tuning, as well as a Jython script to perform the tuning. You can download the Jython script at the bottom of the article and run it as follows from your deployment manager or single server profile:

  • Windows: C:\path\to\AppServer\profiles\PROFILE_NAME\bin\wsadmin -lang jython -f Configure_MQRA.py
  • Linux: /path/to/AppServer/profiles/PROFILE_NAME/bin/wsadmin.sh -lang jython -f Configure_MQRA.py

Creating the JMS resources in JNDI

Part 2 described the JMS resources that have to be created as well as the Jython script that creates them. The examples in this article use a subset of these resources, and therefore a reduced version of this Jython script is included in the download at the bottom of this article. To run it, use the following commands:

  • Windows: C:\path\to\AppServer\profiles\PROFILE_NAME\bin\wsadmin -lang jython -f Configure_JMS_resources.py
  • Linux: /path/to/AppServer/profiles/PROFILE_NAME/bin/wsadmin.sh -lang jython -f Configure_JMS_resources.py

Deploying the applications

In IBM Integration Designer, add the WLMSCAReceiverApp and WLMSCASenderApp applications to a configured IBM BPM development environment via the Servers view. For a Network Deployment environment, you can deploy the applications from the EAR files included in the download using the Integrated Solutions Console and subsequently start these applications. You can use scripting to deploy and start the applications, but no script is supplied with this article.

Testing the applications

Both the fire-and-forget and the request-response examples are implemented as web services, which implies that you can test the examples with any suitable web service client. In IBM Integration Designer, you can test the examples using the Integration Test Client, but the download also includes test scripts for SoapUI and JMeter.

The SoapUI test script contains two sample SOAP requests to test the fire-and-forget and request-response examples. You may have to change the hostname and port number of the endpoints to values that are appropriate for your environment before you can run the sample requests.

The JMeter test script has been set up as a load test for the request-response example. The test assumes that the example applications have been installed in a clustered environment with at least two cluster members. The SOAP requests are intermittently sent to each of these cluster members. The thread group containing these requests has been configured to handle five requests concurrently to test how the applications behave under load. Each SOAP request contains a unique identifier, and the test plan verifies whether this identifier is also contained in the response message.


Code sample1mqtopology_sca_samples.zip279 KB


  1. The zip file contains code samples for IBM BPM Advanced V7.5, and setup scripts to create the sandbox environments for IBM BPM Advanced and WebSphere MQ.



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

Zone=WebSphere, Business process management
ArticleTitle=A flexible and scalable WebSphere MQ topology pattern: Part 3: Workload-balanced WebSphere MQ client connections for SCA applications