Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.9)
  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)

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 with Mule Enterprise Edition and contains native support for WebSphere MQ-specific features.

Note: The community JMS transport does not provide full support for WebSphere MQ and is not recommended for use with production WebSphere MQ installations.

Supported Versions

  • WMQ Transport supports the IBM MQ 8.0, 9.0 client drivers, which can be used to connect to WMQ Server versions 8.0, and 9.0.

  • WMQ 7.x is in end of life at IBM. While the connector should be backwards compatible with this version, it is not supported neither by IBM nor by MuleSoft

  • This transport is compatible with Mule 3.8 and later with IBM MQ 8 and 9. This transport was not tested on Mule 3.7 using IBM MQ 8 or 9. This configuration may work, but is not supported.

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.allclient.jar

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

  • jms.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/current/mule-wmq-ee.xsd

Using the Mule WMQ Transport

Before you run an app using the transport, ensure that your system meets the following conditions:

  • Mule Enterprise is installed.

  • A supported version of WebSphere MQ is installed (see list above).

  • the WebSphere MQ client library JARs listed above are added to the project build path.

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"
          ...
/>

*Notes:

  • Bitronix and JMS do not honor the caching connection factory and TCP connections are recreated regardless of how this factory is set.

  • In 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).

Additional configuration notes:

  • 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 use a remote queue, specify the channel with the channel attribute, and use the WebSphere MQ utility amqsget to verify that the message was received on the remote queue.

Mule configuration:

<mule xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw"
xmlns:metadata="http://www.mulesoft.org/schema/mule/metadata"
xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xmlns:test="http://www.mulesoft.org/schema/mule/test"
      xmlns:http="http://www.mulesoft.org/schema/mule/http"
      xmlns:wmq="http://www.mulesoft.org/schema/mule/ee/wmq"
      xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
      http://www.mulesoft.org/schema/mule/core/current/mule.xsd
        http://www.mulesoft.org/schema/mule/test
        http://www.mulesoft.org/schema/mule/test/current/mule-test.xsd
        http://www.mulesoft.org/schema/mule/http
        http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
        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/ee/dw
        http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd">

    <wmq:connector name="wmqconnector"
                   hostName="localhost" port="1414"
                   queueManager="QUEUE_MANAGER"
                   username="username"
                   password="password"
                   transportType="CLIENT_MQ_TCPIP"
                   specification="1.1"
                   disableTemporaryReplyToDestinations="true"
                   numberOfConsumers="1">
    </wmq:connector>
    <http:listener-config name="HTTP_Listener_Configuration" host="127.0.0.1" port="8081"/>

    <flow name="main">
        <http:listener config-ref="HTTP_Listener_Configuration" path="in" doc:name="HTTP Connector"/>
        <request-reply>
            <wmq:outbound-endpoint queue="REQUEST.QUEUE" connector-ref="wmqconnector"/>
            <wmq:inbound-endpoint queue="RESPONSE.QUEUE" connector-ref="wmqconnector"/>
        </request-reply>
        <wmq:message-info-mapping />
    </flow>

    <flow name="service">
        <wmq:inbound-endpoint queue="REQUEST.QUEUE" connector-ref="wmqconnector" doc:name="WMQ"/>
        <logger message="reached REQUEST QUEUE" level="INFO" doc:name="Logger"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
"Response OK"]]></dw:set-payload>
        </dw:transform-message>
    </flow>
</mule>

Defining WMQ XA Connector

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

<wmq:xa-connector ...>

The connector instantiates the XA Connection Factory under the hood without requiring a reference to an explicitly defined Connection Factory.

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 you use XA transactions. 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 useRemoteQueueDefinitions 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, useRemoteQueueDefinitions 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 a 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
...<wmq:connector name="wmqConnector" ...>
  <spring:property name="connectionLostTimeout" value="3000"/>
  <ee:retry-forever-policy frequency="3000" />
</wmq:connector>

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.

Using a Correlation ID

When an application invokes a request-response operation, you can use a correlation ID to correlate response messages with request messages. With WebSphere® MQ and WebSphere MQ JMS, you can correlate a response message using either a correlation ID or a message ID. In most cases, the caller lets the queue manager select a message ID and expects the application to copy the message ID into the correlation ID of the response message.

