JMS Topics

JMS topics are the Java-facing entry point to IBM MQ publish/subscribe. Where JMS queues load-balance work to one consumer, JMS topics fan out the same event to every matching subscriber—inventory changed, rate updated, security alert raised. You use TopicConnection or a unified ConnectionFactory, create a Topic destination from a name or topic string, publish with TopicPublisher, and subscribe with TopicSubscriber or durable subscription APIs. IBM MQ still enforces topic authority, subscription objects, destination queues for managed subscriptions, and cluster topic routing behind the API. Beginners migrating from queue-only tutorials often publish events to a queue and wonder why only one microservice sees them—that is a queue, not a topic problem. This tutorial maps JMS Topic types to IBM MQ objects, explains durable versus non-durable subscribers, wildcards, shared subscriptions in modern JMS, message selectors, integration with retained publications, administration commands, and failure modes unique to pub/sub estates.

JMS Topic Versus IBM MQ Topic Infrastructure

The JMS Topic interface represents a pub/sub destination. IBM MQ resolves the name against its topic tree—TOPIC objects, topic aliases, and cluster topics. A publication on sports/football/scores reaches subscribers registered for sports/# or sports/football/+ depending on pattern rules. JMS setTopic or createTopic with a string passes that string to the provider; IBM MQ performs routing and fan-out to subscriber destination queues. Managed subscriptions (DESTTYPE MANAGED) create queues automatically; unmanaged subscriptions point at queues you defined in MQSC. Java teams using createDurableSubscriber often discover new QLOCAL objects after deploy—coordinate with operations before production cutover.

Publishing to a Topic

1
2
3
4
5
6
7
8
9
10
TopicConnectionFactory tcf = /* MQConnectionFactory configured */;
TopicConnection conn = tcf.createTopicConnection();
conn.start();
TopicSession session = conn.createTopicSession(false, Session.AUTO_ACKNOWLEDGE);
 
Topic priceTopic = session.createTopic("market/rates/USD");
TopicPublisher publisher = session.createPublisher(priceTopic);
TextMessage msg = session.createTextMessage("1.0842");
msg.setStringProperty("currency", "USD");
publisher.publish(msg);

The topic string market/rates/USD must be publishable by the connected user—check PUB authority on the resolved topic. Properties become JMS headers and may map to MQMD or RFH2 fields depending on configuration. Persistent publication survives restart when delivery mode and topic rules allow. High-rate publishers should monitor publish failures separately from subscriber lag; a fast publisher with slow subscribers increases depth on subscriber destination queues, not on a single shared work queue.

Subscribing: Non-Durable and Durable

Non-durable subscribers receive messages only while connected. Disconnect during maintenance and publications during the gap are lost for that subscriber—acceptable for live dashboards, wrong for billing audit trails. Durable subscribers register a client ID and subscription name; IBM MQ retains messages until consumed subject to expiry and queue limits. createDurableSubscriber(topic, subscriptionName) maps to DEFINE SUB on the server. Client ID must be unique per durable subscriber instance rules your queue manager enforces—duplicate client IDs cause confusing subscription takeover behavior in clustered estates.

Wildcards and Selectors

• Plus (+) matches one topic level—sports/+/scores matches sports/football/scores but not sports/football/uk/scores.
• Hash (#) matches zero or more levels—sports/# matches any depth under sports.
• Message selectors filter by JMS header or property—reduces CPU in the app but still delivers to the subscription queue first unless optimized.

Misconfigured wildcards subscribe to far more traffic than intended—operations sees surprise queue depth growth. Review subscription TOPICSTR in DISPLAY SUB during architecture reviews.

Unified ConnectionFactory Pattern

Modern IBM MQ JMS supports ConnectionFactory implementations that create both queue and topic sessions from one factory—simplifying Spring configuration when an application both sends work to queues and broadcasts events. Domain-specific createQueueSession versus createTopicSession still matters for acknowledgement scope; do not mix pub/sub and point-to-point in one transacted session unless you understand rollback effects on both paths.

MQSC and Subscription Administration

1
2
3
4
5
6
DEFINE TOPIC('MARKET.RATES') TOPICSTR('market/rates') REPLACE
DEFINE SUB('AUDIT.USD.RATES') TOPICSTR('market/rates/USD') +
  DESTQMGR(QM1) DESTQL('AUDIT.RATES.Q') DESTTYPE(QUEUE)
 
DISPLAY SUB('AUDIT.USD.RATES') ALL
DISPLAY TPSTATUS TOPICSTR('market/rates/#')

DESTTYPE(QUEUE) is unmanaged—queue must exist. DESTTYPE(MANAGED) delegates queue creation. DISPLAY TPSTATUS shows publication and subscription activity for troubleshooting fan-out. PUB and SUB authority records are separate from queue GET/PUT for destination queues.

Topics Versus Queues in Architecture Reviews

Choose topics when every interested system needs the same event. Choose queues when exactly one worker should process a unit of work. Hybrid systems publish domain events on topics and enqueue commands on queues—do not duplicate the same payload on both without a versioning strategy. Mainframe CICS and batch programs increasingly consume from queues while cloud-native publishers use JMS topics; bridge patterns copy selected events to queues for legacy consumers.

Explainer: Loudspeaker Versus Mailbox

A JMS topic is the mall loudspeaker—everyone who signed up to listen hears the announcement. A JMS queue is a mailbox slot where only the next person in line takes the letter.

Explain Like I'm Five: JMS Topics

Topics are like the teacher reading a story to the whole class. Everyone who is in the room and listening hears the same story. If you are outside at recess, you miss it unless the teacher saves a copy for you—that is durable.

Practice Exercises

Exercise 1

List three business events that should be topics and three that should be queues in a retail integration.

Exercise 2

Write a durable subscription name and client ID policy for a microservice fleet.

Exercise 3

Given TOPICSTR sports/#, predict which publications match and which do not.

Troubleshooting

1. No messages at subscriber—wrong TOPICSTR, selector too strict, or subscriber not started.
2. 2035 on publish—missing PUB authority on topic.
3. Duplicate delivery—durable redelivery plus at-least-once consumers; design idempotency.
4. Runaway depth—slow consumer on DEST queue; scale consumers or tighten selectors.

Frequently Asked Questions

Test Your Knowledge