Azure Service Bus JMS 2.0 developer guide

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.

Java Message Service (JMS) Programming model

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

JMS - Building blocks

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

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.

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

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

TokenCredential tokenCredential = new DefaultAzureCredentialBuilder()
                                                .managedIdentityClientId("<clientIDOfUserAssignedIdentity>")
                                                .build();

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

TokenCredential tokenCredential = new ClientSecretCredentialBuilder()
                .tenantId("")
                .clientId("")
                .clientSecret("")
                .build();;

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

ConnectionFactory factory = new ServiceBusJmsConnectionFactory(SERVICE_BUS_CONNECTION_STRING, 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);

Session modes

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

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

JMSContext

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);

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:

• Service Bus - Queues, Topics, and Subscriptions
• Service Bus - Java Message Service entities
• AMQP 1.0 support in Azure Service Bus
• Service Bus AMQP 1.0 Developer's Guide
• Get started with Service Bus queues
• Java Message Service API(external Oracle doc)
• Learn how to migrate from ActiveMQ to Service Bus