Menu
Amazon Simple Queue Service
Developer Guide

Client-Side Buffering and Request Batching

The AWS SDK for Java (http://aws.amazon.com/sdkforjava/) includes a buffered asynchronous client, AmazonSQSBufferedAsyncClient, for accessing Amazon SQS. This new client allows for easier request batching by enabling client-side buffering, where calls made from the client are first buffered and then sent as a batch request to Amazon SQS.

Client-side buffering allows up to 10 requests to be buffered and sent as a batch request instead of sending each request separately. As a result, your cost of using Amazon SQS decreases as you reduce the number of requests sent to the service. AmazonSQSBufferedAsyncClient buffers both synchronous and asynchronous calls. Batched requests and support for long polling can also help increase throughput (the number of messages transmitted per second). For more information, see Amazon SQS Long Polling and Increasing Throughput with Horizontal Scaling and Batching.

Migrating from the asynchronous client, AmazonSQSAsyncClient, to the buffered asynchronous client, AmazonSQSBufferedAsyncClient, should require only minimal changes to your existing code. This is because AmazonSQSBufferedAsyncClient implements the same interface as AmazonSQSAsyncClient.

Note

The Amazon SQS Buffered Asynchronous Client doesn't currently support FIFO queues.

Getting Started with AmazonSQSBufferedAsyncClient

Before you begin using the example code in this section, you must first install the AWS SDK for Java and set up your AWS credentials. For instructions, see Getting Started in the AWS SDK for Java Developer Guide.

The following code example shows how to create a new AmazonSQSBufferedAsyncClient based on the AmazonSQSAsyncClient.

Copy
// Create the basic Amazon SQS async client AmazonSQSAsync sqsAsync = new AmazonSQSAsyncClient(); // Create the buffered client AmazonSQSAsync bufferedSqs = new AmazonSQSBufferedAsyncClient(sqsAsync);

After you have created the new AmazonSQSBufferedAsyncClient, you can make calls to it as you do with the AmazonSQSAsyncClient, as the following code example demonstrates.

Copy
CreateQueueRequest createRequest = new CreateQueueRequest().withQueueName("MyTestQueue"); CreateQueueResult res = bufferedSqs.createQueue(createRequest); SendMessageRequest request = new SendMessageRequest(); String body = "test message_" + System.currentTimeMillis(); request.setMessageBody( body ); request.setQueueUrl(res.getQueueUrl()); SendMessageResult sendResult = bufferedSqs.sendMessage(request); ReceiveMessageRequest receiveRq = new ReceiveMessageRequest() .withMaxNumberOfMessages(1) .withQueueUrl(queueUrl); ReceiveMessageResult rx = bufferedSqs.receiveMessage(receiveRq);

Advanced Configuration

AmazonSQSBufferedAsyncClient is pre-configured with settings that will work for most use cases. If you'd like to configure it yourself, you can use the QueueBufferConfig class to do so. Just create an instance of QueueBufferConfig with the settings you want and supply it to the AmazonSQSBufferedAsyncClient constructor, as the following sample code shows.

Copy
// Create the basic Amazon SQS async client AmazonSQSAsync sqsAsync = new AmazonSQSAsyncClient(); QueueBufferConfig config = new QueueBufferConfig() .withMaxInflightReceiveBatches(5) .withMaxDoneReceiveBatches(15); // Create the buffered client AmazonSQSAsync bufferedSqs = new AmazonSQSBufferedAsyncClient(sqsAsync, config);

The parameters you can use for configuring QueueBufferConfig are as follows:

  • longPoll—if this parameter is set to true, AmazonBufferedAsyncClient attempts to use long-polling when consuming messages. The default value is true.

  • longPollWaitTimeoutSeconds—the maximum amount of time, in seconds, that a receive message call blocks on the server waiting for messages to appear in the queue before returning with an empty receive result. This setting has no impact if long polling is disabled. The default value of this setting is 20 seconds.

  • maxBatchOpenMs—the maximum amount of time, in milliseconds, that an outgoing call waits for other calls of the same type to batch with. The higher the setting, the fewer batches are required to perform the same amount of work. Of course, the higher the setting, the more the first call in a batch has to spend waiting. If this parameter is set to zero, submitted requests do not wait for other requests, effectively disabling batching. The default value of this setting is 200 milliseconds.

  • maxBatchSize—the maximum number of messages that will be batched together in a single batch request. The higher the setting, the fewer batches will be required to carry out the same number of requests. The default value of this setting is 10 requests per batch, which is also the maximum batch size currently allowed by Amazon SQS.

  • maxBatchSizeBytes—the maximum size of a message batch, in bytes, that the client attempts to send to Amazon SQS. The default value is 256 KB, which is also the maximum message and batch size currently allowed by Amazon SQS.

  • maxDoneReceiveBatches—the maximum number of receive batches AmazonBufferedAsyncClient prefetches and stores on the client side. The higher the setting, the more receive requests can be satisfied without having to make a call to Amazon SQS server. However, the more messages are pre-fetched, the longer they'll sit in the buffer, which means that their visibility timeout will be expiring. If this parameter is set to zero, all pre-fetching of messages is disabled and messages are consumed only on demand. The default value is 10 batches.

  • maxInflightOutboundBatches—the maximum number of active outbound batches that can be processed at the same time. The higher the setting, the faster outbound batches can be sent (subject to other limits, such as CPU or bandwidth). The higher the setting, the more threads are consumed by the AmazonSQSBufferedAsyncClient. The default value is 5 batches.

  • maxInflightReceiveBatches—the maximum number of active receive batches that can be processed at the same time. The higher the setting, the more messages can be received (subject to other limits, such as CPU or bandwidth, being reached). Although, the higher the setting, the more threads will be consumed by the AmazonSQSBufferedAsyncClient. If this parameter is set to 0, all pre-fetching of messages is disabled and messages are only consumed on demand. The default value is 10 batches.

  • visibilityTimeoutSeconds—if this parameter is set to a positive nonzero value, this visibility timeout overrides the visibility timeout set on the queue from which messages are consumed. A visibility timeout of zero seconds isn't supported. The default value is -1, which means the default queue setting is used.