Skip to content

how-to-use-java-message-service-20.md

Latest commit

 

History

History
210 lines (146 loc) · 9.42 KB

how-to-use-java-message-service-20.md

File metadata and controls

210 lines (146 loc) · 9.42 KB
title Use Java Message Service 2.0 API
description Explains how to use the Java Message Service (JMS) 2.0 API to interact with Azure Service Bus over the Advanced Message Queueing Protocol (AMQP) 1.0 protocol.
ms.topic how-to
ms.date 01/10/2024
ms.custom
devx-track-extended-java
sfi-ropc-nochange

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.

Important notes

  • JMS 2.0 API support requires the Azure Service Bus Premium tier and the azure-servicebus-jms library. Using other JMS libraries (for example, qpid-jms-client directly) against a premium namespace results in JMS 1.1 behavior, and some JMS 2.0 features might not work as expected.
  • The library is open source and built on top of qpid-jms-client — all qpid-jms-client APIs work with it, so there is no vendor lock-in. It also provides defaults for prefetch policies, reconnect policies, Microsoft Entra ID, Managed Identity support, and Auto Delete on Idle.
  • The library is available in two variants for Jakarta EE and Java EE. See Jakarta EE and javax support for details on which artifact to use.

Jakarta EE and javax support

The azure-servicebus-jms library is available in two variants to support both the legacy Java EE (javax.jms) and the newer Jakarta EE (jakarta.jms) API namespaces.

API namespace Maven artifact Versions JMS specification
jakarta.jms (Jakarta EE 9+) com.azure:azure-servicebus-jms 2.0.0+ Jakarta Messaging (JMS 2.0)
javax.jms (Java EE) com.microsoft.azure:azure-servicebus-jms 1.0.x JMS 2.0

Which artifact should I use?

  • If your project uses Jakarta EE 9 or later (for example, Spring Boot 3.x, Quarkus 3.x, or any framework that imports jakarta.jms.*), use the com.azure artifact:

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-servicebus-jms</artifactId>
  <version>2.1.0</version>
</dependency>

  • If your project still uses Java EE (imports javax.jms.*), continue using the com.microsoft.azure artifact:

    <dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>azure-servicebus-jms</artifactId>
  <version>1.0.2</version>
</dependency>

Important

Do not mix the two artifacts. Using com.azure:azure-servicebus-jms in a project that imports javax.jms.* results in compilation errors, and vice versa.

Migrating from javax to Jakarta

If you're upgrading your application from Java EE to Jakarta EE:

  1. Replace your Maven dependency group ID from com.microsoft.azure to com.azure and update the version to 2.0.0 or later.
  2. Update all javax.jms.* imports in your code to jakarta.jms.*.
  3. The ServiceBusJmsConnectionFactory API and configuration remain the same across both variants, so no code changes are needed beyond the import and dependency updates.

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?

[!INCLUDE service-bus-jms-features-list]

Downloading the Java Message Service (JMS) client library

To utilize all the features available in the premium tier, add the azure-servicebus-jms library to the build path of your project. This package provides necessary defaults such as prefetch policy values, reconnect policies, Microsoft Entra ID, and Managed Identity support out of the box. Choose the artifact that matches your project's API namespace (see Jakarta EE and javax support for details):

Jakarta EE (jakarta.jms):

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-servicebus-jms</artifactId>
  <version>2.1.0</version>
</dependency>

Java EE (javax.jms):

<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>azure-servicebus-jms</artifactId>
  <version>1.0.2</version>
</dependency>

Note

To add the library 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.

  1. Instantiate the ServiceBusJmsConnectionFactorySettings

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

  2. Instantiate the ServiceBusJmsConnectionFactory with the appropriate ServiceBusConnectionString.

    String ServiceBusConnectionString = "<SERVICE_BUS_CONNECTION_STRING_WITH_MANAGE_PERMISSIONS>";
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();

    [!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.

Related content