---
schema_version: "1"
id: 483427de821a0a5e95611253aa7581c88914135cd22c2521eca6f161676f7026
title: IBM MQ Connector 2.0
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/ibm-mq-connector/latest/index.md
canonical_url: https://docs.mulesoft.com/ibm-mq-connector/latest/
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 0ba16afe6b7fbddfdca211f221fccc092c4e89979ddc56a4b20d03265f782daa
description: MuleSoft Documentation Site
release: "2.0"
latest: true
---
---
product: IBM MQ Connector
version: 2.0
is-latest-version: true
---

# IBM MQ Connector 2.0

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Connector for IBM MQ (IBM MQ Connector) enables an app to do messaging to a IBM MQ Broker
using the IBM MQ JMS implementation. The main features include:

- Pub/Sub pattern support on any given destination.

- Listen/Reply pattern support on any given destination.

- Publish-Consume pattern support on any given destination, with fixed or temporary reply Queue.

- Non-blocking publishing and consumption of messages.

Release Notes: [IBM MQ Connector Release Notes](https://docs.mulesoft.com/release-notes/connector/connector-ibm-mq)  
Exchange: [IBM MQ Connector](https://www.mulesoft.com/exchange/com.mulesoft.connectors/mule-ibm-mq-connector/)

## Before You Begin

IBM MQ Connector 2.0 uses the Jakarta Messaging (`jakarta.jms`) namespace instead of `javax.jms`,
and it replaces the `enableXa` attribute with a separate XA connection element. If you are upgrading
from version 1.x, see [Upgrading and Migrating IBM MQ Connector](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-connector-upgrade-migrate).

## Connection Types

IBM MQ Connector provides two connection types. In Studio, select the connection type in the
**Connection** field of the global element configuration:

- **IBM MQ Connection** (`<ibm-mq:ibm-mq-connection>`)  
  Use this connection type for local transactions and non-transactional messaging.

- **IBM MQ XA Connection** (`<ibm-mq:ibm-mq-xa-connection>`)  
  Use this connection type to create or join XA transactions that span multiple resources. See
  [Handling Transactions in IBM MQ](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-transactions).

Both connection types accept the same connection parameters. The **IBM MQ XA Connection** type adds
the **Min Pool Size**, **Max Pool Size**, and **Max Idle Seconds** XA connection pool parameters.
For a full list of parameters for each connection type, see
[IBM MQ Connection](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-xml-ref#config_connection) and
[IBM MQ XA Connection](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-xml-ref#config_xa_connection).

## Connection Mode

When creating the IBM configuration, choose is the
[IBM connection mode](https://www.ibm.com/docs/en/ibm-mq/9.0.x?topic=SSFKSJ_9.0.0/com.ibm.mq.dev.doc/q031720_.html)
to use.

As of IBM MQ 8, there are only two available connection modes, **Client** and **Binding**.

### Client Connection Mode

The client connection mode lets you connect to the IBM MQ Queue Manager running in the same system
that is being run the Mule Application or in other system. In both cases the IBM MQ Connector will
connect to the IBM MQ Queue Manager over TCP/IP.

For this connection mode are available the following configurations:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p>Host</p></td><td><p>TRUE</p></td><td></td><td><p>Host containing the IBM MQ Broker.</p></td></tr><tr><td><p>Port</p></td><td><p>FALSE</p></td><td><p>1414</p></td><td><p>Queue manager listener port.</p></td></tr><tr><td><p>Queue Manager</p></td><td><p>FALSE</p></td><td></td><td><p>The queue manager used when selecting a channel definition.</p></td></tr><tr><td><p>Channel</p></td><td><p>FALSE</p></td><td></td><td><p>Name of the channel to connect to.</p></td></tr><tr><td><p>Connection Name List</p></td><td><p>FALSE</p></td><td></td><td><p>Hosts to which the client attempts to reconnect after its connection is broken.<br>The connection name list is a comma separated list of host and IP port pairs.<br><strong>Example:</strong> <code>0.0.0.0(1414),somehost.domain.com(1415)</code></p></td></tr><tr><td><p>Client Reconnect Options</p></td><td><p>FALSE</p></td><td><p>RECONNECT</p></td><td><p>Controls the reconnection behavior for the IBM MQ client. Applies when <strong>Connection Name List</strong> or a CCDT is configured.</p></td></tr><tr><td><p>Client Reconnect Timeout</p></td><td><p>FALSE</p></td><td><p>20</p></td><td><p>The maximum time, in seconds, that the client spends attempting to reconnect. Applies when <strong>Connection Name List</strong> is configured with multiple hosts.</p></td></tr></tbody></table>

For descriptions of all client connection mode parameters, see [Client](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-xml-ref#client).

![Client Connection](/mulesoft/current/en-us/ibm-mq-connector/latest/_images/ibm-mq-client-connection-mode.png)

Figure 1. Client Connection Configuration on Studio

Client Connection Configuration on XML

```xml
<ibm-mq:config name="IBM_MQ_Config">
 <ibm-mq:ibm-mq-connection >
   <ibm-mq:connection-mode >
	 	<ibm-mq:client host="0.0.0.0" port="1414" queueManager="QM1" channel="DEV.ADMIN.SVRCONN" />
		</ibm-mq:connection-mode>
	</ibm-mq:ibm-mq-connection>
</ibm-mq:config>
```

### Binding Connection Mode

The binding connection mode connects automatically to the IBM MQ broker running in the same system.

The unique parameter that is optionally configurable is the Queue Manager to connect to. If the IBM
MQ broker has a default Queue Manager, this configuration is not required.

![Binding Connection](/mulesoft/current/en-us/ibm-mq-connector/latest/_images/ibm-mq-binding-connection-mode.png)

Figure 2. Binding Connection Configuration on Studio

Binding Connection Configuration on XML

```xml
<ibm-mq:config name="IBM_MQ_Config">
  <ibm-mq:ibm-mq-connection >
    <ibm-mq:connection-mode >
      <ibm-mq:binding queueManager="QM1" />
    </ibm-mq:connection-mode>
  </ibm-mq:ibm-mq-connection>
</ibm-mq:config>
```

## Define Global Defaults

The IBM MQ `config` allows you to define multiple parameters to use as a default while consuming or
publishing messages. This way, you can define a global default behavior for all the operations
associated with the config and override each parameter only in the operations that require a custom
behavior.

For example, we can define a default `selector` behavior when consuming a Message in any of the
operations that are associated to this config, and also a default.

```xml
<ibm-mq:config name="IBM_MQ_Config">
  <ibm-mq:ibm-mq-connection/>
  <ibm-mq:consumer-config selector="JMSType = `INVOICE`"/>
  <ibm-mq:producer-config timeToLive="60000"/>
</ibm-mq:config>
```

In this case, every consume or listener operation associated with this configuration uses the
`selector` by default, while every time a publish or publish-consume occurs, the outgoing message
has a TTL of 60 seconds.

All of these properties can be overridden at operation level when required. To publish a message
with a shorter TTL, use this example configuration that overrides the parameter:

```xml
<ibm-mq:publish config-ref="IBM_MQ_Config" timeToLive="10000"/>
```

## Select the JMS Spec

The main common parameter is the JMS specification used to select between all the supported
specifications, which are 2.0 and 1.1. This specification must be supported by the broker
implementation associated to this connection, otherwise the connection fails.

> [!WARNING] Features available only in JMS 2.0 won’t work with any other specification.

## Provide Credentials For Authentication

To establish an authenticated connection, you need to configure the username and password in the
connection element:

```xml
<ibm-mq:config name="IBM_MQ_Config">
	<ibm-mq:ibm-mq-connection username="<username>" password="<password>" >
		<ibm-mq:connection-mode >
			<ibm-mq:client
			host="0.0.0.0"
			port="1414"
			queueManager="QM1"
			channel="DEV.ADMIN.SVRCONN" />
		</ibm-mq:connection-mode>
	</ibm-mq:ibm-mq-connection>
</ibm-mq:config>
```

## Configure Connections Caching

To connect with a broker and execute the required operations, the JMS connector creates multiple
sessions, consumers, and producers that can be cached and reused to increase the performance of the
application. Because of this capability, the IBM MQ connector allows you to configure which caching
strategy to use when creating new connections, caching by default both consumers and producers, and
preserving as many instances as possible in memory at the same time.

Customizing the cache configuration can be done directly in the connection declaration:

```xml
<ibm-mq:config name="IBM_MQ_Config">
  <ibm-mq:ibm-mq-connection>
    <ibm-mq:caching-strategy>
      <ibm-mq:default-caching sessionCacheSize="100" consumersCache="false" producersCache="true"/>
    </ibm-mq:caching-strategy>
  </ibm-mq:ibm-mq-connection>
</ibm-mq:config>
```

In Studio, configure these values in the **Caching strategy** field of the connection. For parameter
descriptions, see [Default Caching](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-xml-ref#default-caching).

## Identify the Connection Client

The client identifier associates a connection and its objects with a state maintained on behalf of
the client by a provider, and it is **mandatory** for identifying an unshared durable subscription.

```xml
<ibm-mq:config name="IBM_MQ_Config">
  <ibm-mq:ibm-mq-connection clientId="${env.clientId}"/>
</ibm-mq:config>
```

> [!WARNING] By definition, the client state identified by a `clientId` can be "in use" by only one
> connection at a time.

## Set Up the Connection Required Libraries

**Important:** No matter what type of connection you are using, you always need to configure a
library containing the JMS client implementation, since the connector is not bound to any particular
implementation.

### IBM MQ External Libraries

To use IBM MQ Connector, configure the external IBM MQ library. The library must provide the
`com.ibm.mq.MQException` class, which both the Jakarta Messaging and the legacy `javax.jms` IBM MQ
client libraries ship.

> [!TIP] Use the IBM MQ Jakarta client library.

Version 2.0 uses the Jakarta Messaging (`jakarta.jms`) namespace, so the recommended library is
`com.ibm.mq.jakarta.client`:

```xml
<dependency>
    <groupId>com.ibm.mq</groupId>
    <artifactId>com.ibm.mq.jakarta.client</artifactId>
    <version>9.4.5.1</version>
</dependency>
```

### Support for the Legacy javax.jms Client Library

If your application ships the legacy `com.ibm.mq.allclient` library instead, the connector detects
it at startup and wraps it so that it exposes a `jakarta.jms` connection factory. This support is
provided only for backward compatibility, and it has these limitations:

- The connector logs a warning at startup and a message on the first successful connection test that
  recommends switching to the Jakarta client library.

- Connection failure messages are suffixed with `[shim:javax-fallback]`.

- Code that casts directly to IBM MQ-specific subclasses doesn’t work through the wrapper.

To get full support, use the `com.ibm.mq.jakarta.client` library.

## See Also

- [Upgrading and Migrating IBM MQ Connector](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-connector-upgrade-migrate)

- [Consume Messages](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-consume)

- [Publish Messages](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-publish)

- [Listen For New Messages](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-listener)

- [Listen For A Reply](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-publish-consume)

- [Handle Message Acknowledgement](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-ack)

- [Handle Transactions in IBM MQ](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-transactions)

- [Tune For Performance](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-performance)

- [Connector Reference](https://docs.mulesoft.com/ibm-mq-connector/latest/ibm-mq-xml-ref)

- [Salesforce Help](https://help.salesforce.com)