Use Azure Storage Queue in Spring applications

Prerequisites

An Azure subscription - create one for free .

Java Development Kit (JDK) , version 8 or higher.

An Azure Storage account and Azure Queues. If you don't have these resources, first create a storage account, then create a queue. For more information, see Create a storage account and the Create a queue section of Quickstart: Create a queue and add a message with the Azure portal .

A Spring Boot application. If you don't have one, create a Maven project with the Spring Initializr . Be sure to select Maven Project and, under Dependencies , add the Spring Web dependency, and then select Java version 8 or higher.

To grant your account access to resources, in your newly created Azure Storage account, assign the Storage Queue Data Contributor role to the Azure AD account you're currently using. For more information, see Assign Azure roles using the Azure portal .

Important

Spring Boot version 2.5 or higher is required to complete the steps in this tutorial.

Prepare your local environment

In this tutorial, the configurations and code don't have any authentication operations. However, connecting to an Azure service requires authentication. To complete the authentication, you need to use the Azure Identity client library. Spring Cloud Azure uses DefaultAzureCredential , which the Azure Identity library provides to help you get credentials without any code changes.

DefaultAzureCredential supports multiple authentication methods and determines which method to use at runtime. This approach enables your app to use different authentication methods in different environments - such as local or production environments - without implementing environment-specific code. For more information, see the DefaultAzureCredential section of Authenticate Azure-hosted Java applications .

To use Azure CLI, IntelliJ, or other methods to complete the authentication in local development environments, see Azure authentication in Java development environments . To complete the authentication in Azure hosting environments, we recommend using managed identity. For more information, see What are managed identities for Azure resources?

Use Spring Cloud Azure Storage Queue Starter

The Spring Cloud Azure Storage Queue Starter module imports Azure Storage Queue client library for Java with the Spring Boot framework. You can use Spring Cloud Azure and the Azure SDK together, in a non-mutually-exclusive pattern. Thus, you can continue using the Storage Queue Java client API in your Spring application.

Add dependencies

To install the Spring Cloud Azure Storage Queue Starter module, add the following dependencies to your pom.xml file:

The Spring Cloud Azure Bill of Materials (BOM):

<dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.azure.spring</groupId>
       <artifactId>spring-cloud-azure-dependencies</artifactId>
       <version>4.7.0</version>
       <type>pom</type>
       <scope>import</scope>
       </dependency>
   </dependencies>
