IBM MQ SOAP listeners

An IBM MQ SOAP listener reads an incoming SOAP request from the queue specified as the destination in the URI. It checks the format of the request message and then invokes a web service using the web services infrastructure. An IBM MQ SOAP listener returns any response or error from a web service using the reply destination queue in the URI. It returns IBM MQ reports to the reply queue.

The term listener is used here in its standard web services sense. It is distinct from the standard IBM MQ listener invoked by the runmqlsr command.


Description

The Java SOAP listener is implemented as a Java class and run services using Axis 1.4. The .NET listener is a console application and runs .NET Framework 1 or .NET Framework 2 services. For .NET Framework 3 services, use the IBM MQ custom channel for Microsoft Windows Communication Foundation (WCF).

The deployment utility creates scripts to start Java or .NET SOAP listeners automatically. A SOAP Listener can be started manually using either the amqSOAPNETListener command, or by calling the SimpleJavaListener class. We can configure the IBM MQ SOAP listener to be started as an IBM MQ service by setting the -s option in the deployment utility. Alternatively, start listeners using triggering, or use the start and end listener scripts generated by the deployment utility. We can configure triggering manually, or use the -tmq and -tmp deployment options to configure triggering automatically. We can end a listener by setting the request queue to GET (DISABLED).
Table 1. Command scripts generated by the deployment utility
Web service Infrastructure UNIX and Linux systems Windows Java Windows.NET
Start listener startWMQJListener.sh startWMQJListener.cmd startWMQNListener.cmd
Stop listener endWMQJListener.sh endWMQJListener.cmd endWMQNListener.cmd
Define listener service defineWMQJListener.sh defineWMQJListener.cmd defineWMQNListener.cmd

The IBM MQ SOAP listener passes the endpointURL and soapAction fields from the SOAP message to the SOAP infrastructure. The listener invokes the service through the Web Services infrastructure and waits for the response. The listener does not validate endpointURL and soapAction. The fields are set by the IBM MQ SOAP sender from the data that is provided in the URI set by a SOAP client.

The listener creates the response message and sends it to the reply destination supplied in the request message URI. In addition, the listener sets the correlation ID in the response message according to the report option in the request message. It returns the expiry, persistence, and priority settings from the request message. The listener also sends report messages back to clients in some circumstances.

If there are format errors in the SOAP request, the listener returns a report message to the client using the reply destination queue. The queue manager also returns report messages to the client using the reply destination queue, if a report has been requested. Full report messages are written to the response queue, in response to a number of events:

  • An exception.
  • Message expiry.
  • Format of the request message is not recognized.
  • Failure of the integrity check of the MQRFH2 header.
  • The format of the main message body is not MQFMT_NONE.
  • The backout/retry threshold is exceeded while the IBM MQ SOAP listener is processing the request.

The IBM MQ SOAP sender sets MQRO_EXCEPTION_WITH_FULL_DATA and MQRO_EXPIRATION_WITH_FULL_DATA report options. As a result of the report options set by the IBM MQ SOAP sender, the report message contains the entire originating request message. The IBM MQ SOAP sender also sets the MQRO_DISCARD option, which causes the message to be discarded after a report message has been returned. If the report options do not meet your requirements, write your own senders to use different MQRO_EXCEPTION and MQRO_DISCARD report options. If the SOAP request is sent by a different sender that did not set MQRO_DISCARD, the failing message is written to the dead letter queue (DLQ).

If the listener generates a report message but fails in the process of sending the report, the report message is sent to the DLQ. Ensure that your DLQ handler handles these messages correctly.

If an error occurs when attempting to write to the dead-letter queue a message is written to the IBM MQ error log. Whether the listener continues to process more messages depends on which message persistence and transactional options are selected. If the listener is running in one-phase transactional mode and is processing a non-persistent request message, the original message is discarded. The IBM MQ SOAP listener continues to execute. If the request message is persistent the request message is backed out to the request queue and the listener exits. The request queue is set to get-inhibited to prevent an accidental triggered restart.

Syntax diagram

