Azure Service Bus JMS 2.0 developer guide

  • Article

This guide contains detailed information to help you succeed in communicating with Azure Service Bus using the Java Message Service (JMS) 2.0 API.

As a Java developer, if you're new to Azure Service Bus, consider reading the following articles.

Getting started Concepts

Java Message Service (JMS) Programming model

The Java Message Service API programming model is as shown in the following sections:

Note

Azure Service Bus Premium tier supports JMS 1.1 and JMS 2.0.

Azure Service Bus - Standard tier supports limited JMS 1.1 functionality. For more details, please refer to this documentation.

JMS - Building blocks

The below building blocks are available to communicate with the JMS application.

Note

The below guide has been adapted from the Oracle Java EE 6 Tutorial for Java Message Service (JMS)

Referring to this tutorial is recommended for better understanding of the Java Message Service (JMS).

Connection factory

The connection factory object is used by the client to connect with the JMS provider. The connection factory encapsulates a set of connection configuration parameters that are defined by the administrator.

Each connection factory is an instance of ConnectionFactory, QueueConnectionFactory, or TopicConnectionFactory interface.

To simplify connecting with Azure Service Bus, these interfaces are implemented through ServiceBusJmsConnectionFactory, ServiceBusJmsQueueConnectionFactory, or ServiceBusJmsTopicConnectionFactory respectively.

Important

Java applications leveraging JMS 2.0 API can connect to Azure Service Bus using the connection string, or using a TokenCredential for leveraging Microsoft Entra backed authentication. When using Microsoft Entra backed authentication, ensure to assign roles and permissions to the identity as needed.

Create a system assigned managed identity on Azure, and use this identity to create a TokenCredential.

TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

The Connection factory can then be instantiated with the below parameters.

  • Token credential - Represents a credential capable of providing an OAuth token.
  • Host - the hostname of the Azure Service Bus Premium tier namespace.
  • ServiceBusJmsConnectionFactorySettings property bag, which contains
    • connectionIdleTimeoutMS - idle connection timeout in milliseconds.
    • traceFrames - boolean flag to collect AMQP trace frames for debugging.
    • other configuration parameters

The factory can be created as shown here. The token credential and host are required parameters, but the other properties are optional.

String host = "<YourNamespaceName>.servicebus.chinacloudapi.cn";
ConnectionFactory factory = new ServiceBusJmsConnectionFactory(tokenCredential, host, null);

JMS destination

A destination is the object a client uses to specify the target of the messages it produces and the source of the messages it consumes.

Destinations map to entities in Azure Service Bus - queues (in point to point scenarios) and topics (in pub-sub scenarios).

Connections

A connection encapsulates a virtual connection with a JMS provider. With Azure Service Bus, it represents a stateful connection between the application and Azure Service Bus over AMQP.

A connection is created from the connection factory as shown in the following example:

Connection connection = factory.createConnection();

Sessions

A session is a single-threaded context for producing and consuming messages. It can be utilized to create messages, message producers and consumers, but it also provides a transactional context to allow grouping of sends and receives into an atomic unit of work.

A session can be created from the connection object as shown in the following example:

Session session = connection.createSession(false, Session.CLIENT_ACKNOWLEDGE);

Note

JMS API doesn't support receiving messages from service bus queues or topics with messaging sessions enabled.

Session modes

A session can be created with any of the below modes.

Session modes Behavior
Session.AUTO_ACKNOWLEDGE The session automatically acknowledges a client's receipt of a message either when the session has successfully returned from a call to receive or when the message listener the session has called to process the message successfully returns.
Session.CLIENT_ACKNOWLEDGE The client acknowledges a consumed message by calling the message's acknowledge method.
Session.DUPS_OK_ACKNOWLEDGE This acknowledgment mode instructs the session to lazily acknowledge the delivery of messages.
Session.SESSION_TRANSACTED This value may be passed as the argument to the method createSession(int sessionMode) on the Connection object to specify that the session should use a local transaction.

