'Version 1.0.0 of the Amazon SQS Java Messaging Library'

Author: Patel, Mihir

NOTICE.txt

@@ -8,6 +8,6 @@ Amazon Technologies, Inc (http://www.amazon.com/).
 THIRD PARTY COMPONENTS
 **********************
 This software includes third party software subject to the following copyrights:
-- Apache ActiveMQ (see: org.apache.activemq.util.TypeConversionSupport, org.apache.activemq.command.ActiveMQStreamMessage). Copyright 2005-2013 Apache Software Foundation
+- Apache ActiveMQ (see: org.apache.activemq.util.TypeConversionSupport), Copyright 2005-2013 Apache Software Foundation.
 
-The licenses for these third party components are included in LICENSE.txt
+The licenses for these third party components are included in LICENSE.txt

README.md

@@ -1,7 +1,7 @@
 Amazon SQS Java Messaging Library
 ========================================
 The **Amazon SQS Java Messaging Library** holds the Java Message Service compatible classes, that are used
-for communicating with Amazon Simple Queue Service. This project builds on top of the AWS SDK for Java to use Amazon SQS as the JMS (as defined in 1.1 specification) provider for the messaging applications without running any additional software. 
+for communicating with Amazon Simple Queue Service. This project builds on top of the AWS SDK for Java to use Amazon SQS as the JMS (as defined in 1.1 specification) provider for the messaging applications without running any additional software.
 
 * You can download release builds through the [releases section of this](https://github.com/awslabs/amazon-sqs-java-messaging-lib) project.
 * For more information on using the amazon-sqs-java-messaging-lib, see our getting started guide to SQS [here](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/Welcome.html).
@@ -11,7 +11,7 @@ for communicating with Amazon Simple Queue Service. This project builds on top o
 * **Sign up for AWS** — Before you begin, you need an AWS account. For more information about creating an AWS account and retrieving your AWS credentials, see [AWS Account and Credentials](http://docs.aws.amazon.com/AWSSdkDocsJava/latest/DeveloperGuide/java-dg-setup.html) in the AWS SDK for Java Developer Guide.
 * **Sign up for Amazon SQS** — Go to the Amazon [SQS console](https://console.aws.amazon.com/sqs/home?region=us-east-1) to sign up for the service.
 * **Minimum requirements** — To use the sample application, you'll need Java 1.7+ and [Maven 3](http://maven.apache.org/). For more information about the requirements, see the [Getting Started](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/Welcome.html) section of the Amazon SQS Developer Guide.
-* **Download** — Download the [latest preview release or](https://github.com/awslabs/amazon-sqs-java-messaging-lib/releases) pick it up from Maven:
+* **Download** — Download the [latest preview release](https://github.com/awslabs/amazon-sqs-java-messaging-lib/releases) or pick it up from Maven:
 ```xml
   <dependency>
     <groupId>com.amazonaws</groupId>
@@ -25,4 +25,3 @@ for communicating with Amazon Simple Queue Service. This project builds on top o
 ##Feedback
 * Give us feedback [here](https://github.com/awslabs/amazon-sqs-java-messaging-lib/issues).
 * If you'd like to contribute a new feature or bug fix, we'd love to see Github pull requests from you.
-

src/main/java/com/amazonaws/sqsjms/AmazonSQSClientJMSWrapper.java

@@ -45,8 +45,8 @@
 import com.amazonaws.services.sqs.model.SendMessageResult;
 
 /**
- * This is a JMS Wrapper of AmazonSQSClient. This class changes all
- * AmazonServiceException and AmazonClientException into
+ * This is a JMS Wrapper of <code>AmazonSQSClient</code>. This class changes all
+ * <code>AmazonServiceException</code> and <code>AmazonClientException</code> into
  * JMSException/JMSSecurityException.
  */
 public class AmazonSQSClientJMSWrapper {
@@ -57,7 +57,7 @@ public class AmazonSQSClientJMSWrapper {
         /**
          * List of exceptions that can classified as security. These exceptions
          * are not thrown during connection-set-up rather after the service
-         * calls of the AmazonSQSClient
+         * calls of the <code>AmazonSQSClient</code>.
          */
         SECURITY_EXCEPTION_ERROR_CODES = new HashSet<String>();
         SECURITY_EXCEPTION_ERROR_CODES.add("MissingClientTokenId");
@@ -84,14 +84,16 @@ public AmazonSQSClientJMSWrapper(AmazonSQS amazonSQSClient) throws JMSException
     /**
      * If one uses any other AWS SDK operations other than explicitly listed
      * here, the exceptions thrown by those operations will not be wrapped as
-     * JMSExceptions.
+     * <code>JMSException</code>.
      * @return amazonSQSClient
      */
     public AmazonSQS getAmazonSQSClient() {
         return amazonSQSClient;
     }
 
     /**
+     * Sets SQS endpoint and wraps IllegalArgumentException.
+     * 
      * @param endpoint
      *            The endpoint (ex: "sqs.us-east-1.amazonaws.com") of the region
      *            specific AWS endpoint this client will communicate with.
@@ -107,6 +109,9 @@ public void setEndpoint(String endpoint) throws JMSException {
     }
 
     /**
+     * Sets SQS region and wraps <code>IllegalArgumentException</code>. This is the recommend
+     * way to set-up the SQS end-points.
+     * 
      * @param region
      *            The region this client will communicate with. See
      *            {@link Region#getRegion(com.amazonaws.regions.Regions)} for
@@ -123,6 +128,9 @@ public void setRegion(Region region) throws JMSException {
     }
 
     /**
+     * Calls <code>deleteMessage</code> and wraps <code>AmazonClientException</code>. This is used to
+     * acknowledge single messages, so that they can be deleted from SQS queue.
+     * 
      * @param deleteMessageRequest
      *            Container for the necessary parameters to execute the
      *            deleteMessage service method on AmazonSQS.
@@ -137,10 +145,17 @@ public void deleteMessage(DeleteMessageRequest deleteMessageRequest) throws JMSE
     }
 
     /**
+     * Calls <code>deleteMessageBatch</code> and wraps
+     * <code>AmazonClientException</code>. This is used to acknowledge multiple
+     * messages on client_acknowledge mode, so that they can be deleted from SQS
+     * queue.
+     * 
      * @param deleteMessageBatchRequest
      *            Container for the necessary parameters to execute the
      *            deleteMessageBatch service method on AmazonSQS. This is the
      *            batch version of deleteMessage. Max batch size is 10.
+     * @return The response from the deleteMessageBatch service method, as
+     *         returned by AmazonSQS
      * @throws JMSException
      */
     public DeleteMessageBatchResult deleteMessageBatch(DeleteMessageBatchRequest deleteMessageBatchRequest) throws JMSException {
@@ -152,9 +167,14 @@ public DeleteMessageBatchResult deleteMessageBatch(DeleteMessageBatchRequest del
     }
 
     /**
+     * Calls <code>sendMessage</code> and wraps
+     * <code>AmazonClientException</code>.
+     * 
      * @param sendMessageRequest
      *            Container for the necessary parameters to execute the
      *            sendMessage service method on AmazonSQS.
+     * @return The response from the sendMessage service method, as returned by
+     *         AmazonSQS
      * @throws JMSException
      */
     public SendMessageResult sendMessage(SendMessageRequest sendMessageRequest) throws JMSException {
@@ -166,11 +186,12 @@ public SendMessageResult sendMessage(SendMessageRequest sendMessageRequest) thro
     }
 
     /**
-     * Check if the requested queue exists. This function works by calling
-     * GetQueueUrl for the given queue name, returning true on 
-     * success, false if it gets QueueDoesNotExistException. 
+     * Check if the requested queue exists. This function calls
+     * <code>GetQueueUrl</code> for the given queue name, returning true on
+     * success, false if it gets <code>QueueDoesNotExistException</code>.
      * 
-     * @param queueName the queue to check
+     * @param queueName
+     *            the queue to check
      * @return true if the queue exists, false if it doesn't.
      * @throws JMSException
      */
@@ -186,6 +207,34 @@ public boolean queueExists(String queueName) throws JMSException {
     }
 
     /**
+     * Check if the requested queue exists. This function calls
+     * <code>GetQueueUrl</code> for the given queue name with the given owner
+     * accountId, returning true on success, false if it gets
+     * <code>QueueDoesNotExistException</code>.
+     * 
+     * @param queueName
+     *            the queue to check
+     * @param queueOwnerAccountId
+     *            The AWS accountId of the account that created the queue
+     * @return true if the queue exists, false if it doesn't.
+     * @throws JMSException
+     */
+    public boolean queueExists(String queueName, String queueOwnerAccountId) throws JMSException {
+        try {
+            GetQueueUrlRequest getQueueUrlRequest = new GetQueueUrlRequest(queueName);
+            getQueueUrlRequest.setQueueOwnerAWSAccountId(queueOwnerAccountId);
+            amazonSQSClient.getQueueUrl(getQueueUrlRequest);
+            return true;
+        } catch (QueueDoesNotExistException e) {
+            return false;
+        } catch (AmazonClientException e) {
+            throw handleException(e, "getQueueUrl");
+        }
+    }
+    
+    /**
+     * Gets the queueUrl of a queue given a queue name.
+     * 
      * @param queueName
      * @return The response from the GetQueueUrl service method, as returned by
      *         AmazonSQS, which will include queue`s URL
@@ -194,8 +243,25 @@ public boolean queueExists(String queueName) throws JMSException {
     public GetQueueUrlResult getQueueUrl(String queueName) throws JMSException {
         return getQueueUrl(new GetQueueUrlRequest(queueName));
     }
+    
+    /**
+     * Gets the queueUrl of a queue given a queue name owned by the provided accountId.
+     * 
+     * @param queueName
+     * @param queueOwnerAccountId The AWS accountId of the account that created the queue
+     * @return The response from the GetQueueUrl service method, as returned by
+     *         AmazonSQS, which will include queue`s URL
+     * @throws JMSException
+     */
+    public GetQueueUrlResult getQueueUrl(String queueName, String queueOwnerAccountId) throws JMSException {
+        GetQueueUrlRequest getQueueUrlRequest = new GetQueueUrlRequest(queueName);
+        getQueueUrlRequest.setQueueOwnerAWSAccountId(queueOwnerAccountId);
+        return getQueueUrl(getQueueUrlRequest);
+    }
 
     /**
+     * Calls <code>getQueueUrl</code> and wraps <code>AmazonClientException</code>
+     * 
      * @param getQueueUrlRequest
      *            Container for the necessary parameters to execute the
      *            getQueueUrl service method on AmazonSQS.
@@ -212,7 +278,8 @@ public GetQueueUrlResult getQueueUrl(GetQueueUrlRequest getQueueUrlRequest) thro
     }
 
     /**
-     * This function creates the queue with the default queue attributes. 
+     * Calls <code>createQueue</code> to create the queue with the default queue attributes,
+     * and wraps <code>AmazonClientException</code>
      * 
      * @param queueName
      * @return The response from the createQueue service method, as returned by
@@ -229,6 +296,9 @@ public CreateQueueResult createQueue(String queueName) throws JMSException {
     }
 
     /**
+     * Calls <code>createQueue</code> to create the queue with the provided queue attributes
+     * if any, and wraps <code>AmazonClientException</code>
+     * 
      * @param createQueueRequest
      *            Container for the necessary parameters to execute the
      *            createQueue service method on AmazonSQS.
@@ -246,6 +316,11 @@ public CreateQueueResult createQueue(CreateQueueRequest createQueueRequest) thro
     }
 
     /**
+     * Calls <code>receiveMessage</code> and wraps <code>AmazonClientException</code>. Used by
+     * {@link SQSMessageConsumerPrefetch} to receive up to minimum of
+     * (<code>numberOfMessagesToPrefetch</code>,10) messages from SQS queue into consumer
+     * prefetch buffers.
+     * 
      * @param receiveMessageRequest
      *            Container for the necessary parameters to execute the
      *            receiveMessage service method on AmazonSQS.
@@ -262,6 +337,9 @@ public ReceiveMessageResult receiveMessage(ReceiveMessageRequest receiveMessageR
     }
 
     /**
+     * Calls <code>changeMessageVisibility</code> and wraps <code>AmazonClientException</code>. This is 
+     * used to for negative acknowledge of a single message, so that messages can be received again without any delay.
+     * 
      * @param changeMessageVisibilityRequest
      *            Container for the necessary parameters to execute the
      *            changeMessageVisibility service method on AmazonSQS.
@@ -278,6 +356,10 @@ public void changeMessageVisibility(ChangeMessageVisibilityRequest changeMessage
     }
 
     /**
+     * Calls <code>changeMessageVisibilityBatch</code> and wraps <code>AmazonClientException</code>. This is
+     * used to for negative acknowledge of messages in batch, so that messages
+     * can be received again without any delay.
+     * 
      * @param changeMessageVisibilityBatchRequest
      *            Container for the necessary parameters to execute the
      *            changeMessageVisibilityBatch service method on AmazonSQS.
@@ -295,8 +377,8 @@ public ChangeMessageVisibilityBatchResult changeMessageVisibilityBatch(ChangeMes
     }
 
     /**
-     * Create generic error message for AmazonServiceException. Message include
-     * ActionCall, RequestId, HTTPStatusCode, AmazonErrorCode.
+     * Create generic error message for <code>AmazonServiceException</code>. Message include
+     * Action, RequestId, HTTPStatusCode, and AmazonErrorCode.
      */
     private String logAndGetAmazonServiceException(AmazonServiceException ase, String action) {
         String errorMessage = "AmazonServiceException: " + action + ". RequestId: " + ase.getRequestId() +
@@ -307,8 +389,8 @@ private String logAndGetAmazonServiceException(AmazonServiceException ase, Strin
     }
 
     /**
-     * Create generic error message for AmazonClientException. Message include
-     * ActionCall.
+     * Create generic error message for <code>AmazonClientException</code>. Message include
+     * Action.
      */
     private String logAndGetAmazonClientException(AmazonClientException ace, String action) {
         String errorMessage = "AmazonClientException: " + action + ".";

src/main/java/com/amazonaws/sqsjms/BulkSQSOperation.java

@@ -31,10 +31,21 @@
 public abstract class BulkSQSOperation {
 
     /**
-     * Bulk action on list of message identifiers up to the indexOfMessage.
+     * Bulk action on list of message identifiers up to the provided index
+     * 
+     * @param messageIdentifierList
+     *            Container for the list of message identifiers
+     * @param indexOfMessage
+     *            The action will apply to all messages up to this index
+     * @throws JMSException
+     *             if <code>action</code> throws
      */
     public void bulkAction(List<SQSMessageIdentifier> messageIdentifierList, int indexOfMessage)
             throws JMSException {
+
+        assert indexOfMessage > 0;
+        assert indexOfMessage <= messageIdentifierList.size();
+
         Map<String, List<String>> receiptHandleWithSameQueueUrl = new HashMap<String, List<String>>();
 
         // Add all messages up to and including requested message into Map.
@@ -66,7 +77,15 @@ public void bulkAction(List<SQSMessageIdentifier> messageIdentifierList, int ind
     }
 
     /**
-     * Action call block for bulk action.
+     * Action call block. This action can be applied on multiple messages for
+     * the same queue.
+     * 
+     * @param queueUrl
+     *            queueUrl of the queue, which the receipt handles belong
+     * @param receiptHandles
+     *            the list of handles, which is be used to (negative)acknowledge
+     *            the messages.
+     * @throws JMSException
      */
     public abstract void action(String queueUrl, List<String> receiptHandles) throws JMSException;
 

src/main/java/com/amazonaws/sqsjms/PrefetchManager.java

@@ -15,7 +15,8 @@
 package com.amazonaws.sqsjms;
 
 /**
- * This interface is helper to notify when the prefetch should be resumed.
+ * This interface is helper to notify when the prefetchThread should be resuming
+ * messages.
  */
 public interface PrefetchManager {
 
@@ -25,6 +26,12 @@ public interface PrefetchManager {
      * called.
      */
     public void messageDispatched();
-    
+
+    /**
+     * This is used to determine the state of the consumer, when the message
+     * listener scheduler is processing the messages.
+     * 
+     * @return The message consumer, which owns the prefetchThread
+     */
     public SQSMessageConsumer getMessageConsumer();
-}
+}