Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.4)
  3. Reference
  4. Transports Reference

  5. Mule WMQ Transport Reference

Mule WMQ Transport Reference

Enterprise

The Mule Enterprise transport for IBM® WebSphere® MQ (Mule WMQ transport) provides the following functionality:

  • Bi-directional request-response messaging between WebSphere MQ and Mule JMS using native MQ point-to-point.

  • Synchronous and asynchronous request-response communications using JMSReplyTo.

  • Support for local, multi-resource, and XA transactions

  • Support for native MQ message types

  • WebSphere MQ-specific configuration syntax that removes the complexity of MQ configuration

  • Supports async request-response messaging pattern transparently in both JMS and native MQ message types

  • Support for connection retry policies (self-healing) with or without transactions

  • Support for IBM-specific headers

  • JNDI destination support including JNDI connections

  • Per endpoint control over target clients (native or JMS compliant)

  • Works with WMQ 7.0, 7.1, and 7.5

This page describes how to configure and use this transport and its connector. It assumes that you already understand how to configure and use WebSphere MQ. For complete information on WebSphere MQ, refer to the WebSphere MQ Information Center.

The Mule WMQ transport is available only with Mule Enterprise Edition version 1.6 or later and, as of 2.2, contains many critical performance and reliability improvements as well as native support for WebSphere MQ-specific features. Note that the community JMS transport does not provide full support for WebSphere MQ and is not recommended for use with production WebSphere MQ installations.

Setting Up the Mule WMQ Transport

Before you can use the Mule WMQ transport, you must copy the following JARs from the java/lib directory under your WebSphere MQ home directory into the lib/user directory under your Mule home directory:

  • com.ibm.mq.jar

  • com.ibm.mqetclient.jar (if using Transactions)

  • com.ibm.mq.jmqi.jar

  • com.ibm.mqjms.jar

  • dhbcore.jar

Additionally, if you are using local bindings (transportType="BINDINGS_MQ"), you must set the following environment variable:

export LD_LIBRARY_PATH=/opt/mqm/java/lib

Set this variable to the location of the Java library directory that shipped with the WebSphere MQ server installation. For more information about the bindings types, see the WebSphere MQ documentation.

Namespace and Syntax

XML namespace:

xmlns:wmq="http://www.mulesoft.org/schema/mule/ee/wmq"

XML Schema Location:

http://www.mulesoft.org/schema/mule/ee/wmq
http://www.mulesoft.org/schema/mule/ee/wmq/3.4/mule-wmq-ee.xsd

Using the Mule WMQ Transport

By default, messages sent from Mule to WebSphere MQ are sent in native format, and JMS (RFH2) headers are suppressed. This configuration is applied transparently to the configuration below by the connector appending a parameter to the WebSphere MQ destination URI (?targetClient=1). To force JMS behavior on the receiving WebSphere MQ (that is, to use non-native format), use the following attribute setting in the WMQ connector declaration:

<wmq:connector name="..."
          ...
     targetClient="JMS_COMPLIANT"
          ...
/>

Note: The targetClient attribute must be set to JMS_COMPLIANT when the message payload is an object.