When the session mode isn't specified, the Session.AUTO_ACKNOWLEDGE is picked by default.

JMSContext

Note

JMSContext is defined as part of the JMS 2.0 specification.

JMSContext combines the functionality provided by the connection and session object. It can be created from the connection factory object.

JMSContext context = connectionFactory.createContext();

JMSContext modes

Just like the Session object, the JMSContext can be created with the same acknowledge modes as mentioned in Session modes.

JMSContext context = connectionFactory.createContext(JMSContext.AUTO_ACKNOWLEDGE);

When the mode isn't specified, the JMSContext.AUTO_ACKNOWLEDGE is picked by default.

JMS message producers

A message producer is an object that is created using a JMSContext or a Session and used for sending messages to a destination.

It can be created either as a stand-alone object as shown in the following example:

JMSProducer producer = context.createProducer();

Or created at runtime when a message is needed to be sent.

context.createProducer().send(destination, message);

JMS message consumers

A message consumer is an object that is created by a JMSContext or a Session and used for receiving messages sent to a destination. It can be created as shown in this example:

JMSConsumer consumer = context.createConsumer(dest);

Synchronous receives via receive() method

The message consumer provides a synchronous way to receive messages from the destination through the receive() method.

If no arguments/timeout is specified or a timeout of '0' is specified, then the consumer blocks indefinitely unless the message arrives, or the connection is broken (whichever is earlier).

Message m = consumer.receive();
Message m = consumer.receive(0);

When a non-zero positive argument is provided, the consumer blocks until that timer expires.

Message m = consumer.receive(1000); // time out after one second.

Asynchronous receives with JMS message listeners

A message listener is an object that is used for asynchronous handling of messages on a destination. It implements the MessageListener interface, which contains the onMessage method where the specific business logic must live.

A message listener object must be instantiated and registered against a specific message consumer using the setMessageListener method.

Listener myListener = new Listener();
consumer.setMessageListener(myListener);

Consuming from topics

JMS Message Consumers are created against a destination, which can be a queue or a topic.

Consumers on queues are simply client side objects that live in the context of the Session (and Connection) between the client application and Azure Service Bus.

Consumers on topics, however, have 2 parts -

  • A client side object that lives in the context of the Session(or JMSContext), and,
  • A subscription that is an entity on Azure Service Bus.

The subscriptions are documented here and can be one of the following ones:

  • Shared durable subscriptions
  • Shared non-durable subscriptions
  • Unshared durable subscriptions
  • Unshared non-durable subscriptions

JMS Queue Browsers

The JMS API provides a QueueBrowser object that allows the application to browse the messages in the queue and display the header values for each message.

A Queue Browser can be created using the JMSContext as in the following example:

QueueBrowser browser = context.createBrowser(queue);

Note

JMS API doesn't provide an API to browse a topic.

This is because the topic itself doesn't store the messages. As soon as the message is sent to the topic, it is forwarded to the appropriate subscriptions.

JMS Message selectors

Message selectors can be used by receiving applications to filter the messages that are received. With message selectors, the receiving application offloads the work of filtering messages to the JMS provider (in this case, Azure Service Bus) instead of taking that responsibility itself.

Selectors can be utilized when creating any of the below consumers -

  • Shared durable subscription
  • Unshared durable subscription
  • Shared non-durable subscription
  • Unshared non-durable subscription
  • Queue browser

AMQP disposition and Service Bus operation mapping

Here's how an AMQP disposition translates to a Service Bus operation:

ACCEPTED = 1; -> Complete()
REJECTED = 2; -> DeadLetter()
RELEASED = 3; (just unlock the message in service bus, will then get redelivered)
MODIFIED_FAILED = 4; -> Abandon() which increases delivery count
MODIFIED_FAILED_UNDELIVERABLE = 5; -> Defer()

Summary

This developer guide showcased how Java client applications using Java Message Service (JMS) can connect with Azure Service Bus.

Next steps

For more information on Azure Service Bus and details about Java Message Service (JMS) entities, check out the following articles: