Advanced Listener for IBM MQ Functionality


Support for Request/Reply Scenarios

The Listener for IBM MQ provides support for a synchronous request/reply scenario. In this case the remote procedure call usually has both INPUT and OUTPUT parameters, or at least one INOUT. A request/reply scenario is automatically detected by the Listener for IBM MQ if the MQ message specifies the ReplyToQueue field. Also, if the property entirex.wmqbridge.check.msgtype has been set, the message type must be "MQMT_REQUEST".

The correlationId of the reply is set to the correlationId of the request if the report field of the request has the flag MQRO_PASS_CORREL_ID set. Otherwise the correlationId of the reply is set to the messageId of the request.

The messageId of the reply is set to the messageId of the request if the report field of the request has the flag MQRO_PASS_MSG_ID set. Otherwise a new messageId is created.

Character Encoding Issues

If the payload of the MQ message is in XML format (property entirex.bridge.xmm has been set), the Listener for IBM MQ converts the XML payload to an RPC request, using the default platform encoding of the Java virtual machine. If the Listener for IBM MQ sends back a reply message, the XML payload of this message will be UTF-8 encoded. A different encoding can be used by setting the property entirex.bridge.xml.encoding.

If the payload of the MQ message is of type text (property entirex.bridge.idl has been set), the Listener for IBM MQ converts the payload to an RPC request, using the default platform encoding of the Java virtual machine. If the Listener for IBM MQ sends back a reply message, the Listener converts the payload of the message to the encoding specified by the CCSID (Coded Character Set IDentification) of the MQ queue manager.

Note:
The default platform encoding of the JVM can be changed by setting the system property file.encoding in the startup script of the Listener.

User Exit for Message Processing

IBM® MQ does not have a clearly defined message layout, it is basically a stream of bytes. In general it is up to the MQ application to know the exact semantics of an MQ message. This might include application-specific headers and formatting rules. The Listener for IBM MQ supports a general but simplified model of message processing.

To better handle application specific message layout details, a user exit (or callback routine) can be used. The user exit works on the IBM® MQ Java representation of an MQ message (class com.ibm.mq.MQMessage) and can change the MQ message. The user exit gets control:

  1. after an MQ message has been read from an MQ queue and before it is processed by the Listener for IBM MQ

  2. after an MQ message has been constructed by the Listener for IBM MQ and before the message is put to the MQ queue.

The user exit can be used, for example, for an application-specific processing of the MQRFH, MQRFH2 or even custom headers.

To enable a user exit, use the property entirex.wmqbridge.userexit to specify the class name of the user exit implementation. The class will be loaded using the standard classpath. You can specify a separate classpath with the property entirex.wmqbridge.userexit.classpath. Note that for the classpath a file or HTTP URL must be specified. Your user exit class must implement the Java interface com.softwareag.entirex.rpcbridge.wmqBridgeExit. This Java interface has the following methods:

/**
 ** This method is called after the message has been created by the 
 ** WMQBridge and before the message is sent to an MQ queue (MQPUT).
 ** The Message object and/or the MessageOptions object can be changed.
 **
 ** @param msg The MQ message object.
 ** @param pmo The MQPutMessageOptions object.
 **/
public void beforePut(com.ibm.mq.MQMessage msg, com.ibm.mq.MQPutMessageOptions pmo);
/**
 ** This method is called before a message is retrieved from an MQ 
 ** queue (MQGET). The MessageOptions object can be changed.
 **
 ** @param gmo The MQGetMessageOptions object.
 **/
public void beforeGet(com.ibm.mq.MQGetMessageOptions gmo);
/**
 ** This method is called after a message has been retrieved from an 
 ** MQ queue (MQGET) and before the message will be processed by the 
 *  WMQBridge.
 ** The Message object can be changed.
 **
 ** @param msg The MQ message object.
 **/
public void afterGet(com.ibm.mq.MQMessage msg);

Transactional Behavior

The Listener for IBM MQ always works transactionally. A message is retrieved from the queue and then passed to the RPC server application. If no error occurs, the message is committed by the Listener for IBM MQ. If the call to the RPC server is not successful, the call is retried as specified by properties entirex.server.retrycycles and entirex.bridge.retryinterval. If all retry attempts fail, the message is rolled back and the Listener for IBM MQ terminates. If a dead-letter queue has been specified by the property entirex.server.deadletterqueue, the message will be put to that queue and committed, and the Listener will not stop.