Java tutorial
/* * Copyright 2012-2014 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). * You may not use this file except in compliance with the License. * A copy of the License is located at * * http://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. This file 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 com.amazonaws.services.sqs.buffered; import java.util.ArrayList; import java.util.Collections; import java.util.LinkedList; import java.util.List; import java.util.concurrent.Executor; import java.util.concurrent.TimeUnit; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import com.amazonaws.AmazonClientException; import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.model.ChangeMessageVisibilityBatchRequest; import com.amazonaws.services.sqs.model.ChangeMessageVisibilityBatchRequestEntry; import com.amazonaws.services.sqs.model.GetQueueAttributesRequest; import com.amazonaws.services.sqs.model.Message; import com.amazonaws.services.sqs.model.ReceiveMessageRequest; import com.amazonaws.services.sqs.model.ReceiveMessageResult; /** * The ReceiveQueueBuffer class is responsible for dequeueing of messages from * a single SQS queue. It uses the provided executor to pre-fetch messages from the server * and keeps them in a buffer which it uses to satisfy incoming requests. The number of requests * pre-fetched and kept in the buffer, as well as the maximum number of threads used to retrieve * the messages are configurable. <p> * * Synchronization strategy: * - Threads must hold the TaskSpawnSyncPoint object monitor to spawn a new task or modify * the number of inflight tasks * - Threads must hold the monitor of the "futures" list to modify the list * - Threads must hold the monitor of the "finishedTasks" list to modify the list * - If you need to lock both futures and finishedTasks, lock futures first and * finishedTasks second * */ public class ReceiveQueueBuffer { private static Log log = LogFactory.getLog(ReceiveQueueBuffer.class); private final QueueBufferConfig config; private final String qUrl; private final Executor executor; private final AmazonSQS sqsClient; private long bufferCounter = 0; /** * This buffer's queue visibility timeout. Used to detect expired message * that should not be returned by the {@code receiveMessage} call. * Synchronized by {@code receiveMessageLock}. -1 indicates that the time is * uninitialized. */ private volatile long visibilityTimeoutNanos = -1; /** * Used as permits controlling the number of in flight receive batches. * Synchronized by {@code taskSpawnSyncPoint}. */ private volatile int inflightReceiveMessageBatches; /** * synchronize on this object to create new receive batches or modify * inflight message count */ private final Object taskSpawnSyncPoint = new Object(); /** shutdown buffer does not retrieve any more messages from sqs */ volatile boolean shutDown = false; /** message delivery futures we gave out */ private final LinkedList<ReceiveMessageFuture> futures = new LinkedList<ReceiveMessageFuture>(); /** finished batches are stored in this list. */ private LinkedList<ReceiveMessageBatchTask> finishedTasks = new LinkedList<ReceiveMessageBatchTask>(); ReceiveQueueBuffer(AmazonSQS paramSQS, Executor paramExecutor, QueueBufferConfig paramConfig, String url) { config = paramConfig; executor = paramExecutor; sqsClient = paramSQS; qUrl = url; } /** * Prevents spawning of new retrieval batches and waits for all in-flight * retrieval batches to finish * */ public void shutdown() { shutDown = true; try { while (inflightReceiveMessageBatches > 0) Thread.sleep(100); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } } /** * Submits the request for retrieval of messages from the queue and returns * a future that will be signalled when the request is satisfied. The future * may already be signalled by the time it is returned. * * @return never null * */ public QueueBufferFuture<ReceiveMessageRequest, ReceiveMessageResult> receiveMessageAsync( ReceiveMessageRequest rq, QueueBufferCallback<ReceiveMessageRequest, ReceiveMessageResult> callback) { if (shutDown) { throw new AmazonClientException("The client has been shut down."); } //issue the future... int numMessages = 10; if (rq.getMaxNumberOfMessages() != null) { numMessages = rq.getMaxNumberOfMessages(); } QueueBufferFuture<ReceiveMessageRequest, ReceiveMessageResult> toReturn = issueFuture(numMessages, callback); //attempt to satisfy it right away... satisfyFuturesFromBuffer(); //spawn more receive tasks if we need them... spawnMoreReceiveTasks(); return toReturn; } /** * Creates and returns a new future object. Sleeps if the list of * already-issued but as yet unsatisfied futures is over a throttle limit. * * @return never null */ private ReceiveMessageFuture issueFuture(int size, QueueBufferCallback<ReceiveMessageRequest, ReceiveMessageResult> callback) { synchronized (futures) { ReceiveMessageFuture theFuture = new ReceiveMessageFuture(callback, size); futures.addLast(theFuture); return theFuture; } } /** * Attempts to satisfy some or all of the already-issued futures from the * local buffer. If the buffer is empty or there are no futures, this method * won't do anything. * */ private void satisfyFuturesFromBuffer() { synchronized (futures) { synchronized (finishedTasks) { //attempt to satisfy futures until we run out of either futures or //finished tasks while ((!futures.isEmpty()) && (!finishedTasks.isEmpty())) { ReceiveMessageFuture currentFuture = futures.poll(); fillFuture(currentFuture); } } } } /** * Fills the future with whatever results were received by the full batch * currently at the head of the completed batch queue. Those results may be retrieved * messages, or an exception. * * this method assumes that you are holding the finished tasks lock * locks when invoking it. violate this assumption at * your own peril */ private void fillFuture(ReceiveMessageFuture f) { ReceiveMessageResult r = new ReceiveMessageResult(); LinkedList<Message> messages = new LinkedList<Message>(); r.setMessages(messages); Exception exception = null; if (!finishedTasks.isEmpty()) { ReceiveMessageBatchTask t = finishedTasks.getFirst(); exception = t.getException(); int retrieved = 0; boolean batchDone = false; while (retrieved < f.getRequestedSize()) { Message m = t.removeMessage(); // a non-empty batch can still give back a null // message if the message expired. if (null != m) { messages.add(m); ++retrieved; } else { batchDone = true; break; } } //we may have just drained the batch. batchDone = batchDone || t.isEmpty() || (exception != null); if (batchDone) { finishedTasks.removeFirst(); } r.setMessages(messages); } //if after the above runs the exception is not null, //the finished batch has encountered an error, and we will //report that in the Future. Otherwise, we will fill //the future with the receive result if (exception != null) f.setFailure(exception); else f.setSuccess(r); //now, a bit of maintenance. remove empty non-exception-bearing //batches so we can get new ones. while (!finishedTasks.isEmpty()) { ReceiveMessageBatchTask t = finishedTasks.getFirst(); if ((!t.isEmpty()) || (t.getException() != null)) { //if we found a finished task that has useful content, //our cleanup is done break; } //throw away the empty batch. finishedTasks.removeFirst(); } } /** * maybe create more receive tasks. extra receive tasks won't be created if * we are already at the maximum number of receive tasks, or if we are at * the maximum number of prefetched buffers */ private void spawnMoreReceiveTasks() { if (shutDown) return; int desiredBatches = config.getMaxDoneReceiveBatches(); desiredBatches = desiredBatches < 1 ? 1 : desiredBatches; synchronized (finishedTasks) { if (finishedTasks.size() >= desiredBatches) return; //if we have some finished batches already, and //existing inflight batches will bring us to the limit, //don't spawn more. if our finished tasks cache is empty, we will //always spawn a thread. if (finishedTasks.size() > 0 && (finishedTasks.size() + inflightReceiveMessageBatches) >= desiredBatches) return; } synchronized (taskSpawnSyncPoint) { if (visibilityTimeoutNanos == -1) { GetQueueAttributesRequest request = new GetQueueAttributesRequest().withQueueUrl(qUrl) .withAttributeNames("VisibilityTimeout"); ResultConverter.appendUserAgent(request, AmazonSQSBufferedAsyncClient.USER_AGENT); long visibilityTimeoutSeconds = Long .parseLong(sqsClient.getQueueAttributes(request).getAttributes().get("VisibilityTimeout")); visibilityTimeoutNanos = TimeUnit.NANOSECONDS.convert(visibilityTimeoutSeconds, TimeUnit.SECONDS); } int max = config.getMaxInflightReceiveBatches(); //must allow at least one inflight receive task, or receive won't //work at all. max = max > 0 ? max : 1; int toSpawn = max - inflightReceiveMessageBatches; if (toSpawn > 0) { ReceiveMessageBatchTask task = new ReceiveMessageBatchTask(this); ++inflightReceiveMessageBatches; ++bufferCounter; if (log.isTraceEnabled()) { log.trace("Spawned receive batch #" + bufferCounter + " (" + inflightReceiveMessageBatches + " of " + max + " inflight) for queue " + qUrl); } executor.execute(task); } } } /** * This method is called by the batches after they have finished retrieving * the messages. * * */ void reportBatchFinished(ReceiveMessageBatchTask batch) { synchronized (finishedTasks) { finishedTasks.addLast(batch); if (log.isTraceEnabled()) { log.info("Queue " + qUrl + " now has " + finishedTasks.size() + " receive results cached "); } } synchronized (taskSpawnSyncPoint) { --inflightReceiveMessageBatches; } satisfyFuturesFromBuffer(); spawnMoreReceiveTasks(); } /** * Clears and nacks any pre-fetched messages in this buffer. */ public void clear() { boolean done = false; while (!done) { ReceiveMessageBatchTask currentBatch = null; synchronized (finishedTasks) { currentBatch = finishedTasks.poll(); } if (currentBatch != null) { currentBatch.clear(); } else { //ran out of batches to clear done = true; } } } private class ReceiveMessageFuture extends QueueBufferFuture<ReceiveMessageRequest, ReceiveMessageResult> { /* how many messages did the request ask for*/ private int requestedSize; ReceiveMessageFuture(int paramSize) { this(null, paramSize); } ReceiveMessageFuture(QueueBufferCallback<ReceiveMessageRequest, ReceiveMessageResult> cb, int paramSize) { super(cb); requestedSize = paramSize; } public int getRequestedSize() { return requestedSize; } } /** * Task to receive messages from SQS. * <p> * The batch task is constructed {@code !open} until the * {@code ReceiveMessage} completes. At that point, the batch opens and its * messages (if any) become available to read. */ private class ReceiveMessageBatchTask implements Runnable { private Exception exception = null; private List<Message> messages; private long visibilityDeadlineNano; private boolean open = false; private ReceiveQueueBuffer parentBuffer; /** * Constructs a receive task waiting the specified time before calling * SQS. * * @param waitTimeMs * the time to wait before calling SQS */ ReceiveMessageBatchTask(ReceiveQueueBuffer paramParentBuffer) { parentBuffer = paramParentBuffer; messages = Collections.emptyList(); } synchronized int getSize() { if (!open) throw new IllegalStateException("batch is not open"); return messages.size(); } synchronized boolean isEmpty() { if (!open) throw new IllegalStateException("batch is not open"); return messages.isEmpty(); } /** @return the exception that was thrown during execution, or null * if there was no exception */ synchronized Exception getException() { if (!open) throw new IllegalStateException("batch is not open"); return exception; } /** * Returns a message if one is available. * <p> * The call adjusts the message count. * * @return a message or {@code null} if none is available */ synchronized Message removeMessage() { if (!open) throw new IllegalStateException("batch is not open"); // our messages expired. if (System.nanoTime() > visibilityDeadlineNano) { messages.clear(); return null; } if (messages.isEmpty()) return null; else return messages.remove(messages.size() - 1); } /** * Nacks and clears all messages remaining in the batch. */ synchronized void clear() { if (!open) throw new IllegalStateException("batch is not open"); if (System.nanoTime() < visibilityDeadlineNano) { ChangeMessageVisibilityBatchRequest batchRequest = new ChangeMessageVisibilityBatchRequest() .withQueueUrl(qUrl); ResultConverter.appendUserAgent(batchRequest, AmazonSQSBufferedAsyncClient.USER_AGENT); List<ChangeMessageVisibilityBatchRequestEntry> entries = new ArrayList<ChangeMessageVisibilityBatchRequestEntry>( messages.size()); int i = 0; for (Message m : messages) { entries.add(new ChangeMessageVisibilityBatchRequestEntry().withId(Integer.toString(i)) .withReceiptHandle(m.getReceiptHandle()).withVisibilityTimeout(0)); ++i; } try { batchRequest.setEntries(entries); sqsClient.changeMessageVisibilityBatch(batchRequest); } catch (AmazonClientException e) { // Log and ignore. log.warn("ReceiveMessageBatchTask: changeMessageVisibility failed " + e); } } messages.clear(); } /** * Attempts to retrieve messages from SQS and upon completion (successful or * unsuccessful) reports the batch as complete and open * */ public void run() { try { visibilityDeadlineNano = System.nanoTime() + visibilityTimeoutNanos; ReceiveMessageRequest request = new ReceiveMessageRequest(qUrl) .withMaxNumberOfMessages(config.getMaxBatchSize()); ResultConverter.appendUserAgent(request, AmazonSQSBufferedAsyncClient.USER_AGENT); if (config.getVisibilityTimeoutSeconds() > 0) { request.setVisibilityTimeout(config.getVisibilityTimeoutSeconds()); visibilityDeadlineNano = System.nanoTime() + TimeUnit.NANOSECONDS.convert(config.getVisibilityTimeoutSeconds(), TimeUnit.SECONDS); } if (config.isLongPoll()) { request.withWaitTimeSeconds(config.getLongPollWaitTimeoutSeconds()); } messages = sqsClient.receiveMessage(request).getMessages(); } catch (AmazonClientException e) { exception = e; } finally { //whatever happened, we are done and can be considered open open = true; parentBuffer.reportBatchFinished(this); } } } } //end of ReceiveQueueBuffer