Quarkus Azure Event Hubs 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 Event Hubs is a big data streaming platform and event ingestion service. It can receive and process millions of events per second. This extension allows you to produce and consume events from Azure Event Hubs by injecting com.azure.messaging.eventhubs.EventHubProducerClient, com.azure.messaging.eventhubs.EventHubConsumerClient, com.azure.messaging.eventhubs.EventHubProducerAsyncClient, and com.azure.messaging.eventhubs.EventHubConsumerAsyncClient objects in your Quarkus application.

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

Installation

Add a dependncy on io.quarkiverse.azureservices:quarkus-azure-eventhubs.

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

<dependency>
    <groupId>io.quarkiverse.azureservices</groupId>
    <artifactId>quarkus-azure-eventhubs</artifactId>
    <version>1.0.8</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.eventhubs.EventHubProducerClient or com.azure.messaging.eventhubs.EventHubConsumerClient object in your application to produce and consume events from Azure Event Hubs.

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-eventhubs \
    --location westus

Create an Azure Event Hubs namespace with the following command:

az eventhubs namespace create \
    --name ehnamespace20241217 \
    --resource-group rg-quarkus-azure-eventhubs
az eventhubs eventhub create \
    --name eventhub1217 \
    --namespace-name ${EVENTHUBS_NAMESPACE} \
    --resource-group rg-quarkus-azure-eventhubs \
    --partition-count 2

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

Next, assign the Azure Event Hubs Data Owner role to the signed-in user, so that the sample application can do data plane operations.

EVENTHUBS_EVENTHUB_RESOURCE_ID=$(az eventhubs eventhub show \
    --resource-group rg-quarkus-azure-eventhubs \
    --namespace-name ehnamespace20241217 \
    --name eventhub1217 \
    --query 'id' \
    --output tsv)
az role assignment create \
    --role "Azure Event Hubs Data Owner" \
    --assignee $(az ad signed-in-user show --query 'id' --output tsv) \
    --scope $EVENTHUBS_EVENTHUB_RESOURCE_ID

Configure the Azure Event Hubs Extension

As you can see below in the Extension Configuration Reference section, the property quarkus.azure.eventhubs.namespace and quarkus.azure.eventhubs.event-hub-name are required. Execute the following Azure CLI command to export the environment variables so that the extension can read the values.

export QUARKUS_AZURE_EVENTHUBS_NAMESPACE=${EVENTHUBS_NAMESPACE}
export QUARKUS_AZURE_EVENTHUBS_EVENTHUB_NAME=${EVENTHUBS_EVENTHUB_NAME}

Because Quarkus implements the MicroProfile Config specification, the value of the environment variables QUARKUS_AZURE_EVENTHUBS_NAMESPACE and QUARKUS_AZURE_EVENTHUBS_EVENTHUB_NAME is read as if the properties quarkus.azure.eventhubs.namespace and quarkus.azure.eventhubs.event-hub-name were set in the application.properties file.

Although technically both approaches work, using environment variable is recommended and more secure as there’s no risk of committing the connection string to source control.

Inject the Azure Event Hubs Client

Now that your Azure environment is ready and you have configured the extension, you can @Inject the com.azure.messaging.eventhubs.EventHubProducerClient object in your imperative application or @Inject the com.azure.messaging.eventhubs.EventHubConsumerClient object in your reactive application, so you can interact with Azure Event Hubs. For complete API see the Azure SDK for Java Reference Documentation.

Use the EventHubProducerClient and EventHubConsumerClient in a Quarkus application

@Path("/quarkus-azure-eventhubs")
@ApplicationScoped
public class EventhubsResource {
    private static final Logger LOGGER = LoggerFactory.getLogger(EventhubsResource.class);

    @Inject
    EventHubProducerClient producer;

    @Inject
    EventHubConsumerClient consumer;

    @Path("/publishEvents")
    @GET
    public void publishEvents() {
        List<EventData> allEvents = Arrays.asList(new EventData("Foo"), new EventData("Bar"));
        producer.send(allEvents, new SendOptions().setPartitionId("0"));
    }

    @Path("/consumeEvents")
    @GET
    public void consumeEvents() {

        LOGGER.info("Receiving message using Event Hub consumer client.");
        String PARTITION_ID = "0";
        // Reads events from partition '0' and returns the first 2 received.
        IterableStream<PartitionEvent> events = consumer.receiveFromPartition(PARTITION_ID, 2,
                EventPosition.earliest());

        for (PartitionEvent partitionEvent : events) {
            // For each event, perform some sort of processing.
            LOGGER.info("Message Body received: " + partitionEvent.getData().getBodyAsString());
            LOGGER.info("Message SequenceNumber is: " + partitionEvent.getData().getSequenceNumber());
        }
    }
}

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

You should see similar output in the logs:

Message Body received: Foo
Message SequenceNumber is: 0
Message Body received: Bar
Message SequenceNumber is: 1

Extension Configuration Reference

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

Configuration property

Type

Default

quarkus.azure.eventhubs.enabled

The flag to enable the eventhubs. If set to false, the eventhubs will be disabled

Environment variable: QUARKUS_AZURE_EVENTHUBS_ENABLED

boolean

true

quarkus.azure.eventhubs.namespace

The namespace of the event hub. Required if quarkus.azure.eventhubs.enabled is set to true

Environment variable: QUARKUS_AZURE_EVENTHUBS_NAMESPACE

string

quarkus.azure.eventhubs.domain-name

The domain name of the event hub. Required if quarkus.azure.eventhubs.enabled is set to true

Environment variable: QUARKUS_AZURE_EVENTHUBS_DOMAIN_NAME

string

servicebus.windows.net

quarkus.azure.eventhubs.eventhub-name

The name of the event hub. Required if quarkus.azure.eventhubs.enabled is set to true

Environment variable: QUARKUS_AZURE_EVENTHUBS_EVENTHUB_NAME

string