Invoking WebSphere MQ Exposed Web Services Using the BizTalk Adapter for MQSeries.
Summary: This article covers how to use the BizTalk Adapter for MQSeries v2.0 with the WebSphere MQ transport for SOAP to invoke web service operations using MQSeries as transport protocol.
Introduction.
Web services and business process integration are becoming more and more interrelated as standards are developed and adopted. Standards like BPEL4WS and BPELJ build on top of existing web service standards such as WSDL and SOAP. The current version of BizTalk Server 2004 provides several ways to interact with web services using the SOAP and WSE 2.0 adapter and BPEL import/export wizards. Despite the power of these features the one limitation inherent in them is the required use of the HTTP transport protocol to communicate with other web services.
MOM technologies add powerful capabilities to web services such as reliable messaging, routing, security, ordered delivery and asynchronous invocation. Today, platforms like Systinet Gateway are completely focused in integrating MOM technologies (such as JMS) with web services.
WebSphere MQ (also known as MQSeries) is one of the most powerful and popular MOM technologies used across many platforms today. Part of MQSeries’ last release included a set of classes that allowed .NET developers to receive/send messages from/to MQSeries queues. Due to its wide adoption and cross-platform architecture, MQSeries provides a nice alternative to the classic HTTP transport for web service invocation. This is the idea behind the WebSphere transport for SOAP, an MQSeries add-in that allows the development of web services that use MQSeries as underlying transport.
WebSphere MQ transport for SOAP allows SOAP-formatted messages to be used in WebSphere applications. Currently it is implemented either for Apache Axis and .NET hosted environments. This transport operates as an extra layer over WebSphere MQ and represents a powerful alternative to HTTP when developing Web Services. The following figure shows an overview of WebSphere MQ transport for SOAP architecture:
Using WebSphere MQ transport for SOAP is amazingly simple. It implements the necessary infrastructure to process SOAP messages and invokes the target operations. WebSphere MQ transport for SOAP also comes with a set of tools that allows proxy-generation in languages such as Java, C# or VB.NET. It also generates the necessary listeners to receive SOAP messages and translates them to class’s methods. Those listeners are automatically generated by the underlying framework for every Web Service.
Combining some of the features exposed above make it possible to develop .NET applications that invoke either .NET or J2EE Web Services using WebSphere MQ as the transport protocol.
WebSphere MQ transport for SOAP abstracts the required logic to invoke Web Services operations despite of their native technology. This feature allows interacting with both .NET and J2EE Web Services.
As well as any multi-transport Web Services technology, the required information to deliver SOAP messages to the target service in encapsulated in the URI. In the case of WebSphere MQ transport for SOAP the uris must have a well-defined format that describes the QueueManagers, the request and reply queues among other key aspects. For instance the URI: “wmq:SOAP.TestService@QM_laura?replyToQueue=ResponseQueue,connectQueueManager=QM_laura” Indicates that messages will be sent to the SOAP.TestService queue and the response will be delivered to ResponseQueue queue and the target QueueManager is QM_laura. Previously the required listeners must be active in order to retrieve the message for the request queue, invoking the operation in the service and put the response in the response queue.
All the complex logic required to translate the SOAP messages into MQ native messages and the process it relies over to the listeners. These listeners are automatically generated using a set of the tools that comes with the WebSphere MQ transport for SOAP installation package.
WebSphere transport for SOAP provides a high-level infrastructure that makes amazingly easy to develop .NET applications that interact with either AXIS or .NET-based Web Services. However this entire infrastructure relies on the processing of SOAP messages that arrive to MQSeries queues. Due to this fact we can use the native MQSeries API for .NET to send SOAP messages to MQSeries queues and receive the appropriate responses. And if we plan to uses BizTalk Server 2004 to invoke Web Services developed using the WebSphere transport for SOAP then the MQSeries adapter seems to be a great choice.
Microsoft BizTalk Adapter for MQSeries.
This adapter allows BizTalk Server 2004-based applications to interact with MQSeries as a messaging platform. The adapter has two main components: the BizTalk component manages all the BizTalk-side communication and the MQSeries component (referred as MQSAgent) communicates with the MQSeries Server.
Conceptually the BizTalk Server 2004 adapter for MQSeries isn’t very different to other adapters; however it provides the always important bridge between J2EE and .NET platforms. In the next section we explore how to uses the MQSeries adapter to invoke Web Services developed using the WebSphere MQSeries transport for SOAP.
A simple example.
The first part of this example is the development of a J2EE-Axis Web Service. To develop a Web Service under the Axis platform you don’t need any special code. Just to develop a simple Java class.
| public class TestService { public TestService() { } public String echostr(String msg) { return msg; } } |
The next step is to generate the artifacts (queues, proxies and listeners) required to invoke the Web Services. To do this we use the deployWMQService utility provided as part of the WebSphere MQ transport for SOAP installation package. This utility accepts parameters as the source java file, the QueueManager on which the service is to be hosted, the request queue, etc. DeployWMQService produces proxies to invoke the Web Service either in Java, C# or VB.NET as well as a listener used to interact with the MOM infrastructure. Even though the J2EE Web Services are very easy to code (just a Java class) the current version of WebSphere MQ transport for SOAP requires that those services are implemented through Apache Axis Framework.
The JMSListener generated as part of the deployment process is intended to monitor the request queue for incoming messages. The listener is derived from the Java class javax.jms.MessageListener and the method onMessage() from this base class is overridden and is automatically called by the base class when a message arrives. This method picks up the incoming JMS message, extracts the text of the message and then feeds it to the Axis engine for processing. Both the SOAP processing and the actual invocation of the service itself are performed within the listener thread. The SOAP response message from Axis is then returned to the client via the WebSphere MQ response queue.
Now if we want to invoke the EchoStr operation of the above-coded Web Service, we need to generate the followed SOAP message:
| <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="TestService_Wmq" xmlns:types="TestService_Wmq/encodedTypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><tns:echostr><in0 xsi:type="xsd:string">Hello Java MQ Service</in0></tns:echostr></soap:Body></soap:Envelope> |
To invoke the sample Web Service from BizTalk Server 2004 the first thing that we need to do is to install and configure the MQSeries adapter. To do this you should only follow the instruction that comes with the installation package.
To develop a BizTalk Server 2004 orchestration that invokes the EchoStr operation we need to create and configure the appropriated send-receive port using the MQSeries transport. Our sample orchestration just “magically” receives the required SOAP message, sets the required properties and sends it to the MQSeries queue. Then the appropriate SOAP response is generated to an MQSeries response queue.
The SOAP messages that will be consumed for the JMSListener must have a well-defined set of properties like the response queue, the format, etc. Suppose that our input SOAP message is OutMsg, and then we can use the following code, in a MessageAssigment shape, to set some required context properties.
| OutMsg.MainPart= InMsg.MainPart; MsgId= System.Guid.NewGuid(); MsgIdStr= MsgId.ToString(); OutMsg(MQSeries.MQMD_ReplyToQ)= "ResponseQueue"; OutMsg(MQSeries.MQMD_MsgId)= MsgIdStr; OutMsg(MQSeries.MQMD_CodedCharSetId)= 1208; OutMsg(MQSeries.MQMD_MsgType)= 1; |
The code above sets a well-defined message id that needs to be correlated with the SOAP response. The code also sets the queue where the SOAP response should be sent as well as other required properties. When we send this message using a SendPort target to the SOAP.TestService queue (which is the queue generated in the Web Service deployment process) the following SOAP response is generated.
| <?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <ns1:echostrResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="TestService_Wmq"> <echostrReturn xsi:type="xsd:string">Hello Java MQ Service</echostrReturn> </ns1:echostrResponse> </soapenv:Body> </soapenv:Envelope> |
The final step that we need to do is read the message with a receive port and check the CorrelationID property to correlate the message with a previously sent request. The uses of MQSeries adapter to send-receive SOAP messages can be very useful in some well-defined scenarios like, for instance, a process that receives SOAP messages over HTTP and routes then to a target Web Service that uses MQSeries as transport.
Where are we?
In this article we have been exploring the how to combine BizTalk Server 2004 adapter for MQSeries to invoke Web Service operation deployed using the WebSphere MQ transport for SOAP. Using variants of the code explained in this article we can develop BizTalk Server applications that can take advantage of Web Services that use MQSeries as transport.