A flexible and scalable WebSphere MQ topology pattern
Part 3: Workload-balanced WebSphere MQ client connections for SCA applications
This content is part # of # in the series: A flexible and scalable WebSphere MQ topology pattern
This content is part of the series:A flexible and scalable WebSphere MQ topology pattern
Stay tuned for additional content in this series.
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
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
|invokeAsync||This method implements an asynchronous invocation of the target service. After the request message has been sent control is returned immediately.|
|invokeAsyncWithResponse||This 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
The examples are provided as IBM Integration Designer projects (created with V126.96.36.199), 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.
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.
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:
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.
- IBM Business Process Manager and Service Component Architecture resources
- Asynchronous processing in WebSphere Process Server
- Exception handling in WebSphere Process Server and WebSphere Enterprise Service Bus
- Using Quality of Service qualifiers in WebSphere Integration Developer V7
- WebSphere Process Server invocation styles
- Parallel invocation of synchronous services in WebSphere Enterprise Service Bus
- Enabling SCA-MQ integration via MQ bindings
- Recovering from failed asynchronous SCA service invocations on WebSphere Process Server
- Exception handling and recovery using synchronous or asynchronous service invocation
- WebSphere MQ resources
- WebSphere MQ V7 documentation in IBM Knowledge Center
- Using WebSphere MQ with high availability configurations
- The Cluster Queue Monitoring example program (AMQSCLM)
- WebSphere MQ product page
- WebSphere MQ product family
- WebSphere MQ documentation library
- IBM Redbook: WebSphere MQ V7 features and enhancements
- Download a free trial version of WebSphere MQ
- WebSphere MQ forum
- WebSphere MQ SupportPacs
- developerWorks resources