Stop Fighting Your Message Broker: Azure Service Bus with Spring

I still remember the exact moment I decided I was done managing my own message brokers. It was 2019, and I was staring at a RabbitMQ cluster that had decided to split-brain right in the middle of a Black Friday load test. Since then, I’ve shifted almost entirely to managed services. If you are working in the Java ecosystem today, specifically with Spring Boot, the integration with Azure Service Bus has reached a level of maturity that makes it genuinely hard to justify rolling your own infrastructure.

I’ve been spending the last few weeks refactoring a legacy monolithic application into a set of Java Microservices, and the glue holding it all together is the Azure SDK for Java. Specifically, the Spring Cloud Azure starters. It’s not just about moving bytes from point A to point B; it’s about how little code I actually have to write to make that happen securely and reliably.

Why I Choose Managed Messaging over DIY

When I build a Java Backend, I want to focus on business logic, not the intricacies of AMQP protocol handshakes. Azure Service Bus provides that enterprise-grade reliability—transactions, ordering, dead-lettering—out of the box. But the real magic happens when you pull in the Spring Cloud Azure libraries.

In the past, connecting Java to Azure meant writing a lot of boilerplate code to handle authentication, connection strings, and retry policies. Now, with the Passwordless connections using Managed Identity, I don’t even manage secrets anymore. It just works. The SDK handles the token acquisition and rotation behind the scenes.

Setting Up the Foundation

Let’s look at a practical setup. I use Maven for dependency management. While Gradle is great, I find the declarative nature of Maven’s POM easier to manage across large teams. To get started, you need the Bill of Materials (BOM) and the specific starter.

Here is what my pom.xml looks like for a standard Spring Boot 3.x application running on Java 21:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure.spring</groupId>
            <artifactId>spring-cloud-azure-dependencies</artifactId>
            <version>5.20.0</version> <!-- Always check for the latest stable version -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.azure.spring</groupId>
        <artifactId>spring-cloud-azure-starter-servicebus</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

Once the dependencies are in, configuration is minimal. I prefer using YAML for my properties. The key here is that I am not pasting a connection string. I’m running this on Azure Container Apps, so I rely on the workload identity.

spring:
  cloud:
    azure:
      servicebus:
        namespace: my-servicebus-namespace.servicebus.windows.net
        entity-type: queue
        producer:
          entity-name: orders-queue

The Producer: Sending Events with Style

I see a lot of developers still using the older JmsTemplate approach. While that works for migration, if you are building greenfield, I recommend using the ServiceBusTemplate. It offers more control over the Azure-specific headers and metadata.

Let’s define a domain object first. I use Java Records because they are immutable and concise—perfect for Data Transfer Objects (DTOs) in a Java Microservices architecture.

package com.example.orders.domain;

import java.math.BigDecimal;
import java.time.Instant;

public record OrderEvent(
    String orderId,
    String customerId,
    BigDecimal totalAmount,
    Instant timestamp,
    OrderStatus status
) {
    public enum OrderStatus {
        CREATED, PENDING, SHIPPED
    }
}

Now, let’s build the producer service. I like to wrap the ServiceBusTemplate in my own service interface to decouple the infrastructure from my business logic. This helps immensely with Java Testing later, as I can easily mock the interface with Mockito.

package com.example.orders.service;

import com.azure.spring.messaging.servicebus.core.ServiceBusTemplate;
import com.example.orders.domain.OrderEvent;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.messaging.Message;
import org.springframework.messaging.support.MessageBuilder;
import org.springframework.stereotype.Service;

import java.util.UUID;

@Service
public class OrderPublisher {

    private static final Logger log = LoggerFactory.getLogger(OrderPublisher.class);
    private final ServiceBusTemplate serviceBusTemplate;

    public OrderPublisher(ServiceBusTemplate serviceBusTemplate) {
        this.serviceBusTemplate = serviceBusTemplate;
    }

    public void publishOrder(OrderEvent event) {
        log.info("Publishing order event for ID: {}", event.orderId());

        // Create a Spring Message with custom headers
        Message<OrderEvent> message = MessageBuilder
                .withPayload(event)
                .setHeader("messageId", UUID.randomUUID().toString())
                .setHeader("eventType", "OrderCreated")
                .build();

        // Send asynchronously
        serviceBusTemplate.sendAsync("orders-queue", message)
                .subscribe(
                    success -> log.info("Message sent successfully"),
                    error -> log.error("Failed to send message", error)
                );
    }
}

Notice the use of sendAsync. In a high-throughput Java Cloud environment, blocking the thread while waiting for the broker to acknowledge receipt is a performance killer. I use the reactive flow to handle the completion or failure without holding up the HTTP request thread.

The Consumer: Processing with Checkpoints

Consuming messages is where things usually get tricky. You have to handle concurrency, exceptions, and message acknowledgement. If you don’t acknowledge (ack) the message, the broker will redeliver it, potentially causing infinite loops if your code has a bug.

The Spring Cloud Azure starter simplifies this with the @ServiceBusListener annotation. It handles the deserialization and the concurrency for you. However, I always disable auto-complete. I prefer to manually complete the message only after my business logic has successfully executed. This ensures I have “at-least-once” delivery guarantees.

package com.example.orders.listener;

