How WebSphere MQ transport for SOAP processes Web services requests

WebSphere MQ transport for SOAP is based on a traditional request/response model. In the simplest case, using proxy classes, the client program sees this as a remote procedure call. The SOAP/WebSphere MQ client puts a message to a WebSphere MQ queue. This may be the request queue on the local queue manager or may be a remote queue in which case the message is then transported using WebSphere MQ to the appropriate SOAP/WebSphere MQ request queue. A dedicated SOAP/WebSphere MQ listener process monitors the request queue for incoming messages and then routes them through to the target Web Service using the appropriate host infrastructure. Two distinct types of SOAP/WebSphere MQ listener are provided, one for Apache Axis Web Services (SimpleJavaListener) and one for Microsoft .NET web services (amqwSOAPNETListener). Note that these listeners are distinct from the standard WebSphere MQ listener invoked by the runmqlsr command.

The sequence of control for this is as follows:

Client:    Client Program (provided by user)
              Client Proxy (generated by infrastructure [optional for Axis])
                  WebServices runtime (Axis or .NET infrastructure)
                      SOAP/WebSphere MQ Sender
                          WebSphere MQ
                                |
Server:                    WebSphere MQ
                      SOAP/WebSphere MQ Listener
                  WebServices runtime (Axis or .NET infrastructure)
          Service Program (provided by user)  

The client proxy is shown as optional for Axis because Axis supports three programming styles, only one of which requires a proxy. .NET always requires a proxy. See Basic Web service client programming for details of the different programming styles.

Figure 1 shows WebSphere MQ positioned between the SOAP/WebSphere MQ sender and listener, providing transport between the client application and the target Web service. Figure 2 and Figure 3 expand on that figure, showing queues and queue managers within WebSphere MQ. Figure 2 illustrates one queue manager (QM1) associated with the sender and one (QM2) with the listener. The sender puts a message on a transmission queue on QM1, from where it is transported to the request queue on QM2. The request queue is monitored by the listener. The listener invokes a Web service and then returns a message via a transmission queue on QM2 to a response queue on QM1. The listener can put messages on the dead-letter queue if a request fails. The sender can be local to QM1 or connected by a WebSphere MQ client connection. The listener can similarly be local to QM2 or connected by a WebSphere MQ client connection.

Figure 2. Queues used by SOAP/WebSphere MQ (separate queue managers)

Figure 3 illustrates a single queue manager (QM2) servicing both the sender and the listener. The sender places a message on the request queue, which is monitored by the listener. The listener returns a message to a response queue. The listener will put messages onto the dead letter queue if a response message cannot be returned. The sender and listener can be local to QM2 or connected by a WebSphere MQ client connection.

Figure 3. Queues used by SOAP/WebSphere MQ (single queue manager)

Processing is as follows:

1. A client program calls the appropriate WebServices framework in the same way as it would for HTTP transport, except that it must also register the 'jms:' prefix (see Basic Web service client programming).

2. The Axis or .NET framework marshals the call into a SOAP request message exactly as for SOAP/HTTP.

3. A WebSphere MQ service is identified by a URI prefixed with 'jms:'. When the framework identifies the 'jms:' URI, it calls the WebSphere MQ transport sender code; com.ib.mq.soap.transport.jms.WMQSender (for Axis) or IBM.WMQSOAP.MQWebRequest (for .NET). If the framework encounters a URI with an 'http:' prefix, it calls the standard SOAP over http sender.

4. The SOAP message is transported by the WebSphere MQ sender over WebSphere MQ, via the request queue, ready for the SimpleJavaListener (for Java) or amqwSOAPNETListener (for .NET) to receive it.

   The SOAP/WebSphere MQ listeners are standalone processes but are multithreaded with a tailorable number of threads.

5. The SOAP/WebSphere MQ listener reads the incoming SOAP request, and passes it to the appropriate Web service infrastructure.

6. The Web service infrastructure parses the SOAP request message and invokes the service, exactly as it would have done for a message that arrived on an HTTP transport

7. The infrastructure formats the response into a SOAP response message and returns it to the SOAP/WebSphere MQ listener.

8. The listener returns the message via the response queue over WebSphere MQ to the SOAP/WebSphere MQ sender, which passes it to the client Web service infrastructure.

9. The client infrastructure parses the response SOAP message and hands the result back to the client application.

Each application context is served by a separate WebSphere MQ request queue. The application context is controlled in Axis by ensuring that the SOAP/WebSphere MQ listener and service execute in the appropriate directory and with the correct CLASSPATH. Application context is controlled in .NET by the SOAP/WebSphere MQ listener executing the service in a context created by a call to ApplicationHost.CreateApplicationHost. This call specifies the target execution directory. Each service then operates in the directory in which it was deployed. The queues are generated automatically by the SOAP/WebSphere MQ deployment utility, which also generates the infrastructure necessary for handling the queues. See Deployment for details of the deployment utility.