IBM MQ Connector 2.0
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
Exchange: 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.
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.
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 and IBM MQ XA Connection.
Connection Mode
When creating the IBM configuration, choose is the IBM connection mode 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:
| Parameter | Required | Default Value | Description |
|---|---|---|---|
Host |
TRUE |
Host containing the IBM MQ Broker. |
|
Port |
FALSE |
1414 |
Queue manager listener port. |
Queue Manager |
FALSE |
The queue manager used when selecting a channel definition. |
|
Channel |
FALSE |
Name of the channel to connect to. |
|
Connection Name List |
FALSE |
Hosts to which the client attempts to reconnect after its connection is broken. |
|
Client Reconnect Options |
FALSE |
RECONNECT |
Controls the reconnection behavior for the IBM MQ client. Applies when Connection Name List or a CCDT is configured. |
Client Reconnect Timeout |
FALSE |
20 |
The maximum time, in seconds, that the client spends attempting to reconnect. Applies when Connection Name List is configured with multiple hosts. |
For descriptions of all client connection mode parameters, see Client.
<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.
<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.
<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:
<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.
| 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:
<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:
<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.
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.
<ibm-mq:config name="IBM_MQ_Config">
<ibm-mq:ibm-mq-connection clientId="${env.clientId}"/>
</ibm-mq:config>
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.
| 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:
<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.