The JMSCorrelationID can be a byte[] value, a string value containing hexadecimal characters and prefixed with ID:, or an arbitrary string value that does not begin with ID:. By default, the Mule correlation ID (or any correlation ID provided) is sent to WMQ in a message that is encoded with the WebSphere format.

To preserve the provided correlation ID and avoid encoding, set the mule.wmq.encodingCorrelationId.disable system property to true:

./mule -M-Dmule.wmq.encodingCorrelationId.disable=true

Additionally, enable JMS_COMPLIANT mode on the connector:

targetClient="JMS_COMPLIANT"

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)

  • 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 Description

queueManager

The name of the QueueManager to use.

Type: string
Required: no
Default: none

hostName

The host name of the QueueManager to use.

Type: string
Required: no
Default: none

port

The port of the QueueManager to use.

Type: port number
Required: no
Default: none

temporaryModel

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

Type: string
Required: no
Default: none

ccsId

The WebSphere MQ CCS ID.

Type: string
Required: no
Default: none

transportType

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.

Type: not specified
Required: no
Default: none

channel

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

Type: string
Required: no
Default: none

propagateMQEvents

Type: boolean
Required: no
Default: none

useRemoteQueueDefinitions

When using remote queue definitions, WMQ uses the JMSReplyTo property to channel responses. When set to true this property causes 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 property is true.

Type: boolean
Required: no
Default: none

receiveExitHandler

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

Type: class name
Required: no
Default: none

receiveExitHandlerInit

An initialization parameter for the receive exit handler.

Type: class name
Required: no
Default: none

sendExitHandler

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

Type: class name
Required: no
Default: none

sendExitHandlerInit

An initialization parameter for the send exit handler.

Type: class name
Required: no
Default: none

securityExitHandler

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

Type: class name
Required: no
Default: none

securityExitHandlerInit

An initialization parameter for the security exit handler.

Type: class name
Required: no
Default: none

targetClient

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

Type: not specified
Required: no
Default: none

No Child Elements of <connector…​>

XA Connector

The WebSphere MQ connector for XA transactions.

Attributes of <xa-connector…​>

Name Description

queueManager

The name of the QueueManager to use.

Type: string
Required: no
Default: none

hostName

The host name of the QueueManager to use.

Type: string
Required: no
Default: none

port

The port of the QueueManager to use.

Type: port number
Required: no
Default: none

temporaryModel

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

Type: string
Required: no
Default: none

ccsId

The WebSphere MQ CCS ID.

Type: integer
Required: no
Default: none

transportType

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.

Type: string
Required: no
Default: none

channel

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

Type: string
Required: no
Default: none

propagateMQEvents

Propagate MQ events.

Type: boolean
Required: no
Default: none

useRemoteQueueDefinitions

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 property is true.

Type: boolean
Required: no
Default: none

receiveExitHandler

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

Type: class name
Required: no
Default: none

receiveExitHandlerInit

An initialization parameter for the receive exit handler.

Type: class name
Required: no
Default: none

sendExitHandler

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

Type: class name
Required: no
Default: none

sendExitHandlerInit

An initialization parameter for the send exit handler.

Type: class name
Required: no
Default: none

securityExitHandler

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

Type: class name
Required: no
Default: none

securityExitHandlerInit

An initialization parameter for the security exit handler.

Type: class name
Required: no
Default: none

targetClient

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

Type: not specified
Required: no
Default: none

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

No Child Elements of <xa-connector…​>

Inbound Endpoint

An endpoint on which WMQ messages are received.

Attributes of <inbound-endpoint…​>

Name Description

queue

The queue name.

Type: string
Required: yes
Default: none

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 Description

queue

The queue name.

Type: string
Required: yes
Default: none

disableTemporaryReplyToDestinations

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.

Type: boolean
Required: no
Default: none

correlationId

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. WMQ uses a 24-byte string for the correlation ID. WebSphere pads 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. By default, all message ID values start with the ID: prefix. To preserve a provided correlation ID, review the using a correlation ID provided documentation section..

Type: string
Required: no
Default: none

messageType

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.

Type: not specified
Required: no
Default: none

characterSet

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

Type: integer
Required: no
Default: none

persistentDelivery

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 has 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.

Type: boolean
Required: no
Default: none

timeToLive

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.

Type: long
Required: no
Default: none

priority

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.

Type: substitutablePriorityNumber
Required: no
Default: none

targetClient

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

Type: not specified
Required: no
Default: none

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

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.