.NET amqwSOAPNETListener URI (.NET service)URI ( Java service)-? -aDefaultMsgIntegrity-xonePhasetwophaseHighMsgIntegrity-xonePhasetwophaseLowMsgIntegrity-xonePhasetwophasenone-d-1msecs-ipassContextownContext-n10numThreads-v-wc:\inetpub\wwwroot\-xonePhasetwophasenone-aLowMsgIntegrityJava java com.ibm.mq.soap.transport.jms.SimpleJavaListener URI (.NET service)URI ( Java service)-? -aDefaultMsgIntegrity-xonePhasetwophaseHighMsgIntegrity-xonePhasetwophaseLowMsgIntegrity-xonePhasetwophasenone-d-1msecs-ipassContextownContext-n10numThreads-v-xonePhasetwophasenone-aLowMsgIntegrity


Required parameters


Optional parameters

    -a integrityOption
    integrityOption specifies the behavior of IBM MQ SOAP listeners if it is not possible to put a failed request message on the dead-letter queue. integrityOption can take one of the following values:

      DefaultMsgIntegrity
      For non-persistent messages, the listener displays a warning message and continues to execute with the original message being discarded. For persistent messages, it displays an error message, backs out the request message so it remains on the request queue and exits. DefaultMsgIntegrity applies if the -a option is omitted, or if integrityOption is not specified.

      LowMsgIntegrity
      For both persistent and non-persistent messages, the listener displays a warning and continues to execute, discarding the message.

      HighMsgIntegrity
      For both persistent and non-persistent messages, the listener displays an error message, backs out the request message so it remains on the request queue and exits.

    The deployment utility checks for the compatibility of the -x and -a flags. If -x none is specified, then -a LowMsgIntegrity must be specified. If the flags are incompatible the deployment utility exits with an error message and with no deployment steps having been undertaken.

    -d msecs
    msecs specifies the number of milliseconds for the IBM MQ SOAP listener to stay alive if request messages have been received on any thread. If msecs is set to -1, the listener stays alive indefinitely.
    -i Context
    Context specifies whether the listeners pass identity context. Context takes the following values:

      passContext
      Set the identity context of the original request message into the response message. The SOAP listener checks that it has authority to save the context from the request queue and to pass it to the response queue. It makes the checks at run time when opening the request queue to save context, and the response queue to pass context. If it does not have the required authority, or the MQOPEN call fails, and the response message is not processed. The response message is put on the dead-letter queue with the dead-letter header containing the return code from the failed MQOPEN. The listener then continues to process subsequent incoming messages as normal.

      ownContext
      The SOAP listener does not pass context. The returned context reflects the user ID under which the listener is running rather than the user ID which created the original request message.

    The fields in the origin context are set by the queue manager, and not by the SOAP listener.

    -n numThreads
    numThreads specifies the number of threads in the generated startup scripts for the IBM MQ SOAP listener. The default is 10. Consider increasing this number if we have high message throughput.
    -v
    -v sets verbose output from external commands. Error messages are always displayed. Use -v to output commands that we can tailor to create customized deployment scripts.
    -w serviceDirectory
    serviceDirectory is the directory containing the web service.
    -x transactionality
    transactionality specifies the type of transactional control for the listener. transactionality can be set to one of the following values:

      onePhase
      IBM MQ one-phase support is used. If the system fails during processing, the request message is redelivered to the application. IBM MQ transactions ensure that the response messages are written exactly once.

      twoPhase
      Two-phase support is used. If the service is written appropriately the message is delivered exactly once, coordinated with other resources, within a single committed execution of the service. This option applies to server bindings connections only.

      none
      No transactional support. If the system fails during processing, the request message can be lost, even if persistent. The service might or might not have executed, and response, report or dead-letter messages might or might not be written.

    The deployment utility checks for the compatibility of the -x and -a flags. See the description of the -a flag for details.


.NET Example

amqwSOAPNETlistener
-u "jms:/queue?destination=myQ&connectionFactory=()
&targetService=myService&initialContextFactory=com.ibm.mq.jms.Nojndi"
-w C:/wmqsoap/demos
-n 20


Java Example

java com.ibm.mq.soap.transport.jms.SimpleJavaListener
-u "jms:/queue?destination=myQ&connectionFactory=()
&initialContextFactory=com.ibm.mq.jms.Nojndi"
-n 20