feat: implement automatic batching for SQS operations using SqsAsyncBatchManager

Author: khc41

docs/src/main/asciidoc/sqs.adoc

@@ -806,6 +806,130 @@ NOTE: The same factory can be used to create both `single message` and `batch` c
 
 IMPORTANT: In case the same factory is shared by both delivery methods, any supplied `ErrorHandler`, `MessageInterceptor` or `MessageListener` should implement the proper methods.
 
+==== Automatic Batching with AWS SDK
+
+Spring Cloud AWS supports automatic message batching using AWS SDK's `SqsAsyncBatchManager`. This feature optimizes SQS operations by automatically batching requests under the hood to improve performance and reduce AWS API calls.
+
+IMPORTANT: This is different from the <<Batch Processing,Batch Processing>> feature described above. Batch Processing refers to processing multiple messages in a single listener method call, while Automatic Batching refers to the AWS SDK automatically combining multiple SQS API calls into batched requests for efficiency.
+
+===== Enabling Automatic Batching
+
+To enable automatic batching, set the following property:
+
+[source,properties]
+----
+spring.cloud.aws.sqs.batch.enabled=true
+----
+
+When enabled, Spring Cloud AWS will automatically wrap the `SqsAsyncClient` with a `BatchingSqsClientAdapter` that uses `SqsAsyncBatchManager` internally.
+
+===== Configuration Properties
+
+The following properties can be used to configure the batching behavior:
+
+[source,properties]
+----
+# Enable automatic batching (default: false)
+spring.cloud.aws.sqs.batch.enabled=true
+
+# Maximum number of messages in a batch (default: AWS SDK default, max: 10)
+spring.cloud.aws.sqs.batch.max-number-of-messages=10
+
+# Frequency at which batched requests are sent (default: AWS SDK default)
+spring.cloud.aws.sqs.batch.send-batch-frequency=PT0.2S
+
+# Visibility timeout for received messages (default: queue default)
+spring.cloud.aws.sqs.batch.visibility-timeout=PT30S
+
+# Wait time for receiveMessage requests (default: AWS SDK default)
+spring.cloud.aws.sqs.batch.wait-time-seconds=PT5S
+
+# System attributes to request for receiveMessage calls
+spring.cloud.aws.sqs.batch.system-attribute-names=SentTimestamp,ApproximateReceiveCount
+
+# Message attributes to request for receiveMessage calls
+spring.cloud.aws.sqs.batch.attribute-names=MessageGroupId,MessageDeduplicationId
+----
+
+===== Important Considerations
+
+WARNING: When using automatic batching, operations are processed asynchronously by the AWS SDK. This means that a method call may return successfully, but the actual request to AWS SQS might fail later during the batching process. This can result in **false positives** where operations appear to succeed locally but fail during transmission.
+
+Applications should:
+
+- **Always handle the returned `CompletableFuture`** to detect actual transmission errors
+- **Implement appropriate error handling and monitoring** to detect delayed failures
+- **Consider retry mechanisms** for critical operations
+
+IMPORTANT: **Batch Manager Bypass**: The AWS SDK batch manager will bypass batching and send regular asynchronous requests when `receiveMessage` is called with any of the following parameters:
+
+- `messageAttributeNames`
+- `messageSystemAttributeNames` 
+- `messageSystemAttributeNamesWithStrings` (not used in Spring Cloud AWS `ReceiveMessageRequest`)
+- `overrideConfiguration` (not used in Spring Cloud AWS `ReceiveMessageRequest`)
+
+When these parameters are used, the performance benefits of batching are lost for those specific requests. 
+
+**Note**: When using Spring Cloud AWS's automatic batching feature, `SqsTemplate` automatically excludes `messageAttributeNames` and `messageSystemAttributeNames` from individual `receiveMessage` requests to maintain batching efficiency. These attributes should be configured globally in the batch configuration instead:
+
+[source,properties]
+----
+# Configure globally for batched requests
+spring.cloud.aws.sqs.batch.system-attribute-names=SentTimestamp,ApproximateReceiveCount
+spring.cloud.aws.sqs.batch.attribute-names=MessageGroupId,MessageDeduplicationId
+----
+
+If you need to use different attribute configurations per request, consider disabling automatic batching and using the standard `SqsAsyncClient` instead.
+
+Example of proper error handling:
+
+[source,java]
+----
+@Service
+public class MessageService {
+    
+    private final SqsTemplate sqsTemplate;
+    
+    public MessageService(SqsTemplate sqsTemplate) {
+        this.sqsTemplate = sqsTemplate;
+    }
+    
+    public void sendMessage(String queueName, String message) {
+        CompletableFuture<SendResult<String>> future = sqsTemplate.sendAsync(queueName, message);
+        
+        future.whenComplete((result, throwable) -> {
+            if (throwable != null) {
+                // Handle actual transmission error
+                log.error("Failed to send message to queue {}: {}", queueName, throwable.getMessage());
+                // Implement retry or alternative handling logic
+            } else {
+                // Message sent successfully
+                log.info("Message sent successfully with ID: {}", result.messageId());
+            }
+        });
+    }
+}
+----
+
+===== Performance Benefits
+
+Automatic batching provides several benefits:
+
+- **Reduced API calls**: Multiple operations are combined into single API calls
+- **Lower costs**: Fewer API calls result in reduced AWS charges
+- **Improved throughput**: Batching reduces network overhead and latency
+- **Better resource utilization**: More efficient use of network and AWS resources
+
+===== Compatibility
+
+Automatic batching is compatible with:
+
+- `SqsTemplate` for sending and receiving messages
+- `@SqsListener` methods for message processing
+- Both standard and FIFO queues
+- All message conversion and error handling features
+
+The batching is transparent to application code - existing `SqsTemplate` and `@SqsListener` code continues to work without changes.
 
 ==== Container Options
 
