Quarkus Azure Service Bus Extension

Quarkus Azure Services Extensions are developed and supported by Microsoft as part of their commitment to Open Standard Enterprise Java. For more information, see Jakarta EE on Azure.

Azure Service Bus is a fully managed enterprise message broker with message queues and publish-subscribe topics. Service Bus is used to decouple applications and services from each other.

This extension provides the following benefits:

  • It resolves native build issues so that applications using the Azure Service Bus with the Azure SDK for Java can be compiled to a native image.

  • It injects com.azure.messaging.servicebus.ServiceBusClientBuilder instances that can be used to create clients for an Azure Service Bus that send and consume messages.

  • The dev services launch an Azure Service Bus emulator in dev and test mode and configure the injected builders to use it.

This is a step by step guide on how to use the Quarkus Azure Service Bus extension. If you’re looking for a complete code sample, you can find it in the Azure Service Bus sample.

Installation

Add a dependency on io.quarkiverse.azureservices:quarkus-azure-servicebus.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.azureservices</groupId>
    <artifactId>quarkus-azure-servicebus</artifactId>
    <version>1.1.6</version>
</dependency>

How to Use It

Once you have added the extension to your project, follow the next steps, so you can inject com.azure.messaging.servicebus.ServiceBusClientBuilder object in your application to create clients for producing and consuming messages from Azure Service Bus.

Setup your Azure Environment

First thing first. For this sample to work, you need to have an Azure account as well as Azure CLI installed. The Azure CLI is available to install in Windows, macOS and GNU/Linux environments. Checkout the installation guide. Then, you need an Azure subscription and log into it by using the az login command. You can run az version to find the version and az upgrade to upgrade to the latest version.

Create an Azure resource group with the az group create command. A resource group is a logical container into which Azure resources are deployed and managed.

az group create \
    --name rg-quarkus-azure-servicebus \
    --location westus

Create an Azure Service Bus namespace and a queue with the following commands:

az servicebus namespace create \
    --name sbnamespace20250604 \
    --resource-group rg-quarkus-azure-servicebus

az servicebus queue create \
    --name test-queue \
    --namespace-name sbnamespace20250604 \
    --resource-group rg-quarkus-azure-servicebus

If you log into the Azure portal, you can see the resource group and the Azure Service Bus namespace you created.

Configure the Azure Service Bus Client Builder

As you can see below in the Extension Configuration Reference section, either the property quarkus.azure.servicebus.namespace or the property quarkus.azure.servicebus.connection-string is required if the extension is enabled.

You have two options to authenticate to Azure Service Bus, either with Microsoft Entra ID or connection string. The following sections describe how to authenticate with both options. For optimal security, it is recommended to use Microsoft Entra ID for authentication.

Authenticating to Azure Service Bus with Microsoft Entra ID

You can authenticate to Azure Service Bus with Microsoft Entra ID. Run the following commands to assign the Azure Service Bus Data Owner role to the signed-in user as a Microsoft Entra identity.

SERVICEBUS_RESOURCE_ID=$(az servicebus namespace show \
    --resource-group rg-quarkus-azure-servicebus \
    --name sbnamespace20250604 \
    --query 'id' \
    --output tsv)
OBJECT_ID=$(az ad signed-in-user show --query id -o tsv)

az role assignment create \
    --role "Azure Service Bus Data Owner" \
    --assignee ${OBJECT_ID} \
    --scope $SERVICEBUS_RESOURCE_ID

Run the following commands to export the namespace of the Azure Service Bus as an environment variable.

export QUARKUS_AZURE_SERVICEBUS_NAMESPACE=sbnamespace20250604

The value of environment variable QUARKUS_AZURE_SERVICEBUS_NAMESPACE will be read by Quarkus as the value of config property quarkus.azure.servicebus.namespace of azure-servicebus extension in order to set up the connection to the Azure Service Bus.

Authenticating to Azure Service Bus with connection string

You can also authenticate to Azure Service Bus with connection string. Run the following commands to export the connection string of the Azure Service Bus as an environment variable.

export QUARKUS_AZURE_SERVICEBUS_CONNECTION_STRING=$(az servicebus namespace authorization-rule keys list \
    --resource-group rg-quarkus-azure-servicebus \
    --namespace-name sbnamespace20250604 \
    --name RootManageSharedAccessKey \
    --query primaryConnectionString -o tsv)

The value of environment variable QUARKUS_AZURE_SERVICEBUS_CONNECTION_STRING will be read by Quarkus as the value of config property quarkus.azure.servicebus.connection-string of azure-servicebus extension in order to set up the connection to the Azure Service Bus.

Inject the Azure Service Bus Client Builder

Now that your Azure environment is ready and you have configured the extension, you can @Inject the com.azure.messaging.servicebus.ServiceBusClientBuilder object in your application, so you can create clients to interact with Azure Servie Bus. For complete API see the Azure SDK for Java Reference Documentation.

Use the ServiceBusClientBuilder to create clients

@ApplicationScoped
public class ServiceBusManager {

    private static final Logger LOG = Logger.getLogger(ServiceBusManager.class);

    @ConfigProperty(name = "quarkus.azure.servicebus.queue-name", defaultValue = "test-queue")
    private String queueName;

