MessageApi (jclouds 1.5.5 API)

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

Author:

Adrian Cole

See Also:
MessageAsyncApi

Method Summary

Methods
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<? extends 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
```
void delete(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
```
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
```
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
```
void changeVisibility(String receiptHandle,
                    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
```
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
```
BatchResult<? extends 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
```
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
```
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
```
MessageIdAndMD5 send(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
  - sendWithDelays
```
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
```
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
```
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
```
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
```
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
```
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)
  - send
```
MessageIdAndMD5 send(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)
  - receive
```
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
```
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
```
com.google.common.collect.FluentIterable<Message> receive(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
```
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. 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)

Interface MessageApi

Method Summary

Method Detail

delete

Note

Important

delete

Example usage

delete

changeVisibility

Important

Important

changeVisibility

Example usage

changeVisibility

changeVisibility

Example usage

changeVisibility

send

Important

sendWithDelays

Example usage

sendWithDelays

sendWithDelay

sendWithDelay

send

Example usage

send

send

receive

Note

receive

receive

receive