Package org.jclouds.sqs.features

Interface MessageApi

  • public interface MessageApi
    Provides access to SQS via their REST API.

    • Method Detail

      • delete

        @Named("DeleteMessage")
@POST
@Path("/")
void delete​(@FormParam("ReceiptHandle")
            String receiptHandle)
        The DeleteMessage action deletes the specified message from the specified queue. You specify the message by using the message's receipt handle and not the message ID you received when you sent the message. Even if the message is locked by another reader due to the visibility timeout setting, it is still deleted from the queue. If you leave a message in the queue for more than 4 days, SQS automatically deletes it.

        Note

        The receipt handle is associated with a specific instance of receiving the message. If you receive a message more than once, the receipt handle you get each time you receive the message is different. When you request DeleteMessage, if you don't provide the most recently received receipt handle for the message, the request will still succeed, but the message might not be deleted.

        Important

        It is possible you will receive a message even after you have deleted it. This might happen on rare occasions if one of the servers storing a copy of the message is unavailable when you request to delete the message. The copy remains on the server and might be returned to you again on a subsequent receive request. You should create your system to be idempotent so that receiving a particular message more than once is not a problem.
        Parameters:
        queue - the queue the message is in
        receiptHandle - The receipt handle associated with the message you want to delete.

      • delete

        @Named("DeleteMessageBatch")
