Integration of SOAP and IBM MQ

The IBM MQ transport for SOAP extends SOAP, and web services tools and run time, with IBM MQ as an alternative transport to HTTP for SOAP. You do not need to modify existing web services to use IBM MQ transport for SOAP as a transport. The transport uses a custom URI format for SOAP/JMS. The W3C URI format for SOAP/JMS is supported in a limited way by Axis2 clients.

An additional line of code has to be added to clients in the .NET Framework 1, .NET Framework 2, and Axis 1.4 environments. No additional code is required in Axis 2 and Windows Communication Foundation (WCF) clients. The IBM MQ SOAP listener runs services in the .NET Framework 1, .NET Framework 2, and Axis 1.4 environments. The IBM MQ transport for SOAP is integrated into some other application server environments, including WCF, CICS®, and WebSphere Application Server.

What is SOAP?

SOAP ¹ describes the standardized format of the messages and interaction protocols that applications use to exchange requests, replies, and datagrams. SOAP is independent of the transport used to transfer the messages, and of the application environment that sends and receives the messages. The W3C defines SOAP Version 1.2 succinctly:

SOAP Version 1.2 provides the definition of the XML-based information which can be used for exchanging structured and typed information between peers in a decentralized, distributed environment. ² .

To use SOAP it must be bound to a transport, such as HTTP, e-mail, or IBM MQ.

A SOAP protocol binding framework is the set of rules for carrying a SOAP message on top of another protocol, such as HTTP. SOAP Version 1.2 Part 2: Adjuncts (Second Edition) describes the SOAP HTTP binding.

The W3C candidate recommendation, 4 June 2009, SOAP over Java Message Service 1.0, describes the recommendation for the SOAP JMS binding. As JMS is an API specification, and not a transport protocol, the JMS SOAP recommendation does not describe the wire-format of SOAP JMS messages. It describes the SOAP interaction protocols and the JMS API binding. Consequently, when using the JMS SOAP recommendation you must still use the same JMS implementation for the SOAP client and the SOAP server. It does enable a SOAP JMS application to be run on any implementation of JMS. A JMS implementation can be plugged into a J2EE application server, if both the server and the JMS implementation comply with the JCA specification. IBM MQ JMS complies with the JCA specification and can be plugged into a compliant application server.

IBM MQ transport for SOAP binding is like the proposed W3C standard, but it is not the same. Its usage is described in the topic MQRFH2 SOAP settings. Unlike the W3C candidate recommendation, the SOAP binding is not formally specified. Effectively, it is the HTTP binding, and the service address takes the form, jms:/queue?name=value&name=value..., rather than http://authority/path?query#fragment. jms: is not an officially registered IANA URI scheme.

What is a web service?

SOAP enables programs written in different languages, running on different platforms, to communicate using various transport protocols. SOAP is the protocol specification. A web service is an application that provides a service through a SOAP interface that can be accessed using internet protocols.

An important goal of SOAP is to provide services that clients can use easily. Once we have designed a client to use a service, we can program the call to invoke the service without reference to external documentation. Service interfaces are described in XML, in a WSDL document. The query, http://authority/path?wsdl, returns the WSDL description of a SOAP service.

Developing web services

Web services have a client and a service part. The service is written first, either starting from the interface description in WSDL, or by following the rules for writing the service class. Web service toolkits have utilities to generate WSDL from the interface definition of a class; for example java2wsdl or disco. They also have tools to generate or class skeletons from WSDL interface descriptions; for example wsdl2java, wsimport, or wsdl. The former is known as bottom up development, and the latter top down.

The amqwdeployWMQService command in IBM MQ transport for SOAP uses these tools to generate WSDL, client stubs, and client proxies.

Web services are typically written using an integrated development environment targeted at a particular application server environment:

Eclipse IDE for Java EE Developers

Creates web services for Axis 2. Supports JAX-RPC and JAX-WS

Rational® Application Developer V7.5

Creates web services for WebSphere Application Server V7 and previous versions, and also for Axis. Supports JAX-RPC and JAX-WS.

WebSphere Integration Developer V6.2

Creates web services for WebSphere Process Server and WebSphere ESB. Supports JAX-RPC and JAX-WS.

Visual Studio 2012

Creates web services for .NET Framework 3.5 and earlier ( Windows Communication Foundation)

We can use any of these tools in combination with IBM MQ transport for SOAP. Once we have developed a service to use with HTTP, use the amqwdeployWMQService tool to deploy the services to use IBM MQ as a transport. We can write a new client using the output from the tool, or modify your existing clients to use the IBM MQ transport for SOAP.

If IBM MQ transport for SOAP is integrated into the application environment, then we do not need use the amqwdeployWMQService tool or modify the client code. The client SOAP layer directs client requests that have a URI with the prefix jms: to the IBM MQ transport for SOAP. The server SOAP layer calls IBM MQ transport for SOAP to wait for jms: SOAP requests, and returns responses to IBM MQ transport for SOAP.

