* Welcome to the Amazon Simple Queue Service API Reference. This section * describes who should read this guide, how the guide is organized, and other * resources related to the Amazon Simple Queue Service (Amazon SQS). *
** Amazon SQS offers reliable and scalable hosted queues for storing messages as * they travel between computers. By using Amazon SQS, you can move data between * distributed components of your applications that perform different tasks * without losing messages or requiring each component to be always available. *
** Topics *
**
*
* CommonParameters *
** CommonErrors *
** Helpful Links *
** We also provide SDKs that enable you to access Amazon SQS from your preferred * programming language. The SDKs contain functionality that automatically takes * care of tasks such as: *
** Cryptographically signing your service requests *
** Retrying requests *
** Handling error responses *
** For a list of available SDKs, see Tools for Amazon Web Services. *
**/ public interface AmazonSQS { /** * Overrides the default endpoint for this client * ("https://sqs.us-east-1.amazonaws.com"). Callers can use this method to * control which AWS region they want to work with. ** Callers can pass in just the endpoint (ex: "sqs.us-east-1.amazonaws.com") * or a full URL, including the protocol (ex: * "https://sqs.us-east-1.amazonaws.com"). If the protocol is not specified * here, the default protocol from this client's {@link ClientConfiguration} * will be used, which by default is HTTPS. *
* For more information on using AWS regions with the AWS SDK for Java, and * a complete list of all available endpoints for all AWS services, see: http://developer.amazonwebservices.com/connect/entry.jspa?externalID= * 3912 *
* This method is not threadsafe. An endpoint should be configured when * the client is created and before any service requests are made. Changing * it afterwards creates inevitable race conditions for any service requests * in transit or retrying. * * @param endpoint The endpoint (ex: "sqs.us-east-1.amazonaws.com") or a * full URL, including the protocol (ex: * "https://sqs.us-east-1.amazonaws.com") of the region specific * AWS endpoint this client will communicate with. * @throws IllegalArgumentException If any problems are detected with the * specified endpoint. */ public void setEndpoint(String endpoint) throws java.lang.IllegalArgumentException; /** * An alternative to {@link AmazonSQS#setEndpoint(String)}, sets the * regional endpoint for this client's service calls. Callers can use this * method to control which AWS region they want to work with. *
* By default, all service endpoints in all regions use the https protocol. * To use http instead, specify it in the {@link ClientConfiguration} * supplied at construction. *
* This method is not threadsafe. A region should be configured when the * client is created and before any service requests are made. Changing it * afterwards creates inevitable race conditions for any service requests in * transit or retrying. * * @param region The region this client will communicate with. See * {@link Region#getRegion(com.amazonaws.regions.Regions)} for * accessing a given region. * @throws java.lang.IllegalArgumentException If the given region is null, * or if this service isn't available in the given region. See * {@link Region#isServiceSupported(String)} * @see Region#getRegion(com.amazonaws.regions.Regions) * @see Region#createClient(Class, * com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration) */ public void setRegion(Region region) throws java.lang.IllegalArgumentException; /** *
* Adds a permission to a queue for a specific principal. This allows for sharing access to the queue. *
** When you create a queue, you have full control access rights for the * queue. Only you (as owner of the queue) can grant or deny permissions to * the queue. For more information about these permissions, see Shared Queues in the Amazon SQS Developer Guide. *
*
* AddPermission writes an Amazon SQS-generated policy. If you
* want to write your own policy, use SetQueueAttributes to upload
* your policy. For more information about writing your own policy, see Using The Access Policy Language in the Amazon SQS Developer
* Guide.
*
* Some API actions take lists of parameters. These lists are specified
* using the param.n notation. Values of n are
* integers starting from 1. For example, a parameter list with two elements
* looks like this:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* 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 you have a message and its default message
* visibility timeout is 5 minutes. After 3 minutes, you call
* ChangeMessageVisiblity with a timeout of 10 minutes. At that
* time, the timeout for the message would be extended by 10 minutes beyond
* the time of the ChangeMessageVisibility call. This results in a total
* visibility timeout of 13 minutes. You can continue to call
* ChangeMessageVisibility to extend the visibility timeout to a maximum of
* 12 hours. If you try to extend beyond 12 hours, the request will be
* rejected.
*
* There is a 120,000 limit for the number of inflight messages per queue. * Messages are inflight after they have been received from the queue by a * consuming component, but have not yet been deleted from the queue. If you * reach the 120,000 limit, you will receive an OverLimit error message from * Amazon SQS. To help avoid reaching the limit, you should delete the * messages from the queue after they have been processed. You can also * increase the number of queues you use to process the messages. *
*
* 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.
*
* 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.
*
* Changes the visibility timeout of multiple messages. This is a batch
* version of ChangeMessageVisibility. The result of the action on
* each message is reported individually in the response. You can send up to
* 10 ChangeMessageVisibility requests with each
* ChangeMessageVisibilityBatch action.
*
* Because the batch request can result in a combination of successful and * unsuccessful actions, you should check for batch errors even when the * call returns an HTTP status code of 200. *
*
* Some API actions take lists of parameters. These lists are specified
* using the param.n notation. Values of n are
* integers starting from 1. For example, a parameter list with two elements
* looks like this:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* Creates a new standard or FIFO queue or returns the URL of an existing * queue. You can pass one or more attributes in the request. *
*
* If you don't specify the FifoQueue attribute, Amazon SQS
* creates a standard queue.
*
* You can't change the queue type after you create it and you can't convert * an existing standard queue into a FIFO queue. You must either create a * new FIFO queue for your application or delete your existing standard * queue and recreate it as a FIFO queue. For more information, see Moving From a Standard Queue to a FIFO Queue in the Amazon SQS * Developer Guide. *
** If you don't provide a value for an attribute, the queue is created with * the default value for the attribute. *
** If you delete a queue, you must wait at least 60 seconds before creating * a queue with the same name. *
** To successfully create a new queue, you must provide a queue name that * adheres to the limits related to queues and is unique within the scope of your * queues. *
*
* To get the queue URL, use the GetQueueUrl action.
* GetQueueUrl requires only the QueueName parameter.
*
* If you provide the name of an existing queue along with the exact names
* and values of all the queue's attributes, CreateQueue
* returns the queue URL for the existing queue.
*
* If the queue name, attribute names, or attribute values don't match an
* existing queue, CreateQueue returns an error.
*
* Some API actions take lists of parameters. Specify these lists using the
* param.n notation. Values of n are integers
* starting from 1. The following is an example of a parameter list with two
* elements:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* 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 longer than the queue's configured retention period, Amazon
* SQS automatically deletes it.
*
* 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.
*
* 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. *
** Deletes up to ten messages from the specified queue. This is a batch * version of DeleteMessage. The result of the delete action on each * message is reported individually in the response. *
** Because the batch request can result in a combination of successful and * unsuccessful actions, you should check for batch errors even when the * call returns an HTTP status code of 200. *
*
* Some API actions take lists of parameters. These lists are specified
* using the param.n notation. Values of n are
* integers starting from 1. For example, a parameter list with two elements
* looks like this:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* Deletes the queue specified by the queue URL, regardless of * whether the queue is empty. If the specified queue doesn't exist, Amazon * SQS returns a successful response. *
*
* Use DeleteQueue with care; once you delete your queue, any
* messages in the queue are no longer available.
*
* When you delete a queue, the deletion process takes up to 60 seconds. * Requests you send involving that queue during the 60 seconds might * succeed. For example, a SendMessage request might succeed, but * after the 60 seconds, the queue and that message you sent no longer * exist. Also, when you delete a queue, you must wait at least 60 seconds * before creating a queue with the same name. *
** We reserve the right to delete queues that have had no activity for more * than 30 days. For more information, see How Amazon SQS Queues Work in the Amazon SQS Developer Guide. *
* * @param deleteQueueRequest * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ void deleteQueue(DeleteQueueRequest deleteQueueRequest) throws AmazonClientException, AmazonServiceException; /** ** Gets attributes for the specified queue. *
*
* Some API actions take lists of parameters. These lists are specified
* using the param.n notation. Values of n are
* integers starting from 1. For example, a parameter list with two elements
* looks like this:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* Returns the URL of an existing queue. This action provides a simple way * to retrieve the URL of an Amazon SQS queue. *
*
* To access a queue that belongs to another AWS account, use the
* QueueOwnerAWSAccountId parameter to specify the account ID
* of the queue's owner. The queue's owner must grant you permission to
* access the queue. For more information about shared queue access, see
* AddPermission or see Shared Queues in the Amazon SQS Developer Guide.
*
* Returns a list of your queues that have the RedrivePolicy queue attribute * configured with a dead letter queue. *
** For more information about using dead letter queues, see Using Amazon SQS Dead Letter Queues in the Amazon SQS Developer * Guide. *
* * @param listDeadLetterSourceQueuesRequest * @return listDeadLetterSourceQueuesResult The response from the * ListDeadLetterSourceQueues service method, as returned by Amazon * SQS. * @throws QueueDoesNotExistException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ ListDeadLetterSourceQueuesResult listDeadLetterSourceQueues( ListDeadLetterSourceQueuesRequest listDeadLetterSourceQueuesRequest) throws AmazonClientException, AmazonServiceException; /** *
* Returns a list of your queues. The maximum number of queues that can be
* returned is 1000. If you specify a value for the optional
* QueueNamePrefix parameter, only queues with a name beginning
* with the specified value are returned.
*
* Deletes the messages in a queue specified by the queue URL. *
*
* When you use the PurgeQueue API, the deleted messages in the
* queue can't be retrieved.
*
* When you purge a queue, the message deletion process takes up to 60
* seconds. All messages sent to the queue before calling
* PurgeQueue will be deleted; messages sent to the queue while
* it is being purged might be deleted. While the queue is being purged,
* messages sent to the queue before PurgeQueue was called
* might be received, but will be deleted within the next minute.
*
* Retrieves one or more messages, with a maximum limit of 10 messages, from
* the specified queue. Long poll support is enabled by using the
* WaitTimeSeconds parameter. For more information, see Amazon SQS Long Poll in the Amazon SQS Developer Guide.
*
* Short poll is the default behavior where a weighted random set of
* machines is sampled on a ReceiveMessage call. This 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.
*
* For each message returned, the response includes the following: *
** Message body *
** MD5 digest of the message body. For information about MD5, see RFC1321. *
** Message ID you received when you sent the message to the queue. *
** Receipt handle. *
** Message attributes. *
** MD5 digest of the message attributes. *
** The receipt handle is the identifier you must provide when deleting the * message. For more information, see Queue and Message Identifiers in the Amazon SQS Developer * Guide. *
*
* You can provide the VisibilityTimeout parameter in your
* request, which will be applied to the messages that Amazon SQS returns in
* the response. If you don't include the parameter, the overall visibility
* timeout for the queue is used for the returned messages. For more
* information, see Visibility Timeout in the Amazon SQS Developer Guide.
*
* A message that is not deleted or a message whose visibility is not * extended before the visibility timeout expires counts as a failed * receive. Depending on the configuration of the queue, the message might * be sent to the dead letter queue. *
** Going forward, new attributes might be added. If you are writing code * that calls this action, we recommend that you structure your code so that * it can handle new attributes gracefully. *
*
* Revokes any permissions in the queue policy that matches the specified
* Label parameter. Only the owner of the queue can remove
* permissions.
*
* Delivers a message to the specified queue. *
** The following list shows the characters (in Unicode) that are allowed in * your message, according to the W3C XML specification: *
*
* #x9 | #xA | #xD | [
* #x20 to #xD7FF] | [#xE000 to
* #xFFFD] | [#x10000 to #x10FFFF]
*
* For more information, see RFC1321. If you send any * characters that aren't included in this list, your request will be * rejected. *
*
* Delivers up to ten messages to the specified queue. This is a batch
* version of SendMessage . For a FIFO queue, multiple
* messages within a single batch are enqueued in the order they are sent.
*
* The result of sending each message is reported individually in the * response. Because the batch request can result in a combination of * successful and unsuccessful actions, you should check for batch errors * even when the call returns an HTTP status code of 200. *
** The maximum allowed individual message size and the maximum total payload * size (the sum of the individual lengths of all of the batched messages) * are both 256 KB (262,144 bytes). *
** The following list shows the characters (in Unicode) that are allowed in * your message, according to the W3C XML specification: *
*
* #x9 | #xA | #xD | [
* #x20 to #xD7FF] | [#xE000 to
* #xFFFD] | [#x10000 to #x10FFFF]
*
* For more information, see RFC1321. If you send any * characters that aren't included in this list, your request will be * rejected. *
*
* If you don't specify the DelaySeconds parameter for an
* entry, Amazon SQS uses the default for the queue.
*
* Some API actions take lists of parameters. These lists are specified
* using the param.n notation. Values of n are
* integers starting from 1. For example, a parameter list with two elements
* looks like this:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* Sets the value of one or more queue attributes. When you change a queue's
* attributes, the change can take up to 60 seconds for most of the
* attributes to propagate throughout the SQS system. Changes made to the
* MessageRetentionPeriod attribute can take up to 15 minutes.
*
* In the future, new attributes might be added. When you write code that * calls this action, we recommend structuring your code so that it can * handle new attributes gracefully. *
** Gets attributes for the specified queue. *
*
* Some API actions take lists of parameters. These lists are specified
* using the param.n notation. Values of n are
* integers starting from 1. For example, a parameter list with two elements
* looks like this:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @param attributeNames* A list of attributes for which to retrieve information. *
** Going forward, new attributes might be added. If you are * writing code that calls this action, we recommend that you * structure your code so that it can handle new attributes * gracefully. *
** The following attributes are supported: *
*
* All - Returns all values.
*
* ApproximateNumberOfMessages - Returns the
* approximate number of visible messages in a queue. For more
* information, see Resources Required to Process Messages in the Amazon
* SQS Developer Guide.
*
* ApproximateNumberOfMessagesDelayed - Returns the
* approximate number of messages that are waiting to be added to
* the queue.
*
* ApproximateNumberOfMessagesNotVisible - Returns
* the approximate number of messages that have not timed-out and
* are not deleted. For more information, see Resources Required to Process Messages in the Amazon
* SQS Developer Guide.
*
* CreatedTimestamp - Returns the time when the
* queue was created in seconds (epoch time).
*
* DelaySeconds - Returns the default delay on the
* queue in seconds.
*
* LastModifiedTimestamp - Returns the time when the
* queue was last changed in seconds (epoch time).
*
* MaximumMessageSize - Returns the limit of how
* many bytes a message can contain before Amazon SQS rejects it.
*
* MessageRetentionPeriod - Returns the number of
* seconds for which Amazon SQS retains a message.
*
* Policy - Returns the policy of the queue.
*
* QueueArn - Returns the Amazon resource name (ARN)
* of the queue.
*
* ReceiveMessageWaitTimeSeconds - Returns the
* number of seconds for which ReceiveMessage call will wait for
* a message to arrive.
*
* RedrivePolicy - Returns the parameters for dead
* letter queue functionality of the source queue. For more
* information about the redrive policy and dead letter queues,
* see Using Amazon SQS Dead Letter Queues in the Amazon SQS
* Developer Guide.
*
* VisibilityTimeout - Returns the visibility
* timeout for the queue. For more information about the
* visibility timeout, see Visibility Timeout in the Amazon SQS Developer
* Guide.
*
* The following attributes apply only to FIFO (first-in-first-out) queues: *
*
* FifoQueue - Returns whether the queue is FIFO.
* For more information, see FIFO Queue Logic in the Amazon SQS Developer
* Guide.
*
* ContentBasedDeduplication - Returns whether
* content-based deduplication is enabled for the queue. For more
* information, see Exactly-Once Processing in the Amazon SQS Developer
* Guide.
*
* Creates a new standard or FIFO queue or returns the URL of an existing * queue. You can pass one or more attributes in the request. *
*
* If you don't specify the FifoQueue attribute, Amazon SQS
* creates a standard queue.
*
* You can't change the queue type after you create it and you can't convert * an existing standard queue into a FIFO queue. You must either create a * new FIFO queue for your application or delete your existing standard * queue and recreate it as a FIFO queue. For more information, see Moving From a Standard Queue to a FIFO Queue in the Amazon SQS * Developer Guide. *
** If you don't provide a value for an attribute, the queue is created with * the default value for the attribute. *
** If you delete a queue, you must wait at least 60 seconds before creating * a queue with the same name. *
** To successfully create a new queue, you must provide a queue name that * adheres to the limits related to queues and is unique within the scope of your * queues. *
*
* To get the queue URL, use the GetQueueUrl action.
* GetQueueUrl requires only the QueueName parameter.
*
* If you provide the name of an existing queue along with the exact names
* and values of all the queue's attributes, CreateQueue
* returns the queue URL for the existing queue.
*
* If the queue name, attribute names, or attribute values don't match an
* existing queue, CreateQueue returns an error.
*
* Some API actions take lists of parameters. Specify these lists using the
* param.n notation. Values of n are integers
* starting from 1. The following is an example of a parameter list with two
* elements:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* The name of the new queue. The following limits apply to this * name: *
** A queue name can have up to 80 characters. *
*
* The following are accepted: alphanumeric chatacters, hyphens (
* -), and underscores (_).
*
* A FIFO queue name must end with the .fifo suffix.
*
* Queue names are case-sensitive. *
* @return createQueueResult The response from the CreateQueue service * method, as returned by Amazon SQS. * @throws QueueDeletedRecentlyException * @throws QueueNameExistsException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ CreateQueueResult createQueue(String queueName) throws AmazonClientException, AmazonServiceException; /** ** Deletes the queue specified by the queue URL, regardless of * whether the queue is empty. If the specified queue doesn't exist, Amazon * SQS returns a successful response. *
*
* Use DeleteQueue with care; once you delete your queue, any
* messages in the queue are no longer available.
*
* When you delete a queue, the deletion process takes up to 60 seconds. * Requests you send involving that queue during the 60 seconds might * succeed. For example, a SendMessage request might succeed, but * after the 60 seconds, the queue and that message you sent no longer * exist. Also, when you delete a queue, you must wait at least 60 seconds * before creating a queue with the same name. *
** We reserve the right to delete queues that have had no activity for more * than 30 days. For more information, see How Amazon SQS Queues Work in the Amazon SQS Developer Guide. *
* * @param queueUrl* The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ void deleteQueue(String queueUrl) throws AmazonClientException, AmazonServiceException; /** ** Returns the URL of an existing queue. This action provides a simple way * to retrieve the URL of an Amazon SQS queue. *
*
* To access a queue that belongs to another AWS account, use the
* QueueOwnerAWSAccountId parameter to specify the account ID
* of the queue's owner. The queue's owner must grant you permission to
* access the queue. For more information about shared queue access, see
* AddPermission or see Shared Queues in the Amazon SQS Developer Guide.
*
* The name of the queue whose URL must be fetched. Maximum 80 * characters; alphanumeric characters, hyphens (-), and * underscores (_) are allowed. *
** Queue names are case-sensitive. *
* @return getQueueUrlResult The response from the GetQueueUrl service * method, as returned by Amazon SQS. * @throws QueueDoesNotExistException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ GetQueueUrlResult getQueueUrl(String queueName) throws AmazonClientException, AmazonServiceException; /** *
* Retrieves one or more messages, with a maximum limit of 10 messages, from
* the specified queue. Long poll support is enabled by using the
* WaitTimeSeconds parameter. For more information, see Amazon SQS Long Poll in the Amazon SQS Developer Guide.
*
* Short poll is the default behavior where a weighted random set of
* machines is sampled on a ReceiveMessage call. This 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.
*
* For each message returned, the response includes the following: *
** Message body *
** MD5 digest of the message body. For information about MD5, see RFC1321. *
** Message ID you received when you sent the message to the queue. *
** Receipt handle. *
** Message attributes. *
** MD5 digest of the message attributes. *
** The receipt handle is the identifier you must provide when deleting the * message. For more information, see Queue and Message Identifiers in the Amazon SQS Developer * Guide. *
*
* You can provide the VisibilityTimeout parameter in your
* request, which will be applied to the messages that Amazon SQS returns in
* the response. If you don't include the parameter, the overall visibility
* timeout for the queue is used for the returned messages. For more
* information, see Visibility Timeout in the Amazon SQS Developer Guide.
*
* A message that is not deleted or a message whose visibility is not * extended before the visibility timeout expires counts as a failed * receive. Depending on the configuration of the queue, the message might * be sent to the dead letter queue. *
** Going forward, new attributes might be added. If you are writing code * that calls this action, we recommend that you structure your code so that * it can handle new attributes gracefully. *
** The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @return receiveMessageResult The response from the ReceiveMessage service * method, as returned by Amazon SQS. * @throws OverLimitException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ ReceiveMessageResult receiveMessage(String queueUrl) throws AmazonClientException, AmazonServiceException; /** ** Delivers a message to the specified queue. *
** The following list shows the characters (in Unicode) that are allowed in * your message, according to the W3C XML specification: *
*
* #x9 | #xA | #xD | [
* #x20 to #xD7FF] | [#xE000 to
* #xFFFD] | [#x10000 to #x10FFFF]
*
* For more information, see RFC1321. If you send any * characters that aren't included in this list, your request will be * rejected. *
** The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @param messageBody* The message to send. String maximum 256 KB in size. For a list * of allowed characters, see the preceding note. *
* @return sendMessageResult The response from the SendMessage service * method, as returned by Amazon SQS. * @throws InvalidMessageContentsException * @throws UnsupportedOperationException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ SendMessageResult sendMessage(String queueUrl, String messageBody) throws AmazonClientException, AmazonServiceException; /** ** Deletes up to ten messages from the specified queue. This is a batch * version of DeleteMessage. The result of the delete action on each * message is reported individually in the response. *
** Because the batch request can result in a combination of successful and * unsuccessful actions, you should check for batch errors even when the * call returns an HTTP status code of 200. *
*
* Some API actions take lists of parameters. These lists are specified
* using the param.n notation. Values of n are
* integers starting from 1. For example, a parameter list with two elements
* looks like this:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @param entries* A list of receipt handles for the messages to be deleted. *
* @return deleteMessageBatchResult The response from the DeleteMessageBatch * service method, as returned by Amazon SQS. * @throws TooManyEntriesInBatchRequestException * @throws EmptyBatchRequestException * @throws BatchEntryIdsNotDistinctException * @throws InvalidBatchEntryIdException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ DeleteMessageBatchResult deleteMessageBatch(String queueUrl, java.util.List
* Returns a list of your queues. The maximum number of queues that can be
* returned is 1000. If you specify a value for the optional
* QueueNamePrefix parameter, only queues with a name beginning
* with the specified value are returned.
*
* Returns a list of your queues. The maximum number of queues that can be
* returned is 1000. If you specify a value for the optional
* QueueNamePrefix parameter, only queues with a name beginning
* with the specified value are returned.
*
* A string to use for filtering the list results. Only those * queues whose name begins with the specified string are * returned. *
** Queue names are case-sensitive. *
* @return listQueuesResult The response from the ListQueues service method, * as returned by Amazon SQS. * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ ListQueuesResult listQueues(String queueNamePrefix) throws AmazonClientException, AmazonServiceException; /** *
* 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 longer than the queue's configured retention period, Amazon
* SQS automatically deletes it.
*
* 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.
*
* 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. *
** The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @param receiptHandle* The receipt handle associated with the message to delete. *
* @throws InvalidIdFormatException * @throws ReceiptHandleIsInvalidException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ void deleteMessage(String queueUrl, String receiptHandle) throws AmazonClientException, AmazonServiceException; /** *
* Delivers up to ten messages to the specified queue. This is a batch
* version of SendMessage . For a FIFO queue, multiple
* messages within a single batch are enqueued in the order they are sent.
*
* The result of sending each message is reported individually in the * response. Because the batch request can result in a combination of * successful and unsuccessful actions, you should check for batch errors * even when the call returns an HTTP status code of 200. *
** The maximum allowed individual message size and the maximum total payload * size (the sum of the individual lengths of all of the batched messages) * are both 256 KB (262,144 bytes). *
** The following list shows the characters (in Unicode) that are allowed in * your message, according to the W3C XML specification: *
*
* #x9 | #xA | #xD | [
* #x20 to #xD7FF] | [#xE000 to
* #xFFFD] | [#x10000 to #x10FFFF]
*
* For more information, see RFC1321. If you send any * characters that aren't included in this list, your request will be * rejected. *
*
* If you don't specify the DelaySeconds parameter for an
* entry, Amazon SQS uses the default for the queue.
*
* Some API actions take lists of parameters. These lists are specified
* using the param.n notation. Values of n are
* integers starting from 1. For example, a parameter list with two elements
* looks like this:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @param entries* A list of SendMessageBatchRequestEntry items. *
* @return sendMessageBatchResult The response from the SendMessageBatch * service method, as returned by Amazon SQS. * @throws TooManyEntriesInBatchRequestException * @throws EmptyBatchRequestException * @throws BatchEntryIdsNotDistinctException * @throws BatchRequestTooLongException * @throws InvalidBatchEntryIdException * @throws UnsupportedOperationException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ SendMessageBatchResult sendMessageBatch(String queueUrl, java.util.List
* Revokes any permissions in the queue policy that matches the specified
* Label parameter. Only the owner of the queue can remove
* permissions.
*
* The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @param label* The identification of the permission to remove. This is the * label added with the AddPermission action. *
* @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ void removePermission(String queueUrl, String label) throws AmazonClientException, AmazonServiceException; /** ** Adds a permission to a queue for a specific principal. This allows for sharing access to the queue. *
** When you create a queue, you have full control access rights for the * queue. Only you (as owner of the queue) can grant or deny permissions to * the queue. For more information about these permissions, see Shared Queues in the Amazon SQS Developer Guide. *
*
* AddPermission writes an Amazon SQS-generated policy. If you
* want to write your own policy, use SetQueueAttributes to upload
* your policy. For more information about writing your own policy, see Using The Access Policy Language in the Amazon SQS Developer
* Guide.
*
* Some API actions take lists of parameters. These lists are specified
* using the param.n notation. Values of n are
* integers starting from 1. For example, a parameter list with two elements
* looks like this:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @param label
* The unique identification of the permission you're setting
* (e.g., AliceSendMessage). Constraints: Maximum 80
* characters; alphanumeric characters, hyphens (-), and
* underscores (_) are allowed.
*
* The AWS account number of the principal who will be given permission. The principal * must have an AWS account, but does not need to be signed up * for Amazon SQS. For information about locating the AWS account * identification, see Your AWS Identifiers in the Amazon SQS Developer * Guide. *
* @param actions
* The action the client wants to allow for the specified
* principal. The following are valid values:
* * | SendMessage | ReceiveMessage | DeleteMessage | ChangeMessageVisibility | GetQueueAttributes | GetQueueUrl
* . For more information about these actions, see Understanding Permissions in the Amazon SQS Developer
* Guide.
*
* Specifying SendMessage,
* DeleteMessage, or
* ChangeMessageVisibility for the
* ActionName.n also grants permissions for the
* corresponding batch versions of those actions:
* SendMessageBatch, DeleteMessageBatch
* , and ChangeMessageVisibilityBatch.
*
* 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 you have a message and its default message
* visibility timeout is 5 minutes. After 3 minutes, you call
* ChangeMessageVisiblity with a timeout of 10 minutes. At that
* time, the timeout for the message would be extended by 10 minutes beyond
* the time of the ChangeMessageVisibility call. This results in a total
* visibility timeout of 13 minutes. You can continue to call
* ChangeMessageVisibility to extend the visibility timeout to a maximum of
* 12 hours. If you try to extend beyond 12 hours, the request will be
* rejected.
*
* There is a 120,000 limit for the number of inflight messages per queue. * Messages are inflight after they have been received from the queue by a * consuming component, but have not yet been deleted from the queue. If you * reach the 120,000 limit, you will receive an OverLimit error message from * Amazon SQS. To help avoid reaching the limit, you should delete the * messages from the queue after they have been processed. You can also * increase the number of queues you use to process the messages. *
*
* 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.
*
* 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.
*
* The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @param receiptHandle* The receipt handle associated with the message whose * visibility timeout should be changed. This parameter is * returned by the ReceiveMessage action. *
* @param visibilityTimeout* The new value (in seconds - from 0 to 43200 - maximum 12 * hours) for the message's visibility timeout. *
* @throws MessageNotInflightException * @throws ReceiptHandleIsInvalidException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ void changeMessageVisibility(String queueUrl, String receiptHandle, Integer visibilityTimeout) throws AmazonClientException, AmazonServiceException; /** *
* Changes the visibility timeout of multiple messages. This is a batch
* version of ChangeMessageVisibility. The result of the action on
* each message is reported individually in the response. You can send up to
* 10 ChangeMessageVisibility requests with each
* ChangeMessageVisibilityBatch action.
*
* Because the batch request can result in a combination of successful and * unsuccessful actions, you should check for batch errors even when the * call returns an HTTP status code of 200. *
*
* Some API actions take lists of parameters. These lists are specified
* using the param.n notation. Values of n are
* integers starting from 1. For example, a parameter list with two elements
* looks like this:
*
* &Attribute.1=this
*
* &Attribute.2=that
*
* The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @param entries* A list of receipt handles of the messages for which the * visibility timeout must be changed. *
* @return changeMessageVisibilityBatchResult The response from the * ChangeMessageVisibilityBatch service method, as returned by * Amazon SQS. * @throws TooManyEntriesInBatchRequestException * @throws EmptyBatchRequestException * @throws BatchEntryIdsNotDistinctException * @throws InvalidBatchEntryIdException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by Amazon * SQS indicating either a problem with the data in the request, * or a server side issue. */ ChangeMessageVisibilityBatchResult changeMessageVisibilityBatch(String queueUrl, java.util.List
* Sets the value of one or more queue attributes. When you change a queue's
* attributes, the change can take up to 60 seconds for most of the
* attributes to propagate throughout the SQS system. Changes made to the
* MessageRetentionPeriod attribute can take up to 15 minutes.
*
* In the future, new attributes might be added. When you write code that * calls this action, we recommend structuring your code so that it can * handle new attributes gracefully. *
** The URL of the Amazon SQS queue to take action on. *
** Queue URLs are case-sensitive. *
* @param attributes* A map of attributes to set. *
*
* The following lists the names, descriptions, and values of the
* special request parameters that the
* SetQueueAttributes action uses:
*
* DelaySeconds - The number of seconds for which
* the delivery of all messages in the queue is delayed. An
* integer from 0 to 900 (15 minutes). The default is 0 (zero).
*
* MaximumMessageSize - The limit of how many bytes
* a message can contain before Amazon SQS rejects it. An integer
* from 1,024 bytes (1 KiB) up to 262,144 bytes (256 KiB). The
* default is 262,144 (256 KiB).
*
* MessageRetentionPeriod - The number of seconds
* for which Amazon SQS retains a message. An integer
* representing seconds, from 60 (1 minute) to 120,9600 (14
* days). The default is 345,600 (4 days).
*
* Policy - The queue's policy. A valid AWS policy.
* For more information about policy structure, see Overview of AWS IAM Policies in the Amazon IAM User
* Guide.
*
* ReceiveMessageWaitTimeSeconds - The number of
* seconds for which a ReceiveMessage action will wait for
* a message to arrive. An integer from 0 to 20 (seconds). The
* default is 0.
*
* RedrivePolicy - The parameters for the dead
* letter queue functionality of the source queue. For more
* information about the redrive policy and dead letter queues,
* see Using Amazon SQS Dead Letter Queues in the Amazon SQS
* Developer Guide.
*
* The dead letter queue of a FIFO queue must also be a FIFO * queue. Similarly, the dead letter queue of a standard queue * must also be a standard queue. *
*
* VisibilityTimeout - The visibility timeout for
* the queue. An integer from 0 to 43200 (12 hours). The default
* is 30. For more information about the visibility timeout, see
* Visibility Timeout in the Amazon SQS Developer
* Guide.
*
* The following attribute applies only to FIFO (first-in-first-out) queues: *
*
* ContentBasedDeduplication - Enables content-based
* deduplication. For more information, see Exactly-Once Processing in the Amazon SQS Developer
* Guide.
*
* Every message must have a unique
* MessageDeduplicationId,
*
* You may provide a MessageDeduplicationId
* explicitly.
*
* If you aren't able to provide a
* MessageDeduplicationId and you enable
* ContentBasedDeduplication for your queue, Amazon
* SQS uses a SHA-256 hash to generate the
* MessageDeduplicationId using the body of the
* message (but not the attributes of the message).
*
* If you don't provide a MessageDeduplicationId and
* the queue doesn't have ContentBasedDeduplication
* set, the action fails with an error.
*
* If the queue has ContentBasedDeduplication set,
* your MessageDeduplicationId overrides the
* generated one.
*
* When ContentBasedDeduplication is in effect,
* messages with identical content sent within the deduplication
* interval are treated as duplicates and only one copy of the
* message is delivered.
*
* You can also use ContentBasedDeduplication for
* messages with identical content to be treated as duplicates.
*
* If you send one message with
* ContentBasedDeduplication enabled and then
* another message with a MessageDeduplicationId
* that is the same as the one generated for the first
* MessageDeduplicationId, the two messages are
* treated as duplicates and only one copy of the message is
* delivered.
*
* Any other valid special request parameters that are specified
* (such as ApproximateNumberOfMessages,
* ApproximateNumberOfMessagesDelayed,
* ApproximateNumberOfMessagesNotVisible,
* CreatedTimestamp,
* LastModifiedTimestamp, and QueueArn)
* will be ignored.
*
* Response metadata is only cached for a limited period of time, so if you * need to access this extra diagnostic information for an executed request, * you should use this method to retrieve it as soon as possible after * executing a request. * * @param request The originally executed request. * @return The response metadata for the specified request, or null if none * is available. */ public ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request); }