The following configuration example configures a flow named test that performs request-reply processing. It picks up messages from the native WebSphere MQ endpoint (wmq://REQUEST.QUEUE) and forwards them to another native WebSphere MQ endpoint, wmq://RESPONSE.QUEUE. The Responder flow waits while Mule processes the messages asynchronously and appends the string RESPONSE OK when it receives messages on the response queue. All JMS semantics apply, and settings such as replyTo and QoS properties are read from the message properties, or defaults are used (according to the JMS specification).

Note the following additional points about the configuration:

  • The wmq URI scheme for endpoints indicates that the WebSphere MQ transport should be used.

  • The queueManager property in the WMQ connector declaration matches the WebSphere MQ QueueManager set up previously.

  • The local queues REQUEST.QUEUE and RESPONSE.QUEUE were set up previously using the runmqsc utility. If you were running on a remote queue, you could specify the channel with the channel attribute.

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:wmq="http://www.mulesoft.org/schema/mule/ee/wmq" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:spring="http://www.springframework.org/schema/beans" version="EE-3.3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="
http://www.mulesoft.org/schema/mule/ee/wmq http://www.mulesoft.org/schema/mule/ee/wmq/current/mule-wmq-ee.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd ">

   <wmq:connector name="wmqConnector"
                 hostName="winter" port="1414"
                 queueManager="HELLO.QMGR"
                 transportType="CLIENT_MQ_TCPIP"
                 specification="1.1"
                 disableTemporaryReplyToDestinations="true"
                 username=""
                 password=""
                 numberOfConsumers="1">
    </wmq:connector>

    <flow name="test">
        <wmq:inbound-endpoint queue="REQUEST.QUEUE" doc:name="WMQ"/>
        <test:component/>
        <wmq:outbound-endpoint queue="MIDDLE.QUEUE"/>
          <reply-to address="wmq://RESPONSE.QUEUE"/>
          <wmq:message-info-mapping/>
    </flow>

    <flow name="responder">
    	<wmq:inbound-endpoint queue="MIDDLE.QUEUE"/>
      	<test:component appendString=" RESPONSE OK"/>
    </flow>
</mule>

If you were running on a remote queue, you could use the WebSphere MQ utility amqsget to verify that the message was received on the remote queue.

Defining WMQ XA Connector

Defining a Connection Factory via Spring is optional, you can simply define WMQ XA-enabled connector as follows:

<wmq:xa-connector ...>

It instantiates the XA Connection Factory under the hood, no reference to an explicitly defined Connection Factory is required.

However, in some situations you need to define a Connection Factory explicitly and then reference it in the connector definition. If that is the case, then the Connection Factory class has to be MQXAConnectionFactory, if XA transactions are used. Then WMQ connector has to reference this bean, for example:

<spring:bean id="mqXAFactory" class="com.ibm.mq.jms.MQXAConnectionFactory">
...
</spring:bean>

<wmq:xa-connector ... connectionFactory-ref="mqXAFactory">

Inbound Message Handling

The inbound messages are received by the connector and delivered to the component. If the useRemoteQueueDefinitons connector attribute is not set to true and the inbound message type is MQMT_REQUEST, the message returned by the component is sent to the queue specified in the JMSReplyTo property of the original message. However, if the outbound WebSphere MQ endpoint exists in the component, it overrides the replyto handler functionality. By default, useRemoteQueueDefinitons is set to false.

inbound flow

Outbound Message Handling

The outbound endpoint behavior depends on the WebSphere MQ message type. If the message type is MQMT_REPLY or MQMT_DATAGRAM, other properties copy over from the original message and the message dispatches to the queue.

If the message type is MQMT_REQUEST, the connector checks for the existence of the JMSReplyTo setting on the message. If it is not set, the connector creates the temporary queue. If the endpoint is synchronous, the connector waits for a response. The timeout can be set using the responseTimeout setting. If a response is received by the connector, it’s returned by the component.

outbound flow

Retrieving the Connection Factory from JNDI

To support the case where a JNDI registry has been configured to store the connection factory, the connector declaration should include the following parameters. This is the same as the regular JMS transport.

<wmq:connector ...
     jndiInitialFactory="com.sun.jndi.ldap.LdapCtxFactory"
     jndiProviderUrl="ldap://localhost:10389/"
     connectionFactoryJndiName="cn=ConnectionFactory,dc=example,dc=com"

Transformers

The WMQ transport provides a transformer for converting a com.ibm.jms.JMSMessage or sub-type into an object by extracting the message payload. It also provides a transformer to convert the object back to a message. You use the <message-to-object-transformer> and <object-to-message-transformer> elements to configure these transformers. Note that object payloads work only when targetClient is set to JMS_COMPLIANT.

Transactions

You can configure single-resource (local), multi-resource, and XA transactions on WMQ transport endpoints using the standard transaction configuration elements. For example, you might configure an XA transaction on an outbound endpoint as follows:

<jbossts:transaction-manager/>

<wmq:xa-connector name="wmqConnector" hostName="winter" ...>
...
     <wmq:outbound-endpoint queue="out">
       <xa-transaction action="ALWAYS_BEGIN"/>
     </wmq:outbound-endpoint
...

Note that if you are using XA transactions, and you are connecting to a queue that requires the queue manager to connect to a remote resource, you must use the extended transactional client from WebSphere MQ (mqetclient.jar). For more information, see What is an extended transactional client? in the WebSphere MQ 7 help.

For more information on using transactions, see Transaction Management.

Configuring Retry Policies

The WMQ transport supports retry policies. You can configure the timeout value on the connector as follows:

<wmq:connector name="wmqConnector" ...>
  <spring:property name="connectionLostTimeout" value="3000"/>
  <ee:retry-forever-policy frequency="3000" />
</wmq:connector>

The example that ships with the Mule WMQ transport allows you to test retry policies. For complete information, see the readme file in the WMQ distribution.

Known Limitations

Following are the features that have not been fully tested with the Mule WMQ transport or are not supported:

  • Remote queues (tested only in previous releases)

  • Exit handler support (not tested)

  • Topics (not tested)

  • MQMT_REPORT message type support (not supported)

  • Native WMQ connection pool support (not supported)

  • Data compression over channels for performance throughput gain (not supported)

Configuration Reference

The following tables describe the configuration for:

  • wmq:connector

  • wmq:xa-connector

  • wmq:inbound-endpoint

  • wmq:outbound-endpoint

  • wmq:endpoint

Connector

The default WebSphere MQ connector.

Attributes of <connector…​>

Name Type Required Default Description

queueManager

string

no

The name of the QueueManager to use.

hostName

string

no

The host name of the QueueManager to use.

port

port number

no

The port of the QueueManager to use.

temporaryModel

string

no

The temporary destination model to use when creating temporary destinations from this connector.

ccsId

integer

no

The WebSphere MQ CCS ID.

transportType

no

Whether to use a local binding or client/server TCP binding. Possible values are: BINDINGS_MQ, CLIENT_MQ_TCPIP, DIRECT_HTTP, DIRECT_TCPIP, and MQJD.

channel

string

no

The name of the channel used to communicate with the QueueManager.

propagateMQEvents

boolean

no

useRemoteQueueDefinitions

boolean

no

When using remote queue definitions, WMQ uses the JMSReplyTo property to channel responses. When set to true this property will cause Mule to ignore ReplyTo queue destinations and not interfere with WMQ’s remote queue mechanism. By default this is set to false. This also means that by using WMQ’s remote queue definitions it is not possible to use some of Mule’s request/response patterns when this properrty is true.

receiveExitHandler

class name

no

The fully qualified class name of the receive exit handler implementation.

receiveExitHandlerInit

class name

no

An initialization parameter for the receive exit handler.

sendExitHandler

class name

no

The fully qualified class name of the send exit handler implementation.

sendExitHandlerInit

class name

no

An initialization parameter for the send exit handler.

securityExitHandler

class name

no

The fully qualified class name of the security exit handler implementation.

securityExitHandlerInit

class name

no

An initialization parameter for the security exit handler.

targetClient

no

Specifies whether this is in JMS or non-JMS format. Possible values are: JMS_COMPLIANT or NONJMS_MQ (default).

Child Elements of <connector…​>

Name Cardinality Description

Xa connector

The WebSphere MQ connector for XA transactions.

Attributes of <xa-connector…​>

Name Type Required Default Description

queueManager

string

no

The name of the QueueManager to use.

hostName

string

no

The host name of the QueueManager to use.

port

port number

no

The port of the QueueManager to use.

temporaryModel

string

no

The temporary destination model to use when creating temporary destinations from this connector.

ccsId

integer

no

The WebSphere MQ CCS ID.

transportType

no

Whether to use a local binding or client/server TCP binding. Possible values are: BINDINGS_MQ, CLIENT_MQ_TCPIP, DIRECT_HTTP, DIRECT_TCPIP, and MQJD.

channel

string

no

The name of the channel used to communicate with the QueueManager.

propagateMQEvents

boolean

no

useRemoteQueueDefinitions

boolean

no

When using remote queue definitions, WMQ uses the JMSReplyTo property to channel responses. When set to true this property will cause Mule to ignore ReplyTo queue destinations and not interfere with WMQ’s remote queue mechanism. By default this is set to false. This also means that by using WMQ’s remote queue definitions it is not possible to use some of Mule’s request/response patterns when this properrty is true.

receiveExitHandler

class name

no

The fully qualified class name of the receive exit handler implementation.

receiveExitHandlerInit

class name

no

An initialization parameter for the receive exit handler.

sendExitHandler

class name

no

The fully qualified class name of the send exit handler implementation.

sendExitHandlerInit

class name

no

An initialization parameter for the send exit handler.

securityExitHandler

class name

no

The fully qualified class name of the security exit handler implementation.

securityExitHandlerInit

class name

no

An initialization parameter for the security exit handler.

targetClient

no

Specifies whether this is in JMS or non-JMS format. Possible values are: JMS_COMPLIANT or NONJMS_MQ (default).

Child Elements of <xa-connector…​>

Name Cardinality Description

Inbound endpoint

An endpoint on which WMQ messages are received.

Attributes of <inbound-endpoint…​>

Name Type Required Default Description

queue

string

yes

The queue name.

Child Elements of <inbound-endpoint…​>

Name Cardinality Description

mule:response

0..1

mule:abstract-redelivery-policy

0..1

mule:abstract-transaction

0..1

mule:abstract-xa-transaction

0..1

mule:abstract-security-filter

0..1

mule:abstract-filter

0..1

selector

0..1

Outbound endpoint

An endpoint to which WMQ messages are sent.

Attributes of <outbound-endpoint…​>

Name Type Required Default Description

queue

string

yes

The queue name.

disableTemporaryReplyToDestinations

boolean

no

If this is set to false (the default), when Mule performs request/response calls a temporary destination will automatically be set up to receive a response from the remote WMQ call.

correlationId

string

no

A client can use the correlation ID header field to link one message to another. A typical use case is to link a response message with its request message. The CorrelationID must be a 24-byte String. WebSphere will pad shorter values with zeroes so that the fixed length is always 24 bytes. Because each message sent by a WMQ provider is assigned a message ID value, it is convenient to link messages via the message ID. All message ID values must start with the 'ID:' prefix.

messageType

no

Indicates the message type. Each of the message types have specific behavior associated with them. The following message types are defined: MQMT_REQUEST: The message requires a reply. Specify the name of the reply queue using the <ReplyTo> element of outbound routers. Mule handles the underlying configuration. MQMT_DATAGRAM: The message does not require a reply. MQMT_REPLY: The message is the reply to an earlier request message (MQMT_REQUEST). The message must be sent to the queue indicated by the <ReplyTo> configured on the outbound router. Mule automatically configures the request to control how to set the MessageId and CorrelationId of the reply. MQMT_REPORT: The message is reporting on some expected or unexpected occurrence, usually related to some other message (for example, a request message was received that contained data that was not valid). Sends the message to the queue indicated by the <ReplyTo> configuration of the message descriptor of the original message.

characterSet

integer

no

If set, this property overrides the coded character set property of the destination queue or topic.

persistentDelivery

boolean

no

If set to true, the JMS provider logs the message to stable storage as it is sent so that it can be recovered if delivery is unsuccessful. A client marks a message as persistent if the application will have problems if the message is lost in transit. A client marks a message as non-persistent if an occasional lost message is tolerable. Clients use delivery mode to tell a JMS provider how to balance message transport reliability/throughput. Delivery mode only covers the transport of the message to its destination. Retention of a message at the destination until its receipt is acknowledged is not guaranteed by a PERSISTENT delivery mode. Clients should assume that message retention policies are set administratively. Message retention policy governs the reliability of message delivery from destination to message consumer. For example, if a client’s message storage space is exhausted, some messages as defined by a site-specific message retention policy may be dropped. A message is guaranteed to be delivered once and only once by a JMS provider if the delivery mode of the message is persistent and if the destination has a sufficient message retention policy.

timeToLive

long

no

Define the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system. Time to live is set to zero (forever) by default.

priority

substitutablePriorityNumber

no

Sets the message priority. JMS defines a ten-level priority value with 0 as the lowest priority and 9 as the highest. In addition, clients should consider priorities 0-4 as gradations of normal priority and priorities 5-9 as gradations of expedited priority. JMS does not require that a provider strictly implement priority ordering of messages. However, it should do its best to deliver expedited messages ahead of normal messages.

targetClient

no

Specifies whether this is in JMS or non-JMS format. Possible values are: JMS_COMPLIANT or NONJMS_MQ (default).

Child Elements of <outbound-endpoint…​>

Name Cardinality Description

mule:response

0..1

mule:abstract-redelivery-policy

0..1

mule:abstract-transaction

0..1

mule:abstract-xa-transaction

0..1

mule:abstract-security-filter

0..1

mule:abstract-filter

0..1

selector

0..1

Endpoint

A global WMQ endpoint definition. Note that global endpoints are like endpoint factories from which new endpoints can be created. As such this endpoint has a union of inbound and outbound endpoint properties. Depending on how this endpoint is used the unneeded properties will ignored.

Attributes of <endpoint…​>

Name Type Required Default Description

queue

string

yes

The queue name.

disableTemporaryReplyToDestinations

boolean

no

If this is set to false (the default), when Mule performs request/response calls a temporary destination will automatically be set up to receive a response from the remote WMQ call.

correlationId

string

no

A client can use the correlation ID header field to link one message to another. A typical use case is to link a response message with its request message. The CorrelationID must be a 24-byte String. WebSphere will pad shorter values with zeroes so that the fixed length is always 24 bytes. Because each message sent by a WMQ provider is assigned a message ID value, it is convenient to link messages via the message ID. All message ID values must start with the 'ID:' prefix.

messageType

no

Indicates the message type. Each of the message types have specific behavior associated with them. The following message types are defined: MQMT_REQUEST: The message requires a reply. Specify the name of the reply queue using the <ReplyTo> element of outbound routers. Mule handles the underlying configuration. MQMT_DATAGRAM: The message does not require a reply. MQMT_REPLY: The message is the reply to an earlier request message (MQMT_REQUEST). The message must be sent to the queue indicated by the <ReplyTo> configured on the outbound router. Mule automatically configures the request to control how to set the MessageId and CorrelationId of the reply. MQMT_REPORT: The message is reporting on some expected or unexpected occurrence, usually related to some other message (for example, a request message was received that contained data that was not valid). Sends the message to the queue indicated by the <ReplyTo> configuration of the message descriptor of the original message.

characterSet

integer

no

If set, this property overrides the coded character set property of the destination queue or topic.

persistentDelivery

boolean

no

If set to true, the JMS provider logs the message to stable storage as it is sent so that it can be recovered if delivery is unsuccessful. A client marks a message as persistent if the application will have problems if the message is lost in transit. A client marks a message as non-persistent if an occasional lost message is tolerable. Clients use delivery mode to tell a JMS provider how to balance message transport reliability/throughput. Delivery mode only covers the transport of the message to its destination. Retention of a message at the destination until its receipt is acknowledged is not guaranteed by a PERSISTENT delivery mode. Clients should assume that message retention policies are set administratively. Message retention policy governs the reliability of message delivery from destination to message consumer. For example, if a client’s message storage space is exhausted, some messages as defined by a site-specific message retention policy may be dropped. A message is guaranteed to be delivered once and only once by a JMS provider if the delivery mode of the message is persistent and if the destination has a sufficient message retention policy.

timeToLive

long

no

Define the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system. Time to live is set to zero (forever) by default.

priority

substitutablePriorityNumber

no

Sets the message priority. JMS defines a ten-level priority value with 0 as the lowest priority and 9 as the highest. In addition, clients should consider priorities 0-4 as gradations of normal priority and priorities 5-9 as gradations of expedited priority. JMS does not require that a provider strictly implement priority ordering of messages. However, it should do its best to deliver expedited messages ahead of normal messages.

targetClient

no

Specifies whether this is in JMS or non-JMS format. Possible values are: JMS_COMPLIANT or NONJMS_MQ (default).

Child Elements of <endpoint…​>

Name Cardinality Description

mule:response

0..1

mule:abstract-redelivery-policy

0..1

mule:abstract-transaction

0..1

mule:abstract-xa-transaction

0..1

mule:abstract-security-filter

0..1

mule:abstract-filter

0..1

selector

0..1

Also supported:

  • Message To Object Transformer converts a com.ibm.jms.JMSMessage or sub-type into an object by extracting the message payload.

  • Object To Message Transformer converts an object back into a com.ibm.jms.JMSMessage.

  • Transactions allow a series of operations to be grouped together so that they can be rolled back if a failure occurs. Set the action (such as ALWAYS_BEGIN or JOIN_IF_POSSIBLE) and the timeout setting for the transaction.