Use Java Message Service 2.0 API with Azure Service Bus Premium

Article
08/26/2024

This article explains how to use the popular Java Message Service (JMS) 2.0 API to interact with Azure Service Bus over the Advanced Message Queueing Protocol (AMQP 1.0) protocol.

Note

Support for Java Message Service (JMS) 2.0 API is only available in the premium tier.

Prerequisites

Get started with Service Bus

This guide assumes that you already have a Service Bus namespace. If you don't, create a namespace and a queue using the Azure portal. For more information about how to create Service Bus namespaces and queues, see Get started with Service Bus queues through the Azure portal.

Set up a Java Development environment

To develop Java applications, you need to set up the appropriate development environment -

Either the JDK (Java Development Kit) or the JRE (Java Runtime Environment) is installed.
The JDK or JRE is added to the build path and the appropriate system variables.
A Java IDE is installed to utilize the JDK or JRE. For example, Eclipse or IntelliJ.

To learn more about how to prepare your developer environment for Java on Azure, utilize this guide.

What JMS features are supported?

The following table lists the Java Message Service (JMS) features that Azure Service Bus currently supports. It also shows features that are unsupported.

Feature	API	Status
Queues	JMSContext.createQueue( String queueName)	Supported
Topics	JMSContext.createTopic( String topicName)	Supported
Temporary queues	JMSContext.createTemporaryQueue()	Supported
Temporary topics	JMSContext.createTemporaryTopic()	Supported
Message Producer / JMSProducer	JMSContext.createProducer()	Supported
Queue browsers	JMSContext.createBrowser(Queue queue) JMSContext.createBrowser(Queue queue, String messageSelector)	Supported
Message Consumer/ JMSConsumer	JMSContext.createConsumer( Destination destination) JMSContext.createConsumer( Destination destination, String messageSelector) JMSContext.createConsumer( Destination destination, String messageSelector, boolean noLocal) noLocal is currently not supported	Supported
Shared durable subscriptions	JMSContext.createSharedDurableConsumer(Topic topic, String name) JMSContext.createSharedDurableConsumer(Topic topic, String name, String messageSelector)	Supported
Unshared durable subscriptions	JMSContext.createDurableConsumer(Topic topic, String name) createDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal) noLocal is currently not supported and should be set to false	Supported
Shared non-durable subscriptions	JMSContext.createSharedConsumer(Topic topic, String sharedSubscriptionName) JMSContext.createSharedConsumer(Topic topic, String sharedSubscriptionName, String messageSelector)	Supported
Unshared non-durable subscriptions	JMSContext.createConsumer(Destination destination) JMSContext.createConsumer( Destination destination, String messageSelector) JMSContext.createConsumer( Destination destination, String messageSelector, boolean noLocal) noLocal is currently not supported and should be set to false	Supported
Message selectors	depends on the consumer created	Supported
Delivery Delay (scheduled messages)	JMSProducer.setDeliveryDelay( long deliveryDelay)	Supported
Message created	JMSContext.createMessage() JMSContext.createBytesMessage() JMSContext.createMapMessage() JMSContext.createObjectMessage( Serializable object) JMSContext.createStreamMessage() JMSContext.createTextMessage() JMSContext.createTextMessage( String text)	Supported
Cross entity transactions	Connection.createSession(true, Session.SESSION_TRANSACTED)	Supported
Distributed transactions		Not supported

Downloading the Java Message Service (JMS) client library

To utilize all the features available in the premium tier, add the following library to the build path of the project: azure-servicebus-jms. This package provides some necessary defaults such as prefetch policy values, reconnect policies, Microsoft Entra ID, and Managed Identity support out of the box.

Note

To add the azure-servicebus-jms to the build path, use the preferred dependency management tool for your project like Maven or Gradle.

Coding Java applications

Once the dependencies are imported, the Java applications can be written in a JMS provider agnostic manner.

Connecting to Azure Service Bus using JMS

To connect with Azure Service Bus using JMS clients, you need the connection string that is available in the 'Shared Access Policies' in the Azure portal under Primary Connection String.

Instantiate the ServiceBusJmsConnectionFactorySettings

ServiceBusJmsConnectionFactorySettings connFactorySettings = new ServiceBusJmsConnectionFactorySettings();
connFactorySettings.setConnectionIdleTimeoutMS(20000);

Instantiate the ServiceBusJmsConnectionFactory with the appropriate ServiceBusConnectionString.

String ServiceBusConnectionString = "<SERVICE_BUS_CONNECTION_STRING_WITH_MANAGE_PERMISSIONS>";
ConnectionFactory factory = new ServiceBusJmsConnectionFactory(ServiceBusConnectionString, connFactorySettings);

Use the ConnectionFactory to either create a Connection and then a Session
```
Connection connection = factory.createConnection();
Session session = connection.createSession();
```
or a JMSContext (for JMS 2.0 clients)
```
JMSContext jmsContext = factory.createContext();
```
Important

Although similarly named, a JMS 'Session' and Service Bus 'Session' is completely independent of each other.

In JMS 1.1, Session is an essential building block of the API that allows creation of the MessageProducer, MessageConsumer, and the Message itself. For more details, review the JMS API programming model

In Service Bus, sessions are service and client side construct to enable FIFO processing on queues and subscriptions.

Write the JMS application

Once the Session or JMSContext is instantiated, your application can use the familiar JMS APIs to perform both management and data operations. Refer to the list of supported JMS features to see which APIs are supported. Here are some sample code snippets to get started with JMS -

Sending messages to a queue and topic

// Create the queue and topic
Queue queue = jmsContext.createQueue("basicQueue");
Topic topic = jmsContext.createTopic("basicTopic");
// Create the message
Message msg = jmsContext.createMessage();

// Create the JMS message producer
JMSProducer producer = jmsContext.createProducer();

// send the message to the queue
producer.send(queue, msg);
// send the message to the topic
producer.send(topic, msg);

Receiving messages from a queue

// Create the queue
Queue queue = jmsContext.createQueue("basicQueue");

// Create the message consumer
JMSConsumer consumer = jmsContext.createConsumer(queue);

// Receive the message
Message msg = (Message) consumer.receive();

Receiving messages from a shared durable subscription on a topic

// Create the topic
Topic topic = jmsContext.createTopic("basicTopic");

// Create a shared durable subscriber on the topic
JMSConsumer sharedDurableConsumer = jmsContext.createSharedDurableConsumer(topic, "sharedDurableConsumer");

// Receive the message
Message msg = (Message) sharedDurableConsumer.receive();

Summary

This guide showcased how Java client applications using Java Message Service (JMS) over AMQP 1.0 can interact with Azure Service Bus.

You can also use Service Bus AMQP 1.0 from other languages, including .NET, C, Python, and PHP. Components built using these different languages can exchange messages reliably and at full fidelity using the AMQP 1.0 support in Service Bus.