Update documentation to include manual configuration instructions for SQS automatic request batching.

Author: khc41

docs/src/main/asciidoc/sqs.adoc

@@ -812,124 +812,87 @@ Spring Cloud AWS supports automatic message batching using AWS SDK's `SqsAsyncBa
 
 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
+==== Automatic Request Batching with SqsAsyncBatchManager
 
-To enable automatic batching, set the following property:
+Spring Cloud AWS allows you to leverage the AWS SDK's `SqsAsyncBatchManager` for automatic request batching. This feature can significantly improve performance and reduce costs by transparently combining multiple SQS API calls (`sendMessage`, `deleteMessage`, etc.) into single batch requests.
 
-[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
+IMPORTANT: This is different from the <<Batch Processing,Batch Processing>> feature for `@SqsListener`. Listener batch processing deals with handling multiple messages within a single listener invocation, whereas automatic request batching optimizes the underlying API calls to AWS.
 
-# Frequency at which batched requests are sent (default: AWS SDK default)
-spring.cloud.aws.sqs.batch.send-batch-frequency=PT0.2S
+===== Manual Configuration of the Batching Client
 
-# Visibility timeout for received messages (default: queue default)
-spring.cloud.aws.sqs.batch.visibility-timeout=PT30S
+Since automatic batching is a powerful feature with specific trade-offs, Spring Cloud AWS does not auto-configure it. You can enable it by creating your own `SqsAsyncClient` bean using the provided `BatchingSqsClientAdapter`.
 
-# Wait time for receiveMessage requests (default: AWS SDK default)
-spring.cloud.aws.sqs.batch.wait-time-seconds=PT5S
+###### 1. Defining the Batching Client Bean
+The following example shows how to define a bean named `batchingSqsAsyncClient`. Notice the use of `@Qualifier("sqsAsyncClient")` in the method parameter. This is crucial to explicitly inject the standard, auto-configured `SqsAsyncClient` and avoid ambiguity.
 
-# 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
+[source,java]
 ----
+@Configuration
+public class SqsBatchingConfiguration {
 
-===== 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:
+    // Define a constant for the bean name to avoid typos
+    public static final String BATCHING_SQS_ASYNC_CLIENT = "batchingSqsAsyncClient";
 
-- `messageAttributeNames`
-- `messageSystemAttributeNames`
-- `messageSystemAttributeNamesWithStrings` (not used in Spring Cloud AWS `ReceiveMessageRequest`)
-- `overrideConfiguration` (not used in Spring Cloud AWS `ReceiveMessageRequest`)
+    @Bean(name = BATCHING_SQS_ASYNC_CLIENT)
+    public SqsAsyncClient batchingSqsAsyncClient(
+            // Inject the standard, auto-configured client to wrap it
+            @Qualifier("sqsAsyncClient") SqsAsyncClient standardSqsAsyncClient) {
 
-When these parameters are used, the performance benefits of batching are lost for those specific requests.
+        ScheduledExecutorService scheduledExecutor = Executors.newScheduledThreadPool(5);
 
-**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:
+        SqsAsyncBatchManager batchManager = SqsAsyncBatchManager.builder()
+                .sqsAsyncClient(standardSqsAsyncClient)
+                .scheduledExecutor(scheduledExecutor)
+                .build();
 
-[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
+        return new BatchingSqsClientAdapter(batchManager);
+    }
+}
 ----
 
-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:
+###### 2. Using the Batching Client
+Now, use `@Qualifier` to inject your named bean. The most common use case is configuring a dedicated `SqsTemplate`.
 
 [source,java]
 ----
 @Service
-public class MessageService {
-
-    private final SqsTemplate sqsTemplate;
+public class MyBatchingMessageService {
 
-    public MessageService(SqsTemplate sqsTemplate) {
-        this.sqsTemplate = sqsTemplate;
-    }
+    private final SqsTemplate batchingSqsTemplate;
 
-    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());
-            }
-        });
+    public MyBatchingMessageService(
+            @Qualifier(SqsBatchingConfiguration.BATCHING_SQS_ASYNC_CLIENT) SqsAsyncClient batchingClient) {
+        this.batchingSqsTemplate = SqsTemplate.builder()
+                .sqsAsyncClient(batchingClient)
+                .build();
     }