    @Inject
    private ServiceBusClientBuilder clientBuilder;

    private ServiceBusSenderClient senderClient;
    private ServiceBusProcessorClient processorClient;

    // Thread-safe list to store received messages for testing
    private final List<String> receivedMessages = new CopyOnWriteArrayList<>();

    @PostConstruct
    void initialize() {
        LOG.info("Initializing Azure Service Bus clients");

        // Initialize sender client
        senderClient = clientBuilder
                .sender()
                .queueName(queueName)
                .buildClient();

        // Initialize processor client with message handler
        processorClient = clientBuilder
                .processor()
                .queueName(queueName)
                .receiveMode(ServiceBusReceiveMode.RECEIVE_AND_DELETE)
                .processMessage(context -> {
                    String body = context.getMessage().getBody().toString();
                    receivedMessages.add(body);
                    LOG.infof("Received message: %s", body);
                })
                .processError(context -> {
                    LOG.errorf("Error occurred: %s", context.getException());
                })
                .disableAutoComplete()
                .buildProcessorClient();

        // Start processing messages
        processorClient.start();

        LOG.info("Azure Service Bus clients initialized successfully");
    }

    @PreDestroy
    void cleanup() {
        LOG.info("Cleaning up Azure Service Bus clients");

        if (processorClient != null) {
            processorClient.close();
        }

        if (senderClient != null) {
            senderClient.close();
        }

        LOG.info("Azure Service Bus clients cleaned up successfully");
    }

    public void sendMessage(String messageBody) {
        LOG.infof("Sending message: %s", messageBody);

        ServiceBusMessage message = new ServiceBusMessage(messageBody);
        senderClient.sendMessage(message);

        LOG.info("Message sent successfully");
    }

    public List<String> getReceivedMessages() {
        return List.copyOf(receivedMessages);
    }
}

Send and retrieve messages in a REST resource

@Path("/quarkus-azure-servicebus")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ServiceBusResource {

    private static final Logger LOG = Logger.getLogger(ServiceBusResource.class);

    @Inject
    ServiceBusManager serviceBusManager;

    @POST
    @Path("/messages")
    public Response sendMessage(Map<String, String> request) {
        String message = request.get("message");
        LOG.infof("REST request to send message: %s", message);
        serviceBusManager.sendMessage(message);

        return Response.ok(Map.of(
                "status", "success",
                "message", "Message sent successfully")).build();
    }

    @GET
    @Path("/messages")
    public Response getMessages() {
        List<String> messages = serviceBusManager.getReceivedMessages();
        LOG.infof("REST request to get messages, returning %d messages", messages.size());

        return Response.ok(Map.of(
                "status", "success",
                "count", messages.size(),
                "messages", messages)).build();
    }
}

To test this sample you can run the following cURL commands after the application is started:

You should see similar outputs:

{"status":"success","message":"Message sent successfully"}
{"messages":["Hello Azure Service Bus!"],"status":"success","count":1}

When you’re done with the example and no longer need the Azure resources, run the following command to clean up the Azure resources you created before:

az group delete \
    --name rg-quarkus-azure-servicebus \
    --yes --no-wait

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.azure.servicebus.devservices.enabled

Whether Dev Services should be enabled or not. Dev Services are enabled by default unless a specific Azure Service Bus connection exists.

When Dev Services are enabled, Quarkus will attempt to automatically configure and start an Azure Service Bus emulator instance and an associated MSSQL Server when running in dev or test mode and when Docker is running. quarkus.azure.servicebus.connection-string will be set to point to the emulator.

Environment variable: QUARKUS_AZURE_SERVICEBUS_DEVSERVICES_ENABLED

boolean

true

quarkus.azure.servicebus.devservices.license-accepted

To use the Service Bus Dev Services, you must accept the license terms of the Service Bus emulator and the Microsoft SQL Server.

Environment variable: QUARKUS_AZURE_SERVICEBUS_DEVSERVICES_LICENSE_ACCEPTED

boolean

false

quarkus.azure.servicebus.enabled

The flag to enable the extension. If set to false, the CDI producers will be disabled.

This flag does not affect Dev Services. To disable Dev Services, you must explicitly set either quarkus.azure.servicebus.devservices.enabled or quarkus.devservices.enabled to false.

Environment variable: QUARKUS_AZURE_SERVICEBUS_ENABLED

boolean

true

quarkus.azure.servicebus.connection-string

Connect to the Service Bus using this connection string. If set, authentication is handled by the SAS key in the connection string. Otherwise, a DefaultAzureCredentialBuilder will be used for authentication, and namespace and domain have to be configured.

Environment variable: QUARKUS_AZURE_SERVICEBUS_CONNECTION_STRING

string

quarkus.azure.servicebus.namespace

The namespace of the Service Bus. The domain name is appended to this value to form the fully qualified namespace name.

Environment variable: QUARKUS_AZURE_SERVICEBUS_NAMESPACE

string

quarkus.azure.servicebus.domain-name

The domain name of the Service Bus. The domain name is appended to the namespace to form the fully qualified namespace name.

Environment variable: QUARKUS_AZURE_SERVICEBUS_DOMAIN_NAME

string

servicebus.windows.net