import com.azure.spring.messaging.servicebus.support.ServiceBusMessageHeaders;
import com.example.orders.domain.OrderEvent;
import com.azure.spring.messaging.servicebus.implementation.core.annotation.ServiceBusListener;
import org.springframework.messaging.handler.annotation.Header;
import org.springframework.messaging.handler.annotation.Payload;
import org.springframework.stereotype.Component;

@Component
public class OrderProcessor {

    @ServiceBusListener(destination = "orders-queue", autoComplete = "false")
    public void processOrder(
            @Payload OrderEvent event,
            @Header(ServiceBusMessageHeaders.RECEIVED_MESSAGE_CONTEXT) com.azure.spring.messaging.servicebus.support.ServiceBusMessageContext context) {

        try {
            // Simulate business logic
            validateOrder(event);
            saveToDatabase(event);

            // Manually complete the message
            context.complete();
            
        } catch (IllegalArgumentException e) {
            // Logic error: Abandon to Dead Letter Queue immediately
            System.err.println("Invalid order data: " + e.getMessage());
            context.deadLetter();
        } catch (Exception e) {
            // Transient error: Abandon so it can be retried
            System.err.println("Transient failure: " + e.getMessage());
            context.abandon();
        }
    }

    private void validateOrder(OrderEvent event) {
        if (event.totalAmount().signum() <= 0) {
            throw new IllegalArgumentException("Total amount must be positive");
        }
    }

    private void saveToDatabase(OrderEvent event) {
        // JDBC or JPA logic here
        System.out.println("Order " + event.orderId() + " saved.");
    }
}

This pattern is crucial for Java Best Practices in distributed systems. By catching specific exceptions, I can decide whether to retry the message (using abandon()) or send it to the Dead Letter Queue (using deadLetter()). This prevents “poison pill” messages from clogging up the queue and wasting CPU cycles on endless retries.

Leveraging Java Streams for Batch Processing

Sometimes, sending messages one by one isn’t efficient, especially if you are doing a bulk import or nightly reconciliation job. I often use Java Streams to process collections of data and then send them in batches.

Here is a utility method I wrote that takes a list of raw data, transforms it, and sends it to Azure Service Bus in batches to respect the message size limits.

public void batchProcessOrders(List<OrderEvent> orders) {
    // Group orders by customer to maintain ordering affinity if needed
    Map<String, List<OrderEvent>> ordersByCustomer = orders.stream()
            .collect(Collectors.groupingBy(OrderEvent::customerId));

    ordersByCustomer.forEach((customerId, customerOrders) -> {
        // Create a batch
        List<Message<OrderEvent>> batch = customerOrders.stream()
                .filter(o -> o.status() == OrderEvent.OrderStatus.CREATED)
                .map(o -> MessageBuilder.withPayload(o)
                        .setHeader("customerId", customerId)
                        .build())
                .toList();

        // Send the batch
        // Note: In production, you'd check batch size limits (e.g., 256KB or 1MB)
        if (!batch.isEmpty()) {
            serviceBusTemplate.sendAsync("orders-queue", batch).subscribe();
        }
    });
}

Observability and Troubleshooting

One thing that often gets overlooked in Azure Java development is observability. When you have messages flying between services, you need to know where they went. The Spring Cloud Azure starter integrates automatically with Micrometer.

I enable Application Insights in my Java Cloud configuration. Without writing any extra code, I get distributed tracing. I can see the HTTP request come into my API, the message being produced to the Service Bus, and the consumer picking it up in another service. This visual map is invaluable when debugging performance bottlenecks or stuck messages.

Handling Configuration Drift

A common pain point I’ve encountered is configuration drift. You change a queue name in Terraform, but forget to update the application.yaml. To mitigate this, I use Spring Cloud Azure’s integration with Azure App Configuration.

Instead of hardcoding queue names in my code, I inject them. This allows me to change the plumbing without recompiling the application.

@ConfigurationProperties(prefix = "app.messaging")
public record MessagingProperties(
    String orderQueueName,
    String inventoryTopicName
) {}

I then enable the configuration processor in my build. It keeps my Java Architecture clean and separates concerns effectively.

Security Considerations

I cannot stress this enough: stop using connection strings. If you are deploying to Azure, use Managed Identities. It eliminates the risk of leaking credentials in your Git history. In my local development environment, the Azure CLI handles the authentication. When I run az login, the DefaultAzureCredential used by the Java SDK picks up my credentials automatically. It creates a consistent experience from local dev to production.

Final Thoughts on the Ecosystem

The Java ecosystem on Azure has evolved rapidly. A few years ago, it felt like a second-class citizen compared to .NET. Today, with the strong support for Spring Boot, Jakarta EE, and modern Java features, it feels native. The tooling around VS Code and IntelliJ is excellent, and the SDKs are idiomatic.

If you are building Java Microservices, the combination of Spring Boot and Azure Service Bus is a powerhouse. It allows you to build systems that are loosely coupled but highly cohesive. You get the scalability of the cloud with the developer experience of Spring.

I encourage you to look at your current messaging implementation. If you are writing a lot of wrapper code around your message broker, it might be time to let the SDK do the heavy lifting for you. The less infrastructure code I write, the more time I have to solve actual business problems, and that is a trade-off I will take any day.