JMS Client

Overview

The SwiftMQ JMS 1.1 Client API provides a full-featured JMS implementation supporting point-to-point (queue) and publish/subscribe (topic) messaging, request/reply patterns, transactions (including XA), and all standard JMS message types. Connections, destinations, and factories are typically obtained via JNDI lookup, with SwiftMQ-specific conventions for naming and configuration. The client supports features such as automatic reconnection, duplicate message detection, and message property management.

Connection Setup via JNDI

SwiftMQ JMS clients are typically configured and connected using JNDI. Connection factories, queues, and topics are registered in the JNDI context and can be looked up using the standard InitialContext. For queues, the lookup name must be in the form queuename@routername (the @routername part is mandatory). For topics, use just the plain topic name (no @routername). Connection factories are looked up as factoryname@routername.

Connection factories support a wide range of configuration properties, such as hostname, port, clientid, reconnect_enabled, and others. These can be set via the JNDI environment or a properties map. Once a factory is obtained, use its createConnection or createQueueConnection/createTopicConnection methods to establish a JMS connection. SwiftMQ also supports XA connections for distributed transactions.

Context ctx = new InitialContext();
ConnectionFactory cf = (ConnectionFactory) ctx.lookup("mycf@router1");
Connection connection = cf.createConnection("user", "password");

Point-to-Point Messaging (Queues)

To send and receive messages using queues, use the Queue and QueueSession APIs. Queues must be looked up using the queuename@routername convention. Create a QueueSender to send messages and a QueueReceiver to receive them. Message selectors and synchronous/asynchronous consumption are supported. Temporary queues can be created for request/reply patterns.

Queue queue = (Queue) ctx.lookup("orders@router1");
QueueSession session = ((QueueConnection) connection).createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
QueueSender sender = session.createSender(queue);
QueueReceiver receiver = session.createReceiver(queue);

Publish/Subscribe Messaging (Topics)

For publish/subscribe, use the Topic and TopicSession APIs. Topics are looked up by their plain name (no router suffix). Create a TopicPublisher to publish messages and a TopicSubscriber to receive them. Durable subscriptions are supported via createDurableSubscriber, which requires a client ID to be set on the connection. Temporary topics can also be created.

Topic topic = (Topic) ctx.lookup("news");
TopicSession session = ((TopicConnection) connection).createTopicSession(false, Session.AUTO_ACKNOWLEDGE);
TopicPublisher publisher = session.createPublisher(topic);
TopicSubscriber subscriber = session.createSubscriber(topic);

Request/Reply Patterns

SwiftMQ supports request/reply messaging using temporary queues or topics. The sender sets the JMSReplyTo property on the message to a temporary destination, and the receiver responds by sending a message to that destination. Temporary destinations are created via the session and are automatically cleaned up when the connection closes, or can be deleted explicitly.

TemporaryQueue tempQueue = session.createTemporaryQueue();
TextMessage request = session.createTextMessage("Request");
request.setJMSReplyTo(tempQueue);
sender.send(request);
QueueReceiver replyReceiver = session.createReceiver(tempQueue);

Transactions and XA Support

Sessions can be created as transacted (createSession(true, ...)) or with standard JMS acknowledge modes. For distributed transactions, use XA connections and sessions (XAConnection, XASession, etc.), which expose the getXAResource() method for transaction management. The client supports full XA recovery, prepare, commit, and rollback operations.

XAConnection xaconn = ((XAConnectionFactory) cf).createXAConnection("user", "password");
XASession xasession = xaconn.createXASession();
XAResource xares = xasession.getXAResource();

Supported Message Types

All standard JMS message types are supported: TextMessage, BytesMessage, MapMessage, ObjectMessage, and StreamMessage. Each type provides methods for setting and retrieving body content, and supports switching between write and read modes via reset(). Message properties can be set and retrieved for filtering and application use. For example, TextMessageImpl stores text in chunked UTF-8 format for efficiency, and BytesMessageImpl supports streaming binary data.

TextMessage msg = session.createTextMessage();
msg.setText("Hello, World!");
BytesMessage bmsg = session.createBytesMessage();
bmsg.writeBytes(new byte[] {1,2,3});

Duplicate Message Detection and Reconnection

SwiftMQ can be configured to detect and suppress duplicate messages using the duplicate_detection_enabled and duplicate_backlog_size connection factory properties. Automatic reconnection is supported via reconnect_enabled, reconnect_retry_delay, and related properties. Applications can register ReconnectListener instances to be notified when a reconnection occurs.

// Enable duplicate detection and reconnection in connection factory properties
properties.put("duplicate_detection_enabled", "true");
properties.put("reconnect_enabled", "true");