Azure Service Bus client library for Java - Version 7.0.0-beta.1

Microsoft Azure Service Bus is a fully managed enterprise integration message broker. Service Bus can decouple applications and services. Service Bus offers a reliable and secure platform for asynchronous transfer of data and state. Data is transferred between different applications and services using messages. If you would like to know more about Azure Service Bus, you may wish to review: What is Service Bus?

The Azure Service Bus client library allows for sending and receiving of Azure Service Bus messages and may be used to:

  • Messaging: Transfer business data, such as sales or purchase orders, journals, or inventory movements.
  • Decouple applications: Improve reliability and scalability of applications and services. Client and service don't have to be online at the same time.
  • Topics and subscriptions: Enable 1:n relationships between publishers and subscribers.
  • Message sessions. Implement work-flows that require message ordering or message deferral.

Source code | API reference documentation | Samples

Table of contents

Getting started


Adding the package to your product


Authenticate the client

For the Service Bus client library to interact with an Service Bus, it will need to understand how to connect and authorize with it.

Create an Service Bus client using Microsoft identity platform (formerly Azure Active Directory)

Azure SDK for Java supports an Azure Identity package, making it simple get credentials from Microsoft identity platform. First, add the package:


All the implemented ways to request a credential can be found under the package. The sample below shows how to use an Azure Active Directory (AAD) application client secret to authorize with Azure Service Bus.

Authorizing with AAD application client secret

Follow the instructions in Creating a service principal using Azure Portal to create a service principal and a client secret. The corresponding clientId and tenantId for the service principal can be obtained from the App registration page.

Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Use the returned token credential to authenticate the client:

TokenCredential credential = new DefaultAzureCredentialBuilder()
ServiceBusReceiverAsyncClient receiver = new ServiceBusClientBuilder()
    .credential("<<fully-qualified-namespace>>", credential)
Service Bus Roles

When using Azure Active Directory, your principal must be assigned a role which allows access to Service Bus, such as the Azure Service Bus Data Owner, Azure Service Bus Data Sender and Azure Service Bus Data Receiver role. For more information about using Azure Active Directory authorization with Service Bus, please refer to the associated documentation.

Key concepts

You can interact with the primary resource types within a Service Bus Namespace, of which multiple can exist and on which actual message transmission takes place, the namespace often serving as an application container:

  • Queue: Allows for Sending and Receiving of messages, ordered first-in-first-out. Often used for point-to-point communication.

  • Topic: As opposed to Queues, Topics are better suited to publish/subscribe scenarios. A topic can be sent to, but requires a subscription, of which there can be multiple in parallel, to consume from.

  • Subscription: The mechanism to consume from a Topic. Each subscription is independent, and receaves a copy of each message sent to the topic.


Create a sender or receiver using connection string

The easiest means for doing so is to use a connection string, which is created automatically when creating an Service Bus namespace. If you aren't familiar with shared access policies in Azure, you may wish to follow the step-by-step guide to get an Service Bus connection string.

Both the asynchronous and synchronous Service Bus sender and receiver clients can be created using ServiceBusClientBuilder.The examples are explained blow.

The snippet below creates an asynchronous Service Bus sender.

ServiceBusSenderAsyncClient sender = new ServiceBusClientBuilder()
    .queueName("<< QUEUE NAME >>")

The snippet below creates an asynchronous Service Bus receiver.

ServiceBusReceiverAsyncClient receiver = new ServiceBusClientBuilder()
    .topicName("<< TOPIC NAME >>")
    .subscriptionName("<< SUBSCRIPTION NAME >>")

Send Message Examples

You'll need to create an asynchronous ServiceBusSenderAsyncClient or a synchronous ServiceBusSenderClient to send message. Each sender can send message to either, a queue, or topic.

Receive Message Examples

You'll need to create an asynchronous ServiceBusReceiverAsyncClient or a synchronous ServiceBusReceiverClient. Each receiver can receive message from either, a queue, or subscriber.


Enable client logging

You can set the AZURE_LOG_LEVEL environment variable to view logging statements made in the client library. For example, setting AZURE_LOG_LEVEL=2 would show all informational, warning, and error log messages. The log levels can be found here: log levels.

Enable AMQP transport logging

If enabling client logging is not enough to diagnose your issues. You can enable logging to a file in the underlying AMQP library, Qpid Proton-J. Qpid Proton-J uses java.util.logging. You can enable logging by create a configuration file with the contents below. Or set proton.trace.level=ALL and whichever configuration options you want for the java.util.logging.Handler implementation. Implementation classes and their options can be found in Java 8 SDK javadoc.

To trace the AMQP transport frames, set the environment variable: PN_TRACE_FRM=1.

Sample "" file

The configuration file below logs trace output from proton-j to the file "proton-trace.log".

java.util.logging.SimpleFormatter.format=[%1$tF %1$tr] %3$s %4$s: %5$s %n

Common exceptions

AMQP exception

This is a general exception for AMQP related failures, which includes the AMQP errors as ErrorCondition and the context that caused this exception as AmqpErrorContext. isTransient is a boolean indicating if the exception is a transient error or not. If true, then the request can be retried; otherwise not.

AmqpErrorCondition contains error conditions common to the AMQP protocol and used by Azure services. When an AMQP exception is thrown, examining the error condition field can inform developers as to why the AMQP exception occurred and if possible, how to mitigate this exception. A list of all the AMQP exceptions can be found in OASIS AMQP Version 1.0 Transport Errors.

The AmqpErrorContext in the AmqpException provides information about the AMQP session, link, or connection that the exception occurred in. This is useful to diagnose which level in the transport this exception occurred at and whether it was an issue in one of the producers or consumers.

Operation cancelled exception

It occurs when the underlying AMQP layer encounters an abnormal link abort or the connection is disconnected in an unexpected fashion. It is recommended to attempt to verify the current state and retry if necessary.

Handling transient AMQP exceptions

If a transient AMQP exception occurs, the client library retries the operation as many times as the [AmqpRetryOptions][AmqpRetryOptions] allows. Afterwards, the operation fails and an exception is propagated back to the user.

Default SSL library

All client libraries, by default, use the Tomcat-native Boring SSL library to enable native-level performance for SSL operations. The Boring SSL library is an uber jar containing native libraries for Linux / macOS / Windows, and provides better performance compared to the default SSL implementation within the JDK. For more information, including how to reduce the dependency size, refer to the performance tuning section of the wiki.

Next steps

Beyond those discussed, the Azure Service Bus client library offers support for many additional scenarios to help take advantage of the full feature set of the Azure Service Bus service. In order to help explore some of the these scenarios, the following set of sample is available here.


If you would like to become an active contributor to this project please refer to our Contribution Guidelines for more information.