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 V184.108.40.206), 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.
|Code sample1||mqtopology_sca_samples.zip||279 KB|
- 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.
- IBM Business Process Manager and Service Component Architecture resources
- Asynchronous processing in WebSphere Process Server
This article explains various asynchronous aspects in Process Server and points out best practices along the way.
- Exception handling in WebSphere Process Server and WebSphere Enterprise Service Bus
This article explains how error conditions are captured and processed in WebSphere Process Server and WebSphere Enterprise Service Bus, and describes problem detection, retry behavior, exception propagation, and reporting.
- Using Quality of Service qualifiers in WebSphere Integration Developer V7
This article discusses how you can effectively use Quality of Service qualifiers provided by WebSphere® Integration Developer V7 to manage transactions, secure applications, and make reliable invocations in a business application.
- WebSphere Process Server invocation styles
This article explains how to determine which invocation style will be used at runtime, based on characteristics of your application.
- Parallel invocation of synchronous services in WebSphere Enterprise Service Bus
This article describes the design pattern for the parallel invocation of synchronous services using the aggregation function available for WebSphere ESB mediation flows. It takes you from learning about the basic mediation primitives to optimizing ESB performance.
- Enabling SCA-MQ integration via MQ bindings
The MQ Bindings feature in WebSphere Integration Developer V6.0.2, simplifies interoperability between SCA and MQ applications, and makes it easier to read and write native MQ messages to and from SCA applications.
- Recovering from failed asynchronous SCA service invocations on WebSphere Process Server
This article describes potential message routes and recovery scenarios. It explains how to configure the system to set up recovery, and it covers a wide range of SCA messaging options, including both WebSphere Default Messaging (JMS provider) and WebSphere MQ.
- Exception handling and recovery using synchronous or asynchronous service invocation
This technote explains how to handle exceptions during synchronous and asynchronous outbound processing, and what the differences and recommendations are for both invocation styles.
- Asynchronous processing in WebSphere Process Server
- WebSphere MQ resources
- WebSphere MQ V7 information center
A single Web portal to all WebSphere MQ V7 documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere MQ V7.
- Using WebSphere MQ with high availability configurations
Topic in the WebSphere MQ information center.
- The Cluster Queue Monitoring example program (AMQSCLM)
Topic in the WebSphere MQ information center.
- WebSphere MQ developer resources page
Technical resources to help you design, develop, and deploy messaging middleware with WebSphere MQ to integrate applications, Web services, and transactions on almost any platform.
- WebSphere MQ product page
Product descriptions, product news, training information, support information, trial download, and more.
- WebSphere MQ product family
A description of the ten or so different editions of WebSphere MQ.
- WebSphere MQ documentation library
WebSphere MQ information centers and product manuals.
- IBM Redbook: WebSphere MQ V7 features and enhancements
Describes the fundamental concepts and benefits of message queuing technology, describes the new features in V7, and provides a business scenario that shows those features in action.
- Download a free trial version of WebSphere MQ V7
A 90-day, full featured, no-charge trial of WebSphere MQ V7
- WebSphere MQ support page
A searchable database of support problems and their solutions, plus downloads, fixes, and problem tracking.
- WebSphere MQ forum
Get answers to your WebSphere MQ technical questions and share your knowledge with other users.
- WebSphere MQ SupportPacs
Downloadable code, documentation, and performance reports for WebSphere MQ products. The majority of SupportPacs are available at no charge, while others can be purchased as fee-based services from IBM.
- WebSphere MQ V7 information center
- WebSphere resources
- developerWorks WebSphere
Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
- developerWorks WebSphere application integration developer resources
How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application integration and business integration solutions.
- Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products.
- WebSphere forums
Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
- WebSphere demos
Download and watch these self-running demos, and learn how WebSphere products can provide business advantage for your company.
- WebSphere-related articles on developerWorks
Over 3000 edited and categorized articles on WebSphere and related technologies by top practitioners and consultants inside and outside IBM. Search for what you need.
- developerWorks WebSphere weekly newsletter
The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
- WebSphere-related books from IBM Press
Convenient online ordering through Barnes & Noble.
- WebSphere-related events
Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
- developerWorks WebSphere
- developerWorks resources
- Trial downloads for IBM software products
No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
- developerWorks business process management developer resources
BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
- developerWorks blogs
Join a conversation with developerWorks users and authors, and IBM editors and developers.
- developerWorks tech briefings
Free technical sessions by IBM experts to accelerate your learning curve and help you succeed in your most challenging software projects. Sessions range from one-hour virtual briefings to half-day and full-day live sessions in cities worldwide.
- developerWorks podcasts
Listen to interesting and offbeat interviews and discussions with software innovators.
- developerWorks on Twitter
Check out recent Twitter messages and URLs.
- IBM Education Assistant
A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.
- Trial downloads for IBM software products