@@ -877,6 +1001,13 @@ The Spring Boot Starter for SQS provides the following auto-configuration proper
 | `spring.cloud.aws.sqs.listener.auto-startup` | Defines whether SQS listeners are started automatically or not. | No | true
 | `spring.cloud.aws.sqs.queue-not-found-strategy`  | The strategy to be used by SqsTemplate and SqsListeners when a queue does not exist. | No | CREATE
 | `spring.cloud.aws.sqs.observation-enabled` | Enables observability support for SQS operations. | No | false
+| `spring.cloud.aws.sqs.batch.enabled` | Enables automatic SQS batching using AWS SDK's SqsAsyncBatchManager. | No | `false`
+| `spring.cloud.aws.sqs.batch.max-number-of-messages` | Maximum number of messages in a batch (max: 10). | No | AWS SDK default
+| `spring.cloud.aws.sqs.batch.send-batch-frequency` | Frequency at which batched requests are sent. | No | AWS SDK default
+| `spring.cloud.aws.sqs.batch.visibility-timeout` | Visibility timeout for received messages in batch. | No | Queue default
+| `spring.cloud.aws.sqs.batch.wait-time-seconds` | Wait time for receiveMessage requests in batch. | No | AWS SDK default
+| `spring.cloud.aws.sqs.batch.system-attribute-names` | System attributes to request for receiveMessage calls. | No | None
+| `spring.cloud.aws.sqs.batch.attribute-names` | Message attributes to request for receiveMessage calls. | No | None
 |===
 
 

spring-cloud-aws-autoconfigure/src/main/java/io/awspring/cloud/autoconfigure/sqs/SqsProperties.java

@@ -169,10 +169,30 @@ public void setAutoStartup(Boolean autoStartup) {
 
 	}
 
