Class BatchingSqsClientAdapter

java.lang.Object
io.awspring.cloud.sqs.operations.BatchingSqsClientAdapter
All Implemented Interfaces:
AutoCloseable, software.amazon.awssdk.awscore.AwsClient, software.amazon.awssdk.core.SdkClient, software.amazon.awssdk.services.sqs.SqsAsyncClient, software.amazon.awssdk.utils.SdkAutoCloseable
public class BatchingSqsClientAdapter extends Object implements software.amazon.awssdk.services.sqs.SqsAsyncClient
An SqsAsyncClient adapter that provides automatic batching capabilities using AWS SDK's SqsAsyncBatchManager.

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.

Important - Asynchronous Behavior: This adapter processes requests asynchronously through batching. The returned CompletableFuture reflects the batching operation, not the final transmission to AWS SQS. This can lead to false positives where the operation appears successful locally but fails during actual transmission. The actual transmission happens in a background thread, up to the configured sendRequestFrequency after enqueuing. Applications must:

  • Handle the returned CompletableFuture to detect transmission errors. Calling .join() will block until the batch is sent (up to sendRequestFrequency), while .exceptionally() or .handle() are required for non-blocking error handling.
  • Implement appropriate error handling, monitoring, and retry mechanisms for critical operations.

Batch Optimization: The underlying SqsAsyncBatchManager from the AWS SDK bypasses batching for 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 SqsAsyncBatchManager builder instead of on each ReceiveMessageRequest. The parameters that trigger this bypass are:

  • messageAttributeNames
  • messageSystemAttributeNames
  • messageSystemAttributeNamesWithStrings
  • overrideConfiguration

By configuring these globally on the manager, you ensure consistent batching performance. If you require per-request attribute configurations, using the standard SqsAsyncClient without this adapter may be more appropriate.

