Connection Factories

A JMS ConnectionFactory is the configuration object every IBM MQ Java application uses before it ever opens a queue or topic. Think of it as the address book and security badge printer for your messaging: it stores which queue manager to reach, which SVRCONN channel to use, whether traffic is TLS-protected, and how the client should behave when the network blips. Application code asks the factory for a Connection; the Connection opens TCP (or bindings) to the queue manager; Sessions created from that Connection perform the actual puts and gets. Misconfigured factories cause the majority of beginner incidents—wrong port, typo in queue manager name, missing client JAR, or channel auth blocking the MCAUSER your app presents. This tutorial explains IBM MQ-specific factory classes, essential properties and what each one changes, JNDI and Spring Boot configuration patterns, CCDT versus inline settings, TLS and mutual authentication hooks, reconnect options, XA factories for global transactions, and how operations teams hand off factory settings without leaking secrets into source control.

IBM MQ ConnectionFactory Classes

com.ibm.mq.jms.MQConnectionFactory implements javax.jms/jakarta.jms ConnectionFactory. You set string properties such as hostName, port, channel, queueManager, transportType, and SSL-related cipher suite names. MQQueueConnectionFactory and MQTopicConnectionFactory remain in older samples; unified factories simplify dual queue and topic applications. Always place IBM MQ client JARs on the classpath—JMS API jars alone contain no provider. Version alignment between client and queue manager prevents subtle attribute and cipher mismatches during upgrades.

Programmatic Configuration Example

1
2
3
4
5
6
7
8
9
10
11
MQConnectionFactory factory = new MQConnectionFactory();
factory.setHostName("mq.example.com");
factory.setPort(1414);
factory.setChannel("APP.SVRCONN");
factory.setQueueManager("QM1");
factory.setTransportType(WMQConstants.WMQ_TRANSPORT_MQSERIES_CLIENT);
factory.setStringProperty(WMQConstants.WMQ_CLIENT_RECONNECT_OPTIONS,
    WMQConstants.WMQ_CLIENT_RECONNECT);
 
Connection conn = factory.createConnection("appUser", "secret");
conn.start();

createConnection with user and password passes credentials for queue manager authentication when CONNAUTH requires them. Many estates map certificate DN to MCAUSER instead and omit passwords. Never commit real passwords to Git—use vaults or server bindings. After createConnection, call start on the Connection before creating MessageListeners or some receive calls block.

JNDI on Application Servers

WebSphere Liberty and traditional WAS define a JMS connection factory resource referencing IBM MQ. Deployments bind jms/MQFactory in JNDI; applications perform initial context lookup. Benefits: environment-specific bindings without code changes, centralized TLS keystore configuration on the server, and connection pooling managed by the container. Drawbacks: harder local debugging unless you replicate JNDI in test with embedded Liberty or resource references in Spring.

Spring Boot Configuration

1
2
3
4
5
6
7
8
9
ibm:
  mq:
    queueManager: QM1
    channel: APP.SVRCONN
    connName: mq.example.com(1414)
    user: ${MQ_USER}
    password: ${MQ_PASSWORD}
    client:
      reconnect: true

Spring Boot auto-configures a ConnectionFactory bean from ibm.mq properties. Custom beans override reconnect, SSL, and CCDT location. @JmsListener containers inject the same factory—verify pool size and concurrency do not open more connections than queue manager MAXCHANNELS allows.

CCDT-Driven Factories

Setting factory.setCCDTURL or environment variables MQCHLLIB and MQCHLTAB directs the client to a channel table file maintained by operations. When the DR site activates, operations swaps CCDT; applications reconnect to the standby host. Inline hostName/port in code fights operations runbooks—prefer CCDT or externalized config for anything beyond local developer laptops.

TLS and Mutual TLS

• SSL cipher suite must match channel SSLCIPH and queue manager GSKit policy.
• Trust store must contain the CA that signed the queue manager certificate.
• Mutual TLS adds client certificate presentation—maps to CHLAUTH SSLPEER rules and possibly MCAUSER mapping.
• Test with openssl s_client or MQ diagnostics before blaming application code.

XA ConnectionFactory

When a service updates Db2 and sends JMS in one atomic business action, configure an XA ConnectionFactory and enlist through JTA. The transaction manager drives two-phase commit; application code calls tm.commit(), not raw session.commit() mixed incorrectly. Non-XA factories silently break cross-resource atomicity—architects must verify the deployment descriptor or Spring transaction manager actually uses XA resources. See the XA transactions tutorial for prepare/commit flow.

Connection Pooling and Lifecycle

Creating a new Connection per message is expensive. Application servers pool connections; Spring JmsTemplate may cache sessions depending on configuration. Leaked connections show as elevated CHSTATUS and IPPROCS on channels. Shutdown hooks should close factories and connections cleanly during deploys to avoid orphaned handles blocking channel limits.

Explainer: Phone Book for the Post Office

The ConnectionFactory is the phone book entry for the post office branch—address, hours, security desk. Each Connection is one phone call; each Session is a conversation during that call about what to send.

Explain Like I'm Five: Connection Factories

The factory remembers where the mailbox building is and what key card you need. Every time you want to mail a letter, you ask the factory for a connection instead of looking up the address yourself each time.

Practice Exercises

Exercise 1

Document which ConnectionFactory settings differ between dev, test, and prod for your estate.

Exercise 2

Compare inline host/port versus CCDT for a DR scenario. Who updates what during failover?

Exercise 3

Verify whether your application server uses XA or local JMS transactions for a given datasource plus JMS flow.

Troubleshooting

1. MQRC_HOST_NOT_AVAILABLE—DNS, firewall, or wrong connName.
2. SSL errors—cipher mismatch or expired certificates.
3. 2035—authentication or CHLAUTH on SVRCONN.
4. Too many connections—pool sizing versus MAXCHANNELS.

Frequently Asked Questions

Test Your Knowledge