org.jclouds.sqs.features

Interface MessageApi

public interface MessageApi

Provides access to SQS via their REST API.

Method Summary

Modifier and Type	Method and Description
BatchResult<String>	changeVisibility(Iterable<String> receiptHandles, int visibilityTimeout) Same as changeVisibility(Map, int), except that we generate numeric ids starting with 1
BatchResult<MessageIdAndMD5>	changeVisibility(Map<String,Integer> receiptHandleVisibilityTimeout) Same as changeVisibility(Table), except that we generate numeric ids starting with 1
BatchResult<String>	changeVisibility(Map<String,String> idReceiptHandle, int visibilityTimeout) Currently, you can send up to 10 changeVisibility(java.lang.String, int) requests.
void	changeVisibility(String receiptHandle, int visibilityTimeout) The ChangeMessageVisibility action changes the visibility timeout of a specified message in a queue to a new value.
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.
BatchResult<String>	delete(Iterable<String> receiptHandles) Same as delete(Map), except that we generate numeric ids starting with 1
BatchResult<String>	delete(Map<String,String> idReceiptHandle) Currently, you can send up to 10 delete(java.lang.String) requests.
void	delete(String receiptHandle) The DeleteMessage action deletes the specified message from the specified queue.
Message	receive() The ReceiveMessage action retrieves one or more messages from the specified queue.
com.google.common.collect.FluentIterable<Message>	receive(int max) same as #receive(URI) except you can receive multiple messages.
com.google.common.collect.FluentIterable<Message>	receive(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.
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.
BatchResult<? extends MessageIdAndMD5>	send(Iterable<String> messageBodies) Same as send(Map), except that we generate numeric ids starting with 1
BatchResult<? extends MessageIdAndMD5>	send(Map<String,String> idMessageBody) The SendMessageBatch action delivers up to ten messages to the specified queue.
MessageIdAndMD5	send(String message) The SendMessage action delivers a message to the specified queue.
MessageIdAndMD5	send(String message, SendMessageOptions options) same as #sendMessage(URI, String) except you can control options such as delay seconds.
BatchResult<? extends MessageIdAndMD5>	sendWithDelay(Iterable<String> messageBodies, int delaySeconds) Same as sendWithDelay(Map, int), except that we generate numeric ids starting with 1
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
BatchResult<? extends MessageIdAndMD5>	sendWithDelays(Map<String,Integer> messageBodyDelaySeconds) Same as sendWithDelays(Table), except that we generate numeric ids starting with 1
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.

Method Detail

delete

@Named(value="DeleteMessage")
 @POST
 @Path(value="/")
void delete(@FormParam(value="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(value="DeleteMessageBatch")
 @POST
 @Path(value="/")
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(value="DeleteMessageBatch")
 @POST
 @Path(value="/")
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(value="ChangeMessageVisibility")
 @POST
 @Path(value="/")
void changeVisibility(@FormParam(value="ReceiptHandle")
                                                                                       String receiptHandle,
                                                                                       @FormParam(value="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(value="ChangeMessageVisibilityBatch")
 @POST
 @Path(value="/")
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(value="ChangeMessageVisibilityBatch")
 @POST
 @Path(value="/")
BatchResult<MessageIdAndMD5> changeVisibility(Map<String,Integer> receiptHandleVisibilityTimeout)

Same as changeVisibility(Table), except that we generate numeric ids starting with 1

Parameters:

receiptHandleVisibilityTimeout - receipt handle to visibility timeout

See Also:

changeVisibility(Table)

changeVisibility

@Named(value="ChangeMessageVisibilityBatch")
 @POST
 @Path(value="/")
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)

changeVisibility

@Named(value="ChangeMessageVisibilityBatch")
 @POST
 @Path(value="/")
BatchResult<String> changeVisibility(Iterable<String> receiptHandles,
                                                                                                           int visibilityTimeout)

Same as changeVisibility(Map, int), except that we generate numeric ids starting with 1

Parameters:

receiptHandles - receipt handles to change visibility

See Also:

changeVisibility(Map, int)

send

@Named(value="SendMessage")
 @POST
 @Path(value="/")
MessageIdAndMD5 send(@FormParam(value="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(value="SendMessage")
 @POST
 @Path(value="/")
MessageIdAndMD5 send(@FormParam(value="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(value="SendMessageBatch")
 @POST
 @Path(value="/")
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)

sendWithDelays

@Named(value="SendMessageBatch")
 @POST
 @Path(value="/")
BatchResult<? extends MessageIdAndMD5> sendWithDelays(Map<String,Integer> messageBodyDelaySeconds)

Same as sendWithDelays(Table), except that we generate numeric ids starting with 1

Parameters:

messageBodyDelaySeconds - message body to the delay desired

See Also:

sendWithDelays(Table)

sendWithDelay

@Named(value="SendMessageBatch")
 @POST
 @Path(value="/")
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)

sendWithDelay

@Named(value="SendMessageBatch")
 @POST
 @Path(value="/")
BatchResult<? extends MessageIdAndMD5> sendWithDelay(Iterable<String> messageBodies,
                                                                                                               int delaySeconds)

Same as sendWithDelay(Map, int), except that we generate numeric ids starting with 1

Parameters:

messageBodies - message bodies to send

See Also:

sendWithDelay(Map, int)

send

@Named(value="SendMessageBatch")
 @POST
 @Path(value="/")
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)

send

@Named(value="SendMessageBatch")
 @POST
 @Path(value="/")
BatchResult<? extends MessageIdAndMD5> send(Iterable<String> messageBodies)

Same as send(Map), except that we generate numeric ids starting with 1

Parameters:

messageBodies - message bodies to send

See Also:

send(Map)

receive

@Named(value="ReceiveMessage")
 @POST
 @Path(value="/")
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(value="ReceiveMessage")
 @POST
 @Path(value="/")
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(value="ReceiveMessage")
 @POST
 @Path(value="/")
com.google.common.collect.FluentIterable<Message> receive(@FormParam(value="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(value="ReceiveMessage")
 @POST
 @Path(value="/")
com.google.common.collect.FluentIterable<Message> receive(@FormParam(value="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)