Use Java Message Service 2.0 API with Azure Service Bus Premium

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.


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


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
  • JMSContext.createQueue( String queueName)
  • JMSContext.createTopic( String topicName)
Temporary queues
  • JMSContext.createTemporaryQueue()
Temporary topics
  • JMSContext.createTemporaryTopic()
Message Producer /
  • JMSContext.createProducer()
Queue browsers
  • JMSContext.createBrowser(Queue queue)
  • JMSContext.createBrowser(Queue queue, String messageSelector)
Message Consumer/
  • JMSContext.createConsumer( Destination destination)
  • JMSContext.createConsumer( Destination destination, String messageSelector)
  • JMSContext.createConsumer( Destination destination, String messageSelector, boolean noLocal)

noLocal is currently not supported
Shared durable subscriptions
  • JMSContext.createSharedDurableConsumer(Topic topic, String name)
  • JMSContext.createSharedDurableConsumer(Topic topic, String name, String messageSelector)
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
Shared non-durable subscriptions
  • JMSContext.createSharedConsumer(Topic topic, String sharedSubscriptionName)
  • JMSContext.createSharedConsumer(Topic topic, String sharedSubscriptionName, String messageSelector)
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
Message selectors depends on the consumer created Supported
Delivery Delay (scheduled messages)
  • JMSProducer.setDeliveryDelay( long deliveryDelay)
Message created
  • JMSContext.createMessage()
  • JMSContext.createBytesMessage()
  • JMSContext.createMapMessage()
  • JMSContext.createObjectMessage( Serializable object)
  • JMSContext.createStreamMessage()
  • JMSContext.createTextMessage()
  • JMSContext.createTextMessage( String text)
Cross entity transactions
  • Connection.createSession(true, Session.SESSION_TRANSACTED)
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.



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 have been 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.

  1. Instantiate the ServiceBusJmsConnectionFactorySettings

    ServiceBusJmsConnectionFactorySettings connFactorySettings = new ServiceBusJmsConnectionFactorySettings();
  2. Instantiate the ServiceBusJmsConnectionFactory with the appropriate ServiceBusConnectionString.

    ConnectionFactory factory = new ServiceBusJmsConnectionFactory(ServiceBusConnectionString, connFactorySettings);
  3. 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();


    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 has been 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();


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.

Next steps

For more information on Azure Service Bus and details about Java Message Service (JMS) entities, check out the links below -