Typically, .NET services have been developed bottom up using web service annotations in code, and Java services top down, using WSDL interface definitions. The difference in approaches is narrowing, as Java Standard Edition Version 6 supports JAX-WS 2.0, and uses annotations to qualify the definition of service interfaces. It is now as easy to develop Java services bottom up as top down. Which approach you choose is a matter of development method.

The web services client is written after the service, using the WSDL service definition and generated client stubs and proxies. In some applications, the service definition is not known when the client is written. The client retrieves the service WSDL and creates service requests dynamically. More commonly the service definition is known, but the address to which the service is deployed, is not. The web service toolkit generates interfaces for the client to use to make service requests. The client provides the service address when it is required. In the third case, the WSDL contains all the information a client needs. The WSDL contains both the interface and address of the service. The code generated by the web service toolkit has all the information needed by the client to make requests of a service.

We can use any of these three styles with IBM MQ transport for SOAP.

Web service application environments

Web service toolkits require a mapping from the WSDL definition of a service to the streams of bytes that are transferred in SOAP requests and responses. The byte stream is defined by the SOAP specification, and is contained in the SOAP envelope. The SOAP envelope is shown in Figure 1.

<?xml version='1.0'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header> <!-- optional -->

<!-- headers... -->

</soap:Header>
<soap:Body>
<!-- payload or fault message -->

</soap:Body>
</soap:Envelope>

Mapping from the SOAP envelope to the language binding and back is part standardized, and part proprietary. The mapping is fundamental to the .NET architecture, and is provided as part of the Common Language Runtime (CLR). The mapping is standardized in Java by JAX specifications. Because the Java mappings are standardized, Java web service clients and services are portable between different Java-based application environments. JAX-RPC (sometimes called JAX-WS 1.0) is the mapping most in use today. It is supported by Axis 1.4. JAX-WS (sometimes called JAX-WS 2.0) is a greatly improved standard and is likely to replace JAX-RPC rapidly. JAX-WS is supported by Axis 2.0. IBM MQ 7.0.1 does not support JAX-WS and Axis 2.

IBM MQ transport for SOAP does not alter the contents of the SOAP envelope, and the contents do not affect the transport. The language bindings do affect the IBM MQ transport for SOAP. IBM MQ 7.0.1 supports .NET Framework 1, .NET Framework 2, and Axis 1.4 using the code and utilities shipped with IBM MQ transport for SOAP. Support for the WebSphere transport for SOAP in .NET Framework 3 and 3.5 is implemented using the IBM MQ custom channel for Windows Communication Foundation.

Other SOAP development and run time environments might ship support for IBM MQ transport for SOAP, and support different languages. For example, web services running on CICS supports languages such as COBOL and PL/1.

What is IBM MQ transport for SOAP?

IBM MQ transport for SOAP is a SOAP binding and a web services toolkit. Together, they enable applications to exchange SOAP messages using IBM MQ rather than HTTP. Figure 2 shows IBM MQ as an alternative to HTTP as a SOAP transport.

SOAP over HTTP is shown as (1) in the diagram. The client SOAP layer converts a request into a SOAP message and the HTTP component sends over TCP/IP. The HTTP server component listens for HTTP requests, typically on the TCP/IP port 80. If the request is for a SOAP service, the HTTP server component calls the SOAP layer to convert the SOAP request into method call. It then returns the response.

SOAP over IBM MQ is shown as (2). The client application registers the IBM MQ SOAP sender component as a handler for the jms: protocol with the SOAP layer. The SOAP layer passes SOAP messages addressed to jms: to the IBM MQ SOAP sender. The sender uses the URI in the message to place the message on the request queue with the required qualities of service. The corresponding IBM MQ SOAP listener waits for messages on its request queue and calls the SOAP layer to process requests and return responses.

The SOAP sender and listener are normal IBM MQ programs. They can be connected to the same queue manager, as in Figure 3, or connected to different queue managers; see Figure 4. The client can be connected by a client connection.

W3C candidate recommendation for binding SOAP to JMS.

The W3C candidate recommendation defines the SOAP over JMS binding; SOAP over Java Message Service 1.0. Also useful for its examples is URI Scheme for Java(tm) Message Service 1.0³.

Some application frameworks, such as WebSphere Application Server v7, have support for the W3C candidate recommendation. Send SOAP requests formatted with a URI compatible with the W3C candidate recommendation using the Axis2 client; see W3C SOAP over JMS URI for the IBM MQ Axis 2 client. The Axis2 client sends a SOAP request formatted with either a W3C or an IBM MQ transport for SOAP based on URI in the SOAP request.

Axis2 client support for the W3C recommendation is introduced in the 7.0.1.3 fix pack. Support for other clients, and for the SOAP listeners provided by IBM MQ is not provided.