Merge pull request #11 from dacamo76/readme-long-polling-example

Update README with long-polling usage example

README.md

@@ -14,14 +14,14 @@ Bandalore is available in Maven central.  Add it to your Maven project's `pom.xm
 <dependency>
   <groupId>com.cemerick</groupId>
   <artifactId>bandalore</artifactId>
-  <version>0.0.4</version>
+  <version>0.0.6</version>
 </dependency>
 ```
 
 or your leiningen project.clj:
 
 ```clojure
-[com.cemerick/bandalore "0.0.4"]
+[com.cemerick/bandalore "0.0.6"]
 ```
 
 Bandalore is compatible with Clojure 1.2.0+.
@@ -56,7 +56,7 @@ to do anything:
 
 **Security Note** If your application using Bandalore is deployed to EC2, _you
 should not put your AWS credentials on those EC2 nodes_.  Rather,
-  [give your EC2 instances IAM roles](http://docs.aws.amazon.com/IAM/latest/UserGuide/role-usecase-ec2app.html),
+  [give your EC2 instances IAM roles](http://docs.aws.amazon.com/AWSSdkDocsJava/latest/DeveloperGuide/java-dg-roles.html),
   and use the nullary arity of `create-client`:
   
 ```clojure
@@ -108,6 +108,28 @@ That's cleaner than having to interop directly with the Java SDK, but it's all
 pretty pedestrian stuff.  You can do more interesting things with some
 simple higher-order functions and other nifty Clojure facilities.
 
+### Enabling SQS Long Polling
+
+[Long polling](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-long-polling.html) reduces the number of empty responses by allowing Amazon SQS service to wait until a message is available in the queue before sending a response. You can enable long polling on an individual receive request by supplying the optional kwarg `:wait-time-seconds`:
+
+  :wait-time-seconds - time in seconds (bewteen 0 and 20) for SQS to wait if there are no messages in the queue. A value of 0 indicates no long polling.
+
+```clojure
+   ; ensure our queue is empty to start
+#> (get (sqs/queue-attrs client q) "ApproximateNumberOfMessages")
+"0"
+#> (let [no-polling (future (sqs/receive client q))
+         long-polling (future (sqs/receive client q :wait-time-seconds 20))]
+    (Thread/sleep 10000)                 ;; Sleep 10s before sending message
+    (sqs/send client q "my message body")
+    (println (count @no-polling))
+    (println (count @long-polling)))
+0
+1
+nil
+
+```
+
 ### Sending and receiving Clojure values
 
 SQS' message bodies are strings, so you can stuff anything in them that you can

pom.xml

@@ -2,7 +2,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.cemerick</groupId>
     <artifactId>bandalore</artifactId>
-    <version>0.0.4</version>
+    <version>0.0.7-SNAPSHOT</version>
     <name>bandalore</name>
     <description>A Clojure library for Amazon's Simple Queue Service (SQS).</description>
     <url>http://github.com/cemerick/bandalore</url>
@@ -36,7 +36,7 @@
         <dependency>
             <groupId>com.amazonaws</groupId>
             <artifactId>aws-java-sdk</artifactId>
-            <version>1.3.21.1</version>
+            <version>1.8.0</version>
         </dependency>
     </dependencies>
 

src/main/clojure/cemerick/bandalore.clj

@@ -50,9 +50,10 @@
   (.deleteQueue client (DeleteQueueRequest. queue-url)))
 
 (defn list-queues
-  "Returns a seq of all queues' URL strings."
-  [^AmazonSQSClient client]
-  (->> (ListQueuesRequest.)
+  "Returns a seq of all queues' URL strings.  Takes an optional string prefix
+  argument to only list queues with names that start with the prefix."
+  [^AmazonSQSClient client & {:keys [prefix]}]
+  (->> (ListQueuesRequest. prefix)
     (.listQueues client)
     .getQueueUrls
     seq))
@@ -105,6 +106,11 @@
              Defaults to the empty set (i.e. no attributes will be included in
              received messages).
              See the SQS documentation for all support message attributes.
+   :wait-time-seconds - enables long poll support. time is in seconds, bewteen
+             0 (default - no long polling) and 20.
+             Allows Amazon SQS service to wait until a message is available
+             in the queue before sending a response.
+             See the SQS documentation at (http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-long-polling.html)
 
    Returns a seq of maps with these slots:
    
@@ -115,13 +121,17 @@
    :receipt-handle - the ID used to delete the message from the queue after
              it has been fully processed.
    :source-queue - the URL of the queue from which the message was received"
-  [^AmazonSQSClient client queue-url & {:keys [limit visibility ^java.util.Collection attributes]
+  [^AmazonSQSClient client queue-url & {:keys [limit
+                                               visibility
+                                               wait-time-seconds
+                                               ^java.util.Collection attributes]
                                         :or {limit 1
                                              attributes #{}}}]
   (let [req (-> (ReceiveMessageRequest. queue-url)
-              (.withMaxNumberOfMessages (-> limit (min 10) (max 1) int Integer.))
+              (.withMaxNumberOfMessages (-> limit (min 10) (max 1) int Integer/valueOf))
               (.withAttributeNames attributes))
-        req (if visibility (.withVisibilityTimeout req (Integer. (int visibility))) req)]
+        req (if wait-time-seconds (.withWaitTimeSeconds req (Integer/valueOf (int wait-time-seconds))) req)
+        req (if visibility (.withVisibilityTimeout req (Integer/valueOf (int visibility))) req)]
     (->> (.receiveMessage client req)
       .getMessages
       (map (partial message-map queue-url)))))

src/test/clojure/cemerick/bandalore_test.clj

@@ -59,7 +59,9 @@
     ; sending a msg seems to "force" the queue's existence in listings
     (send client *test-queue-url* msg)
     (wait-for-condition #((set (list-queues client)) *test-queue-url*)
-      "Created queue not visible in result of list-queues")))
+      "Created queue not visible in result of list-queues")
+    (wait-for-condition #((set (list-queues client :prefix test-queue-name-prefix)) *test-queue-url*)
+      "Created queue not visible in result of list-queues with prefix")))
 
 (defsqstest test-queue-attrs
   (let [{:strs [MaximumMessageSize] :as base-attrs} (queue-attrs client *test-queue-url*)
@@ -119,3 +121,11 @@
   (let [v (-> (receive client *test-queue-url* :visibility 5) first :body read-string)]
     (is (some #(= v (-> % :body read-string)) (polling-receive client *test-queue-url* :max-wait 10000)))))
 
+(defsqstest test-receive-long-polling
+  (let [q *test-queue-url*
+        no-poll (future (receive client q))
+        long-poll (future (receive client q :wait-time-seconds 20))]
+    (Thread/sleep 10000)
+    (send client q "1")
+    (is (== 0 (count @no-poll)) "Should not return messages")
+    (is (== 1 (count @long-poll)) "Should return 1 message")))