Since:
4.0.0
Author:
Heechul Kang
See Also:
  • SqsAsyncBatchManager
  • SqsAsyncClient

  • Field Summary

    Fields inherited from interface software.amazon.awssdk.services.sqs.SqsAsyncClient

    SERVICE_METADATA_ID, SERVICE_NAME

  • Constructor Summary

    Constructors
    Constructor
    Description
    BatchingSqsClientAdapter(software.amazon.awssdk.services.sqs.batchmanager.SqsAsyncBatchManager batchManager)
    Creates a new BatchingSqsClientAdapter with the specified batch manager.

  • Method Summary

    Modifier and Type
    Method
    Description
    CompletableFuture<software.amazon.awssdk.services.sqs.model.ChangeMessageVisibilityResponse>
    changeMessageVisibility(Consumer<software.amazon.awssdk.services.sqs.model.ChangeMessageVisibilityRequest.Builder> changeMessageVisibilityRequest)
    Changes the visibility timeout of a message in the specified SQS queue using automatic batching.
    CompletableFuture<software.amazon.awssdk.services.sqs.model.ChangeMessageVisibilityResponse>
    changeMessageVisibility(software.amazon.awssdk.services.sqs.model.ChangeMessageVisibilityRequest changeMessageVisibilityRequest)
    Changes the visibility timeout of a message in the specified SQS queue using automatic batching.
    void
    close()
    Closes the underlying batch manager and releases associated resources.
    CompletableFuture<software.amazon.awssdk.services.sqs.model.DeleteMessageResponse>
    deleteMessage(Consumer<software.amazon.awssdk.services.sqs.model.DeleteMessageRequest.Builder> deleteMessageRequest)
    Deletes a message from the specified SQS queue using automatic batching.
    CompletableFuture<software.amazon.awssdk.services.sqs.model.DeleteMessageResponse>
    deleteMessage(software.amazon.awssdk.services.sqs.model.DeleteMessageRequest deleteMessageRequest)
    Deletes a message from the specified SQS queue using automatic batching.
    CompletableFuture<software.amazon.awssdk.services.sqs.model.ReceiveMessageResponse>
    receiveMessage(Consumer<software.amazon.awssdk.services.sqs.model.ReceiveMessageRequest.Builder> receiveMessageRequest)
    Receives messages from the specified SQS queue using automatic batching.
    CompletableFuture<software.amazon.awssdk.services.sqs.model.ReceiveMessageResponse>
    receiveMessage(software.amazon.awssdk.services.sqs.model.ReceiveMessageRequest receiveMessageRequest)
    Receives messages from the specified SQS queue using automatic batching.
    CompletableFuture<software.amazon.awssdk.services.sqs.model.SendMessageResponse>
    sendMessage(Consumer<software.amazon.awssdk.services.sqs.model.SendMessageRequest.Builder> sendMessageRequest)
    Sends a message to the specified SQS queue using automatic batching.
    CompletableFuture<software.amazon.awssdk.services.sqs.model.SendMessageResponse>
    sendMessage(software.amazon.awssdk.services.sqs.model.SendMessageRequest sendMessageRequest)
    Sends a message to the specified SQS queue using automatic batching.
    String
    serviceName()
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface software.amazon.awssdk.services.sqs.SqsAsyncClient

    addPermission, addPermission, batchManager, cancelMessageMoveTask, cancelMessageMoveTask, changeMessageVisibilityBatch, changeMessageVisibilityBatch, createQueue, createQueue, deleteMessageBatch, deleteMessageBatch, deleteQueue, deleteQueue, getQueueAttributes, getQueueAttributes, getQueueUrl, getQueueUrl, listDeadLetterSourceQueues, listDeadLetterSourceQueues, listDeadLetterSourceQueuesPaginator, listDeadLetterSourceQueuesPaginator, listMessageMoveTasks, listMessageMoveTasks, listQueues, listQueues, listQueues, listQueuesPaginator, listQueuesPaginator, listQueuesPaginator, listQueueTags, listQueueTags, purgeQueue, purgeQueue, removePermission, removePermission, sendMessageBatch, sendMessageBatch, serviceClientConfiguration, setQueueAttributes, setQueueAttributes, startMessageMoveTask, startMessageMoveTask, tagQueue, tagQueue, untagQueue, untagQueue

  • Constructor Details

    • BatchingSqsClientAdapter

      public BatchingSqsClientAdapter(software.amazon.awssdk.services.sqs.batchmanager.SqsAsyncBatchManager batchManager)
      Creates a new BatchingSqsClientAdapter with the specified batch manager.
      Parameters:
      batchManager - the SqsAsyncBatchManager to use for batching operations
      Throws:
      IllegalArgumentException - if batchManager is null

  • Method Details

    • serviceName

      public String serviceName()
      Specified by:
      serviceName in interface software.amazon.awssdk.core.SdkClient

    • close

      public void close()
      Closes the underlying batch manager and releases associated resources.

      This method should be called when the adapter is no longer needed to ensure proper cleanup of threads and connections.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface software.amazon.awssdk.utils.SdkAutoCloseable

    • sendMessage

      public CompletableFuture<software.amazon.awssdk.services.sqs.model.SendMessageResponse> sendMessage(software.amazon.awssdk.services.sqs.model.SendMessageRequest sendMessageRequest)
      Sends a message to the specified SQS queue using automatic batching.

      Important: This method returns immediately, but the actual sending is performed asynchronously. Handle the returned CompletableFuture to detect transmission errors.

      Specified by:
      sendMessage in interface software.amazon.awssdk.services.sqs.SqsAsyncClient
      Parameters:
      sendMessageRequest - the request containing queue URL and message details
      Returns:
      a CompletableFuture that completes with the send result

    • sendMessage

      public CompletableFuture<software.amazon.awssdk.services.sqs.model.SendMessageResponse> sendMessage(Consumer<software.amazon.awssdk.services.sqs.model.SendMessageRequest.Builder> sendMessageRequest)
      Sends a message to the specified SQS queue using automatic batching.

      Important: This method returns immediately, but the actual sending is performed asynchronously. Handle the returned CompletableFuture to detect transmission errors.

      Specified by:
      sendMessage in interface software.amazon.awssdk.services.sqs.SqsAsyncClient
      Parameters:
      sendMessageRequest - a consumer to configure the send message request
      Returns:
      a CompletableFuture that completes with the send result

    • receiveMessage

      public CompletableFuture<software.amazon.awssdk.services.sqs.model.ReceiveMessageResponse> receiveMessage(software.amazon.awssdk.services.sqs.model.ReceiveMessageRequest receiveMessageRequest)
      Receives messages from the specified SQS queue using automatic batching.

      The batching manager may combine multiple receive requests to optimize AWS API usage.

      Specified by:
      receiveMessage in interface software.amazon.awssdk.services.sqs.SqsAsyncClient
      Parameters:
      receiveMessageRequest - the request containing queue URL and receive options
      Returns:
      a CompletableFuture that completes with the received messages

    • receiveMessage

      public CompletableFuture<software.amazon.awssdk.services.sqs.model.ReceiveMessageResponse> receiveMessage(Consumer<software.amazon.awssdk.services.sqs.model.ReceiveMessageRequest.Builder> receiveMessageRequest)
      Receives messages from the specified SQS queue using automatic batching.

      The batching manager may combine multiple receive requests to optimize AWS API usage.

      Specified by:
      receiveMessage in interface software.amazon.awssdk.services.sqs.SqsAsyncClient
      Parameters:
      receiveMessageRequest - a consumer to configure the receive message request
      Returns:
      a CompletableFuture that completes with the received messages

    • deleteMessage

      public CompletableFuture<software.amazon.awssdk.services.sqs.model.DeleteMessageResponse> deleteMessage(software.amazon.awssdk.services.sqs.model.DeleteMessageRequest deleteMessageRequest)
      Deletes a message from the specified SQS queue using automatic batching.

      Important: The actual deletion may be delayed due to batching. Handle the returned CompletableFuture to confirm successful deletion.

      Specified by:
      deleteMessage in interface software.amazon.awssdk.services.sqs.SqsAsyncClient
      Parameters:
      deleteMessageRequest - the request containing queue URL and receipt handle
      Returns:
      a CompletableFuture that completes with the deletion result

    • deleteMessage

      public CompletableFuture<software.amazon.awssdk.services.sqs.model.DeleteMessageResponse> deleteMessage(Consumer<software.amazon.awssdk.services.sqs.model.DeleteMessageRequest.Builder> deleteMessageRequest)
      Deletes a message from the specified SQS queue using automatic batching.

      Important: The actual deletion may be delayed due to batching. Handle the returned CompletableFuture to confirm successful deletion.

      Specified by:
      deleteMessage in interface software.amazon.awssdk.services.sqs.SqsAsyncClient
      Parameters:
      deleteMessageRequest - a consumer to configure the delete message request
      Returns:
      a CompletableFuture that completes with the deletion result

    • changeMessageVisibility

      public CompletableFuture<software.amazon.awssdk.services.sqs.model.ChangeMessageVisibilityResponse> changeMessageVisibility(software.amazon.awssdk.services.sqs.model.ChangeMessageVisibilityRequest changeMessageVisibilityRequest)
      Changes the visibility timeout of a message in the specified SQS queue using automatic batching.

      The batching manager may combine multiple visibility change requests to optimize AWS API usage.

      Specified by:
      changeMessageVisibility in interface software.amazon.awssdk.services.sqs.SqsAsyncClient
      Parameters:
      changeMessageVisibilityRequest - the request containing queue URL, receipt handle, and new timeout
      Returns:
      a CompletableFuture that completes with the visibility change result

    • changeMessageVisibility

      public CompletableFuture<software.amazon.awssdk.services.sqs.model.ChangeMessageVisibilityResponse> changeMessageVisibility(Consumer<software.amazon.awssdk.services.sqs.model.ChangeMessageVisibilityRequest.Builder> changeMessageVisibilityRequest)
      Changes the visibility timeout of a message in the specified SQS queue using automatic batching.

      The batching manager may combine multiple visibility change requests to optimize AWS API usage.

      Specified by:
      changeMessageVisibility in interface software.amazon.awssdk.services.sqs.SqsAsyncClient
      Parameters:
      changeMessageVisibilityRequest - a consumer to configure the change visibility request
      Returns:
      a CompletableFuture that completes with the visibility change result