@POST
@Path("/")
BatchResult<String> delete​(Map<String,​String> idReceiptHandle)
        Currently, you can send up to 10 delete(java.lang.String) requests.

        Example usage

         BatchResult results = api.delete(ImmutableMap.builder()
                                  .put("id1", "handle1")
                                  .put("id2", "handle2")
                                  .build());
 
 if (results.keySet().equals(ImmutableSet.of("id", "id2"))
    // all ok
 else
   results.getErrors();
        Parameters:
        idReceiptHandle - id for correlating the result to receipt handle
        Returns:
        result that contains success or errors of the operation
        See Also:
        delete(String)

      • delete

        @Named("DeleteMessageBatch")
@POST
@Path("/")
BatchResult<String> delete​(Iterable<String> receiptHandles)
        Same as delete(Map), except that we generate numeric ids starting with 1
        Parameters:
        receiptHandles - receipt handles to delete
        See Also:
        delete(Map)

      • changeVisibility

        @Named("ChangeMessageVisibility")
@POST
@Path("/")
void changeVisibility​(@FormParam("ReceiptHandle")
                      String receiptHandle,
                      @FormParam("VisibilityTimeout")
                      int visibilityTimeout)
        The ChangeMessageVisibility action changes the visibility timeout of a specified message in a queue to a new value. The maximum allowed timeout value you can set the value to is 12 hours. This means you can't extend the timeout of a message in an existing queue to more than a total visibility timeout of 12 hours. (For more information visibility timeout, see Visibility Timeout in the Amazon SQS Developer Guide.) For example, let's say the timeout for the queue is 30 seconds, and you receive a message. Once you're 20 seconds into the timeout for that message (i.e., you have 10 seconds left), you extend it by 60 seconds by calling ChangeMessageVisibility with VisibilityTimeoutset to 60 seconds. You have then changed the remaining visibility timeout from 10 seconds to 60 seconds.

        Important

        If you attempt to set the VisibilityTimeout to an amount more than the maximum time left, Amazon SQS returns an error. It will not automatically recalculate and increase the timeout to the maximum time remaining.

        Important

        Unlike with a queue, when you change the visibility timeout for a specific message, that timeout value is applied immediately but is not saved in memory for that message. If you don't delete a message after it is received, the visibility timeout for the message the next time it is received reverts to the original timeout value, not the value you set with the ChangeMessageVisibility action.
        Parameters:
        queue - the queue the message is in
        receiptHandle - The receipt handle associated with the message whose visibility timeout you want to change. This parameter is returned by the ReceiveMessage action.
        visibilityTimeout - The new value for the message's visibility timeout (in seconds) from 0 to 43200 (maximum 12 hours)

      • changeVisibility

        @Named("ChangeMessageVisibilityBatch")
@POST
@Path("/")
BatchResult<String> changeVisibility​(com.google.common.collect.Table<String,​String,​Integer> idReceiptHandleVisibilityTimeout)
        Currently, you can send up to 10 changeVisibility(java.lang.String, int) requests. action.

        Example usage

         BatchResult results = api.changeVisibility(ImmutableTable.builder()
                                  .put("id1", "handle1", 45)
                                  .put("id2", "handle2", 10)
                                  .build());
 
 if (results.keySet().equals(ImmutableSet.of("id", "id2"))
    // all ok
 else
   results.getErrors();
        Parameters:
        idReceiptHandleVisibilityTimeout - id for correlating the result, receipt handle, and visibility timeout
        Returns:
        result that contains success or errors of the operation
        See Also:
        changeVisibility(String, int)

      • changeVisibility

        @Named("ChangeMessageVisibilityBatch")
@POST
@Path("/")
BatchResult<String> changeVisibility​(Map<String,​String> idReceiptHandle,
                                     int visibilityTimeout)
        Currently, you can send up to 10 changeVisibility(java.lang.String, int) requests. action.

        Example usage

         BatchResult results = api.changeVisibility(ImmutableMap.builder()
                                  .put("id1", "handle1")
                                  .put("id2", "handle2")
                                  .build(), 45);
 
 if (results.keySet().equals(ImmutableSet.of("id", "id2"))
    // all ok
 else
   results.getErrors();
        Parameters:
        idReceiptHandle - id for correlating the result to receipt handle
        visibilityTimeout - The new value for the message's visibility timeout (in seconds).
        Returns:
        result that contains success or errors of the operation
        See Also:
        changeVisibility(String, int)

      • send

        @Named("SendMessage")
@POST
@Path("/")
MessageIdAndMD5 send​(@FormParam("MessageBody")
                     String message)
        The SendMessage action delivers a message to the specified queue. The maximum allowed message size is 64 KB.

        Important

        The following list shows the characters (in Unicode) allowed in your message, according to the W3C XML specification (for more information, go to http://www.w3.org/TR/REC-xml/#charsets). If you send any characters not included in the list, your request will be rejected. #x9 | #xA | #xD | [#x20 to #xD7FF] | [#xE000 to #xFFFD] | [#x10000 to #x10FFFF]
        Parameters:
        queue - queue you want to send to
        message - Type: String maximum 64 KB in size. For a list of allowed characters, see the preceding important note.
        Returns:
        id of the message and md5 of the content sent

      • send

        @Named("SendMessage")
@POST
@Path("/")
MessageIdAndMD5 send​(@FormParam("MessageBody")
                     String message,
                     SendMessageOptions options)
        same as #sendMessage(URI, String) except you can control options such as delay seconds.
        Parameters:
        options - options such as delay seconds
        See Also:
        #sendMessage(URI, String)

      • sendWithDelays

        @Named("SendMessageBatch")
@POST
@Path("/")
BatchResult<? extends MessageIdAndMD5> sendWithDelays​(com.google.common.collect.Table<String,​String,​Integer> idMessageBodyDelaySeconds)
        Same as send(Map) except you can set a delay for each message in the request.

        Example usage

         BatchResult results = api.sendWithDelays(ImmutableTable.builder()
                                  .put("id1", "test message one", 1)
                                  .put("id2", "test message two", 10)
                                  .build());
 
 if (results.keySet().equals(ImmutableSet.of("id", "id2"))
    // all ok
 else
   results.getErrors();
        Parameters:
        idMessageBodyDelaySeconds - id for correlating the result, message body, and delay seconds
        Returns:
        result that contains success or errors of the operation
        See Also:
        send(String, SendMessageOptions)

      • sendWithDelay

        @Named("SendMessageBatch")
@POST
@Path("/")
BatchResult<? extends MessageIdAndMD5> sendWithDelay​(Map<String,​String> idMessageBody,
                                                     int delaySeconds)
        Same as send(Map) except you set a delay for all messages in the request
        Parameters:
        delaySeconds - The number of seconds to delay a specific message. Messages with a positive DelaySeconds value become available for processing after the delay time is finished.
        See Also:
        send(String, SendMessageOptions)

      • send

        @Named("SendMessageBatch")
@POST
@Path("/")
BatchResult<? extends MessageIdAndMD5> send​(Map<String,​String> idMessageBody)
        The SendMessageBatch action delivers up to ten messages to the specified queue. The maximum allowed individual message size is 64 KiB (65,536 bytes). The maximum total payload size (i.e., the sum of all a batch's individual message lengths) is also 64 KiB (65,536 bytes). Currently, you can send up to 10 send(java.lang.String) requests. action.

        Example usage

         BatchResult results = api.send(ImmutableMap.builder()
                                  .put("id1", "test message one")
                                  .put("id2", "test message two")
                                  .build());
 
 if (results.keySet().equals(ImmutableSet.of("id", "id2"))
    // all ok
 else
   results.getErrors();
        Parameters:
        idMessageBody - id for correlating the result to message body
        Returns:
        result that contains success or errors of the operation
        See Also:
        send(String)

      • receive

        @Named("ReceiveMessage")
@POST
@Path("/")
Message receive()
        The ReceiveMessage action retrieves one or more messages from the specified queue. The ReceiveMessage action does not delete the message after it is retrieved. To delete a message, you must use the DeleteMessage action. For more information about message deletion in the message life cycle, see Message Lifecycle.

        Note

        Due to the distributed nature of the queue, a weighted random set of machines is sampled on a ReceiveMessage call. That means only the messages on the sampled machines are returned. If the number of messages in the queue is small (less than 1000), it is likely you will get fewer messages than you requested per ReceiveMessage call. If the number of messages in the queue is extremely small, you might not receive any messages in a particular ReceiveMessage response; in which case you should repeat the request.
        Parameters:
        queue - from where you are receiving messages
        Returns:
        message including the receipt handle you can use to delete it

      • receive

        @Named("ReceiveMessage")
@POST
@Path("/")
Message receive​(ReceiveMessageOptions options)
        same as #receive(URI) except you can provide options like VisibilityTimeout parameter in your request, which will be applied to the messages that SQS returns in the response. If you do not include the parameter, the overall visibility timeout for the queue is used for the returned messages.
        Parameters:
        options - options such as VisibilityTimeout
        See Also:
        #receive(URI)

      • receive

        @Named("ReceiveMessage")
@POST
@Path("/")
com.google.common.collect.FluentIterable<Message> receive​(@FormParam("MaxNumberOfMessages")
                                                          int max)
        same as #receive(URI) except you can receive multiple messages.
        Parameters:
        max - maximum messages to receive, current limit is 10
        See Also:
        #receive(URI)

      • receive

        @Named("ReceiveMessage")
@POST
@Path("/")
com.google.common.collect.FluentIterable<Message> receive​(@FormParam("MaxNumberOfMessages")
                                                          int max,
                                                          ReceiveMessageOptions options)
        same as #receive(URI, int) except you can provide options like VisibilityTimeout parameter in your request, which will be applied to the messages that SQS returns in the response. If you do not include the parameter, the overall visibility timeout for the queue is used for the returned messages.
        Parameters:
        options - options such as VisibilityTimeout
        See Also:
        #receive(URI, int)