+	/**
+	 * Configuration properties for SQS automatic batching using AWS SDK's {@code SqsAsyncBatchManager}.
+	 * 
+	 * <p>Automatic batching improves performance and reduces costs by combining multiple SQS requests
+	 * into fewer AWS API calls. When enabled, Spring Cloud AWS will use a {@code BatchingSqsClientAdapter}
+	 * that wraps the standard {@code SqsAsyncClient} with batching capabilities.
+	 * 
+	 * <p><strong>Important:</strong> Batched operations are processed asynchronously, which may result
+	 * in false positives where method calls appear to succeed locally but fail during actual transmission
+	 * to AWS. Applications should handle the returned {@code CompletableFuture} objects to detect
+	 * actual transmission errors.
+	 * 
+	 * @since 3.2
+	 */
 	public static class Batch {
 
 		/**
 		 * Enables SQS automatic batching using AWS SDK's SqsAsyncBatchManager.
+		 * 
+		 * <p>When set to {@code true}, the {@code SqsAsyncClient} bean will be wrapped
+		 * with a {@code BatchingSqsClientAdapter} that automatically batches requests
+		 * to improve performance and reduce AWS API calls.
+		 * 
+		 * <p>Default is {@code false}.
 		 */
 		private boolean enabled = false;
 

spring-cloud-aws-autoconfigure/src/test/java/io/awspring/cloud/autoconfigure/sqs/SqsAutoConfigurationTest.java

@@ -70,6 +70,7 @@
  *
  * @author Tomaz Fernandes
  * @author Wei Jiang
+ * @author khc41
  */
 class SqsAutoConfigurationTest {
 

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/operations/BatchingSqsClientAdapter.java

@@ -1,15 +1,82 @@
+/*
+ * Copyright 2013-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package io.awspring.cloud.sqs.operations;
 
+import org.springframework.util.Assert;
 import software.amazon.awssdk.services.sqs.SqsAsyncClient;
 import software.amazon.awssdk.services.sqs.batchmanager.SqsAsyncBatchManager;
 import software.amazon.awssdk.services.sqs.model.*;
 
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
 
+/**
+ * An {@link SqsAsyncClient} adapter that provides automatic batching capabilities using AWS SDK's
+ * {@link SqsAsyncBatchManager}.
+ * 
+ * <p>This adapter automatically batches SQS operations to improve performance and reduce costs by
+ * combining multiple requests into fewer AWS API calls. All standard SQS operations are supported:
+ * send message, receive message, delete message, and change message visibility.
+ * 
+ * <p><strong>Important - False Positives Warning:</strong> This adapter processes requests 
+ * asynchronously through batching. Method calls may return successfully before the actual request 
+ * is sent to AWS SQS. This can result in false positives where the operation appears to succeed 
+ * locally but fails during the actual transmission to AWS. Applications should:
+ * <ul>
+ * <li>Always handle the returned {@link CompletableFuture} to detect actual transmission errors</li>
+ * <li>Implement appropriate error handling and monitoring</li>
+ * <li>Consider retry mechanisms for critical operations</li>
+ * </ul>
+ * 
+ * <p><strong>Batch Optimization:</strong> The AWS SDK bypasses batching when {@code receiveMessage} is 
+ * called with any of the following parameters: {@code messageAttributeNames}, {@code messageSystemAttributeNames}, 
+ * {@code messageSystemAttributeNamesWithStrings}, or {@code overrideConfiguration}. To maintain consistent 
+ * batching performance, Spring Cloud AWS handles these parameters as follows:
+ * <ul>
+ * <li>{@code messageAttributeNames} - excluded from per-request, configured globally via {@code spring.cloud.aws.sqs.batch.attribute-names}</li>
+ * <li>{@code messageSystemAttributeNames} - excluded from per-request, configured globally via {@code spring.cloud.aws.sqs.batch.system-attribute-names}</li>
+ * <li>{@code messageSystemAttributeNamesWithStrings} - not used in Spring Cloud AWS {@code ReceiveMessageRequest}</li>
+ * <li>{@code overrideConfiguration} - not used in Spring Cloud AWS {@code ReceiveMessageRequest}</li>
+ * </ul>
+ * <p>This design prevents batch bypass and ensures optimal performance. 
+ * If per-request attribute configuration is required, consider disabling automatic batching.
+ * 
+ * <p>This adapter is automatically configured by Spring Cloud AWS when automatic batching is enabled.
+ * Users do not need to create instances directly - instead, enable batching through configuration:
+ * 
+ * <pre>
+ * spring.cloud.aws.sqs.batch.enabled=true
+ * </pre>
+ * 
+ * <p>Once enabled, all {@code SqsTemplate} operations will automatically use batching transparently.
+ * 
+ * @author khc41
+ * @since 3.2
+ * @see SqsAsyncBatchManager
+ * @see SqsAsyncClient
+ */
 public class BatchingSqsClientAdapter implements SqsAsyncClient {
 	private final SqsAsyncBatchManager batchManager;
 
+	/**
+	 * Creates a new {@code BatchingSqsClientAdapter} with the specified batch manager.
+	 * 
+	 * @param batchManager the {@link SqsAsyncBatchManager} to use for batching operations
+	 * @throws IllegalArgumentException if batchManager is null
+	 */
 	public BatchingSqsClientAdapter(SqsAsyncBatchManager batchManager) {
 		Assert.notNull(batchManager, "batchManager cannot be null");
 		this.batchManager = batchManager;
@@ -20,46 +87,126 @@ public String serviceName() {
 		return SqsAsyncClient.SERVICE_NAME;
 	}
 
+	/**
+	 * Closes the underlying batch manager and releases associated resources.
+	 * 
+	 * <p>This method should be called when the adapter is no longer needed to ensure
+	 * proper cleanup of threads and connections.
+	 */
 	@Override
 	public void close() {
 		batchManager.close();
 	}
 
+	/**
+	 * Sends a message to the specified SQS queue using automatic batching.
+	 * 
+	 * <p><strong>Important:</strong> This method returns immediately, but the actual sending
+	 * is performed asynchronously. Handle the returned {@link CompletableFuture} to detect
+	 * transmission errors.
+	 * 
+	 * @param sendMessageRequest the request containing queue URL and message details
+	 * @return a {@link CompletableFuture} that completes with the send result
+	 */
 	@Override
 	public CompletableFuture<SendMessageResponse> sendMessage(SendMessageRequest sendMessageRequest) {
 		return batchManager.sendMessage(sendMessageRequest);
 	}
 
+	/**
+	 * Sends a message to the specified SQS queue using automatic batching.
+	 * 
+	 * <p><strong>Important:</strong> This method returns immediately, but the actual sending
+	 * is performed asynchronously. Handle the returned {@link CompletableFuture} to detect
+	 * transmission errors.
+	 * 
+	 * @param sendMessageRequest a consumer to configure the send message request
+	 * @return a {@link CompletableFuture} that completes with the send result
+	 */
 	@Override
 	public CompletableFuture<SendMessageResponse> sendMessage(Consumer<SendMessageRequest.Builder> sendMessageRequest) {
 		return batchManager.sendMessage(sendMessageRequest);
 	}
 
+	/**
+	 * Receives messages from the specified SQS queue using automatic batching.
+	 * 
+	 * <p>The batching manager may combine multiple receive requests to optimize
+	 * AWS API usage.
+	 * 
+	 * @param receiveMessageRequest the request containing queue URL and receive options
+	 * @return a {@link CompletableFuture} that completes with the received messages
+	 */
 	@Override
 	public CompletableFuture<ReceiveMessageResponse> receiveMessage(ReceiveMessageRequest receiveMessageRequest) {
 		return batchManager.receiveMessage(receiveMessageRequest);
 	}
 
+	/**
+	 * Receives messages from the specified SQS queue using automatic batching.
+	 * 
+	 * <p>The batching manager may combine multiple receive requests to optimize
+	 * AWS API usage.
+	 * 
+	 * @param receiveMessageRequest a consumer to configure the receive message request
+	 * @return a {@link CompletableFuture} that completes with the received messages
+	 */
 	@Override
 	public CompletableFuture<ReceiveMessageResponse> receiveMessage(Consumer<ReceiveMessageRequest.Builder> receiveMessageRequest) {
 		return batchManager.receiveMessage(receiveMessageRequest);
 	}
 
+	/**
+	 * Deletes a message from the specified SQS queue using automatic batching.
+	 * 
+	 * <p><strong>Important:</strong> The actual deletion may be delayed due to batching.
+	 * Handle the returned {@link CompletableFuture} to confirm successful deletion.
+	 * 
+	 * @param deleteMessageRequest the request containing queue URL and receipt handle
+	 * @return a {@link CompletableFuture} that completes with the deletion result
+	 */
 	@Override
 	public CompletableFuture<DeleteMessageResponse> deleteMessage(DeleteMessageRequest deleteMessageRequest) {
 		return batchManager.deleteMessage(deleteMessageRequest);
 	}
 
+	/**
+	 * Deletes a message from the specified SQS queue using automatic batching.
+	 * 
+	 * <p><strong>Important:</strong> The actual deletion may be delayed due to batching.
+	 * Handle the returned {@link CompletableFuture} to confirm successful deletion.
+	 * 
+	 * @param deleteMessageRequest a consumer to configure the delete message request
+	 * @return a {@link CompletableFuture} that completes with the deletion result
+	 */
 	@Override
 	public CompletableFuture<DeleteMessageResponse> deleteMessage(Consumer<DeleteMessageRequest.Builder> deleteMessageRequest) {
 		return batchManager.deleteMessage(deleteMessageRequest);
 	}
 
+	/**
+	 * Changes the visibility timeout of a message in the specified SQS queue using automatic batching.
+	 * 
+	 * <p>The batching manager may combine multiple visibility change requests to optimize
+	 * AWS API usage.
+	 * 
+	 * @param changeMessageVisibilityRequest the request containing queue URL, receipt handle, and new timeout
+	 * @return a {@link CompletableFuture} that completes with the visibility change result
+	 */
 	@Override
 	public CompletableFuture<ChangeMessageVisibilityResponse> changeMessageVisibility(ChangeMessageVisibilityRequest changeMessageVisibilityRequest) {
 		return batchManager.changeMessageVisibility(changeMessageVisibilityRequest);
 	}
 
+	/**
+	 * Changes the visibility timeout of a message in the specified SQS queue using automatic batching.
+	 * 
+	 * <p>The batching manager may combine multiple visibility change requests to optimize
+	 * AWS API usage.
+	 * 
+	 * @param changeMessageVisibilityRequest a consumer to configure the change visibility request
+	 * @return a {@link CompletableFuture} that completes with the visibility change result
+	 */
 	@Override
 	public CompletableFuture<ChangeMessageVisibilityResponse> changeMessageVisibility(Consumer<ChangeMessageVisibilityRequest.Builder> changeMessageVisibilityRequest) {
 		return batchManager.changeMessageVisibility(changeMessageVisibilityRequest);