</dependencyManagement>
The Spring Cloud Azure Queue Storage Queue artifact:
<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-storage-queue</artifactId>
</dependency>
Code your application to send and receive messages
This section shows you how to use the Azure Queue Storage clients in the context of a Spring application. You have the following two options:
Use Spring Boot autoconfiguration and use out-of-the-box clients from the Spring context (recommended).
Build the client programmatically.
With autoconfiguration, you autowire client beans from the Spring inversion-of-control (IoC) container. This approach provides you with a more flexible and efficient experience when developing with Storage Queue clients. Autoconfiguration has the following advantages:
Autoconfiguration uses externalized configuration so that you can work with the same application code in different environments.
You can delegate to the Spring Boot framework the process of learning the builder pattern and registering the clients to the application context. You focus only on how to use the clients with your own business requirements.
You can use health indicator to inspect the status and health of your application and internal components.
The code examples in the following sections show you how to use QueueClient with the two alternatives described.
Azure Java SDK for Storage Queue provides multiple clients to interact with Storage Queue. The starter also provides autoconfiguration for all the Storage Queue clients and client builders. This article uses only QueueClient as an example.
Use Spring Boot autoconfiguration
To send messages to and receive messages from Azure Storage queues, use the following steps to configure the application:
Configure your storage account name and queue name, as shown in the following example:
spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
spring.cloud.azure.storage.queue.queue-name=<your-storage-queue-name>
Inject the QueueClient in your Spring application and call the related APIs to send messages, as shown in the following example:
import com.azure.storage.queue.QueueClient;
import com.azure.storage.queue.models.QueueMessageItem;
import com.azure.storage.queue.models.SendMessageResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class StorageQueueClientApplication implements CommandLineRunner {
    private final static Logger logger = LoggerFactory.getLogger(StorageQueueClientApplication.class);
    @Autowired
    private QueueClient queueClient;
    public static void main(String[] args) {
        SpringApplication.run(StorageQueueClientApplication.class, args);
    @Override
    public void run(String... args) {
     // Using the QueueClient object, call the create method to create the queue in your storage account.
        queueClient.create();
        SendMessageResult sendMessageResult = queueClient.sendMessage("Hello world");
        logger.info("Send message id: {}", sendMessageResult.getMessageId());
        QueueMessageItem queueMessageItem = queueClient.receiveMessage();
        logger.info("Received message: {}", new String(queueMessageItem.getBody().toBytes()));
Start the application. After launch, the application produces logs similar to the following example:
Send message id: ...
Received message: Hello world
Build the client programmatically
You can build the client beans by yourself, but the process is complicated. In Spring Boot applications, you have to manage properties, learn the builder pattern, and register the clients to your Spring application context. The following steps show you how to do that.
Build the client programmatically in your Spring application, as shown in the following example. Be sure to replace the <storage-account-name> placeholder with your own value.
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.storage.queue.QueueClient;
import com.azure.storage.queue.QueueClientBuilder;
import com.azure.storage.queue.models.QueueMessageItem;
import com.azure.storage.queue.models.SendMessageResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class StorageQueueClientApplication implements CommandLineRunner {
    private final static String queueName = "test-queue";
    private final static String endpoint = "https://<storage-account-name>.queue.core.windows.net/";
    private final static Logger logger = LoggerFactory.getLogger(StorageQueueClientApplication.class);
    QueueClient queueClient = new QueueClientBuilder()
        .endpoint(endpoint)
        .queueName(queueName)
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();
    public static void main(String[] args) {
        SpringApplication.run(StorageQueueClientApplication.class, args);
    @Override
    public void run(String... args) {
     // Using the QueueClient object, call the create method to create the queue in your storage account.
        queueClient.create();
        SendMessageResult sendMessageResult = queueClient.sendMessage("Hello world");
        logger.info("Send message id: {}", sendMessageResult.getMessageId());
        QueueMessageItem queueMessageItem = queueClient.receiveMessage();
        logger.info("Received message: {}", new String(queueMessageItem.getBody().toBytes()));
Start the application. After launch, the application produces logs similar to the following example:
Send message id: ...
Received message: Hello world
The following list shows reasons why this code isn't flexible or graceful:
The storage account and queue names are hard coded.
If you use @Value to get configurations from the Spring environment, you can't have IDE hints in your application.properties file.
If you have a microservice scenario, you must duplicate the code in each project, and it's easy to make mistakes and hard to be consistent.
Fortunately, building the client beans by yourself isn't necessary with Spring Cloud Azure. Instead, you can directly inject them and use the configuration properties that you're already familiar with to configure the storage queue. For more information, see Spring Cloud Azure configuration properties.
Spring Cloud Azure also provides the following global configurations for different scenarios. For more information, see Spring Cloud Azure global configuration properties.
Proxy options.
Retry options.
You can also connect to different Azure clouds. For more information, see Connect to different Azure clouds.
Use Spring Messaging Azure Storage Queue
The Spring Messaging Azure Storage Queue module provides support for the Spring Messaging framework with Azure Queue Storage.
If you're using Spring Messaging Azure Storage Queue, then you can use the StorageQueueTemplate feature to send messages to storage queues asynchronously and synchronously.
The following sections show you how to use Spring Messaging Azure Storage Queue to send messages to and receive messages from storage queues.
Add dependencies
To install the Spring Messaging Azure Storage Queue module, add the following dependencies to your pom.xml file:
The Spring Cloud Azure Bill of Materials (BOM):
<dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.azure.spring</groupId>
       <artifactId>spring-cloud-azure-dependencies</artifactId>
       <version>4.7.0</version>
       <type>pom</type>
       <scope>import</scope>
       </dependency>
   </dependencies>
</dependencyManagement>
The Spring Cloud Azure starter and Spring Messaging Storage Queue artifacts:
<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-messaging-azure-storage-queue</artifactId>
</dependency>
Code your application to send and receive messages
Use the following steps to configure and code your application:
Configure the Azure Storage account name for your storage queues, as shown in the following example:
spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
Wire up a sender and a receiver to send and receive messages with Spring, as shown in the following example. Be sure to replace the <storage-queue-name> placeholder with your own value.
import com.azure.spring.messaging.AzureHeaders;
import com.azure.spring.messaging.checkpoint.Checkpointer;
import com.azure.spring.messaging.storage.queue.core.StorageQueueTemplate;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.messaging.Message;
import org.springframework.messaging.support.MessageBuilder;
import java.time.Duration;
@SpringBootApplication
public class StorageQueueMessagingApplication implements CommandLineRunner {
    private static final Logger LOGGER = LoggerFactory.getLogger(StorageQueueMessagingApplication.class);
    private static final String STORAGE_QUEUE_NAME = "<storage-queue-name>";
    @Autowired
    StorageQueueTemplate storageQueueTemplate;
    public static void main(String[] args) {
        SpringApplication.run(StorageQueueMessagingApplication.class, args);
    @Override
    public void run(String... args) {
        storageQueueTemplate
            .sendAsync(STORAGE_QUEUE_NAME, MessageBuilder.withPayload("Hello world").build())
            .subscribe();
        LOGGER.info("Message was sent successfully.");
        Message<?> message = storageQueueTemplate.receiveAsync(STORAGE_QUEUE_NAME, Duration.ofSeconds(30)).block();
        LOGGER.info("Received message: {}", new String((byte[]) message.getPayload()));
Start the application. After launch, the application produces logs similar to the following example:
Message was sent successfully.
Received message: Hello World
Use Spring Integration Azure Storage Queue
The Spring Integration Azure Storage Queue module provides support for the Spring Integration framework with storage queues.
If your Spring application uses Spring Integration message channels, you can route messages between your message channels and storage queue using channel adapters. An inbound channel adapter forwards messages from a storage queue to a message channel. An outbound channel adapter publishes messages from a message channel to a storage queue.
The following sections show you how to use Spring Integration Azure Storage Queue to send and receive messages to and from storage queues.
Add dependencies
To install the Spring Integration Azure Storage Queue module, add the following dependencies to your pom.xml file:
The Spring Cloud Azure Bill of Materials (BOM):
<dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.azure.spring</groupId>
       <artifactId>spring-cloud-azure-dependencies</artifactId>
       <version>4.7.0</version>
       <type>pom</type>
       <scope>import</scope>
       </dependency>
   </dependencies>
</dependencyManagement>
The Spring Integration Azure Storage Queue artifacts:
<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-integration-storage-queue</artifactId>
</dependency>
Code your application to send and receive messages
Use the following steps to configure and code your application:
Configure the Azure Storage account name for your storage queues.
spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
Create a new QueueReceiveConfiguration Java class as shown in the following example. This class is used to define a message receiver. Be sure to replace the <storage-queue-name> placeholder with your own value.
import com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource;
import com.azure.spring.messaging.AzureHeaders;
import com.azure.spring.messaging.checkpoint.Checkpointer;
import com.azure.spring.messaging.storage.queue.core.StorageQueueTemplate;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.integration.annotation.InboundChannelAdapter;
import org.springframework.integration.annotation.Poller;
import org.springframework.integration.annotation.ServiceActivator;
import org.springframework.messaging.handler.annotation.Header;
@Configuration
public class QueueReceiveConfiguration {
    private static final Logger LOGGER = LoggerFactory.getLogger(QueueReceiveConfiguration.class);
    private static final String STORAGE_QUEUE_NAME = "<storage-queue-name>";
    private static final String INPUT_CHANNEL = "input";
    @Bean
    @InboundChannelAdapter(channel = INPUT_CHANNEL, poller = @Poller(fixedDelay = "1000"))
    public StorageQueueMessageSource storageQueueMessageSource(StorageQueueTemplate storageQueueTemplate) {
        return new StorageQueueMessageSource(STORAGE_QUEUE_NAME, storageQueueTemplate);
    @ServiceActivator(inputChannel = INPUT_CHANNEL)
    public void messageReceiver(byte[] payload, @Header(AzureHeaders.CHECKPOINTER) Checkpointer checkpointer) {
        String message = new String(payload);
        LOGGER.info("Received message: {}", message);
Create a new QueueSendConfiguration Java class as shown in the following example. This class is used to define a message sender. Be sure to replace the <storage-queue-name> placeholder with your own value.
import com.azure.spring.integration.core.handler.DefaultMessageHandler;
import com.azure.spring.messaging.storage.queue.core.StorageQueueTemplate;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.integration.annotation.MessagingGateway;
import org.springframework.integration.annotation.ServiceActivator;
import org.springframework.messaging.MessageHandler;
import org.springframework.util.concurrent.ListenableFutureCallback;
@Configuration
public class QueueSendConfiguration {
    private static final Logger LOGGER = LoggerFactory.getLogger(QueueSendConfiguration.class);
    private static final String STORAGE_QUEUE_NAME = "<storage-queue-name>";
    private static final String OUTPUT_CHANNEL = "output";
    @Bean
    @ServiceActivator(inputChannel = OUTPUT_CHANNEL)
    public MessageHandler messageSender(StorageQueueTemplate storageQueueTemplate) {
        DefaultMessageHandler handler = new DefaultMessageHandler(STORAGE_QUEUE_NAME, storageQueueTemplate);
        handler.setSendCallback(new ListenableFutureCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                LOGGER.info("Message was sent successfully.");
            @Override
            public void onFailure(Throwable ex) {
                LOGGER.info("There was an error sending the message.");
        return handler;
    @MessagingGateway(defaultRequestChannel = OUTPUT_CHANNEL)
    public interface StorageQueueOutboundGateway {
        void send(String text);
Wire up a sender and a receiver to send and receive messages with Spring.
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.annotation.Configuration;
import org.springframework.integration.config.EnableIntegration;
@SpringBootApplication
@EnableIntegration
@Configuration(proxyBeanMethods = false)
public class StorageQueueIntegrationApplication {
    public static void main(String[] args) {
        ConfigurableApplicationContext applicationContext = SpringApplication.run(StorageQueueIntegrationApplication.class, args);
        QueueSendConfiguration.StorageQueueOutboundGateway storageQueueOutboundGateway = applicationContext.getBeanQueueSendConfiguration.StorageQueueOutboundGateway.class);
        storageQueueOutboundGateway.send("Hello World");
Remember to add the @EnableIntegration annotation, which enables the Spring Integration infrastructure.
Start the application. After launch, the application produces logs similar to the following example:
Message was sent successfully.
Received message: Hello World
Deploy to Azure Spring Apps
Now that you have the Spring Boot application running locally, it's time to move it to production. Azure Spring Apps makes it easy to deploy Spring Boot applications to Azure without any code changes. The service manages the infrastructure of Spring applications so developers can focus on their code. Azure Spring Apps provides lifecycle management using comprehensive monitoring and diagnostics, configuration management, service discovery, CI/CD integration, blue-green deployments, and more. To deploy your application to Azure Spring Apps, see Deploy your first application to Azure Spring Apps.
Next steps
Azure for Spring developers
Spring Cloud Azure Storage Queue Samples
See also
For more information about the Spring Boot Starters available for Microsoft Azure, see What is Spring Cloud Azure?