Refactor: Focus on BatchingSqsClientAdapter;

Author: khc41

docs/src/main/asciidoc/sqs.adoc

@@ -806,6 +806,131 @@ 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
 
 Each `MessageListenerContainer` can have a different set of options.

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

@@ -18,8 +18,10 @@
 import io.awspring.cloud.autoconfigure.AwsClientProperties;
 import io.awspring.cloud.sqs.listener.QueueNotFoundStrategy;
 import java.time.Duration;
+import java.util.List;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.lang.Nullable;
+import software.amazon.awssdk.services.sqs.model.MessageSystemAttributeName;
 
 /**
  * Properties related to AWS SQS.
@@ -38,6 +40,8 @@ public class SqsProperties extends AwsClientProperties {
 
 	private Listener listener = new Listener();
 
+	private Batch batch = new Batch();
+
 	public Listener getListener() {
 		return this.listener;
 	}
@@ -46,6 +50,14 @@ public void setListener(Listener listener) {
 		this.listener = listener;
 	}
 
+	public Batch getBatch() {
+		return batch;
+	}
+
+	public void setBatch(Batch batch) {
+		this.batch = batch;
+	}
+
 	@Nullable
 	private QueueNotFoundStrategy queueNotFoundStrategy;
 
@@ -153,6 +165,155 @@ public Boolean getAutoStartup() {
 		public void setAutoStartup(Boolean autoStartup) {
 			this.autoStartup = 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;
+
+		/**
+		 * The maximum number of messages that can be processed in a single batch. The maximum is 10.
+		 */
+		@Nullable
+		private Integer maxNumberOfMessages;
+
+		/**
+		 * The frequency at which requests are sent to SQS when processing messages in a batch.
+		 */
+		@Nullable
+		private Duration sendBatchFrequency;
+
+		/**
+		 * The visibility timeout to set for messages received in a batch. If unset, the queue default is used.
+		 */
+		@Nullable
+		private Duration visibilityTimeout;
+
+		/**
+		 * The minimum wait duration for a receiveMessage request in a batch. To avoid unnecessary CPU usage, do not set
+		 * this value to 0.
+		 */
+		@Nullable
+		private Duration waitTimeSeconds;
+
+		/**
+		 * The list of system attribute names to request for receiveMessage calls.
+		 */
+		@Nullable
+		private List<MessageSystemAttributeName> systemAttributeNames;
+
+		/**
+		 * The list of attribute names to request for receiveMessage calls.
+		 */
+		@Nullable
+		private List<String> attributeNames;
+
+		/**
+		 * The size of the scheduled thread pool used for batching operations. This thread pool handles periodic batch
+		 * sending and other scheduled tasks.
+		 * 
+		 * <p>
+		 * Default is {@code 5}.
+		 */
+		private int scheduledExecutorPoolSize = 5;
+
+		public boolean isEnabled() {
+			return enabled;
+		}
+
+		public void setEnabled(boolean enabled) {
+			this.enabled = enabled;
+		}
+
+		@Nullable
+		public Integer getMaxNumberOfMessages() {
+			return maxNumberOfMessages;
+		}
+
+		public void setMaxNumberOfMessages(Integer maxNumberOfMessages) {
+			this.maxNumberOfMessages = maxNumberOfMessages;
+		}
+
+		@Nullable
+		public Duration getSendBatchFrequency() {
+			return sendBatchFrequency;
+		}
+
+		public void setSendBatchFrequency(Duration sendBatchFrequency) {
+			this.sendBatchFrequency = sendBatchFrequency;
+		}
+
+		@Nullable
+		public Duration getVisibilityTimeout() {
+			return visibilityTimeout;
+		}
+
+		public void setVisibilityTimeout(Duration visibilityTimeout) {
+			this.visibilityTimeout = visibilityTimeout;
+		}
+
+		@Nullable
+		public Duration getWaitTimeSeconds() {
+			return waitTimeSeconds;
+		}
+
+		public void setWaitTimeSeconds(Duration waitTimeSeconds) {
+			this.waitTimeSeconds = waitTimeSeconds;
+		}
+
+		@Nullable
+		public List<MessageSystemAttributeName> getSystemAttributeNames() {
+			return systemAttributeNames;
+		}
+
+		public void setSystemAttributeNames(List<MessageSystemAttributeName> systemAttributeNames) {
+			this.systemAttributeNames = systemAttributeNames;
+		}
+
+		@Nullable
+		public List<String> getAttributeNames() {
+			return attributeNames;
+		}
+
+		public void setAttributeNames(List<String> attributeNames) {
+			this.attributeNames = attributeNames;
+		}
+
+		public int getScheduledExecutorPoolSize() {
+			return scheduledExecutorPoolSize;
+		}
+
+		public void setScheduledExecutorPoolSize(int scheduledExecutorPoolSize) {
+			this.scheduledExecutorPoolSize = scheduledExecutorPoolSize;
+		}
+
 	}
 
 }