+    // ... service methods using batchingSqsTemplate
 }
 ----
 
-===== Performance Benefits
+===== Important Considerations & Best Practices
 
-Automatic batching provides several benefits:
+WARNING: **Asynchronous Operations and False Positives**. The batching client processes operations asynchronously. A call to `sqsTemplate.sendAsync(...)` might return a `CompletableFuture` that completes successfully before the message is actually sent to AWS. The actual transmission happens later in a background thread. This can lead to **false positives**. Always attach error handling to the `CompletableFuture` to detect and handle real transmission failures.
 
-- **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
+[source,java]
+----
+CompletableFuture<SendResult<String>> future = batchingSqsTemplate.sendAsync(queueName, message);
 
-===== Compatibility
+future.whenComplete((result, ex) -> {
+    if (ex != null) {
+        // This is where you handle the actual transmission error
+        log.error("Failed to send message to queue {}: {}", queueName, ex.getMessage());
+    } else {
+        log.info("Message acknowledged for batch sending with ID: {}", result.messageId());
+    }
+});
+----
 
-Automatic batching is compatible with:
+WARNING: **Not Recommended for `@SqsListener`**. While technically compatible, using this batching client with `@SqsListener` for receiving messages is **not recommended**. The `@SqsListener` infrastructure already performs efficient batch receiving and has a complex acknowledgment lifecycle. Adding another layer of asynchronous batching provides limited performance benefits while significantly increasing complexity. For listeners, it's best to rely on the default `SqsAsyncClient`.
 
-- `SqsTemplate` for sending and receiving messages
-- `@SqsListener` methods for message processing
-- Both standard and FIFO queues
-- All message conversion and error handling features
+IMPORTANT: **Bean Injection Safety**. By using a named bean and `@Qualifier` as shown in the configuration examples, you ensure the batching client is only used where intended. This prevents it from accidentally being injected into `@SqsListener` infrastructure, which should use the default `SqsAsyncClient`.
 
-The batching is transparent to application code - existing `SqsTemplate` and `@SqsListener` code continues to work without changes.
+IMPORTANT: **AWS SDK Batching Bypass**. The `SqsAsyncBatchManager` will bypass batching for `receiveMessage` calls if certain parameters like `messageAttributeNames` are set on a per-request basis. To ensure batching works effectively, these should be configured globally on the `SqsAsyncBatchManager` builder, not on individual `receiveMessage` calls. See the `BatchingSqsClientAdapter` Javadoc for more details.
 
 ==== Container Options
 

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

@@ -43,33 +43,21 @@
  * </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:
+ * <strong>Batch Optimization:</strong> The underlying {@code SqsAsyncBatchManager} from the AWS SDK bypasses
+ * batching for {@code receiveMessage} calls that include per-request configurations for certain parameters.
+ * To ensure batching is not bypassed, it is recommended to configure these settings globally on the
+ * {@code SqsAsyncBatchManager} builder instead of on each {@code ReceiveMessageRequest}.
+ * The parameters that trigger this bypass are:
  * <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>
+ * <li>{@code messageAttributeNames}</li>
+ * <li>{@code messageSystemAttributeNames}</li>
+ * <li>{@code messageSystemAttributeNamesWithStrings}</li>
+ * <li>{@code overrideConfiguration}</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.
- * 
+ * By configuring these globally on the manager, you ensure consistent batching performance. If you require
+ * per-request attribute configurations, using the standard {@code SqsAsyncClient} without this adapter may be
+ * more appropriate.
  * @author Heechul Kang
  * @since 3.2
  * @see SqsAsyncBatchManager