com.xerox.amazonws.sqs2
Class MessageQueue

java.lang.Object
  extended by com.xerox.amazonws.common.AWSConnection
      extended by com.xerox.amazonws.common.AWSQueryConnection
          extended by com.xerox.amazonws.sqs2.MessageQueue

public class MessageQueue
extends AWSQueryConnection

This class provides an interface with the Amazon SQS message queue. It provides methods for sending / receiving messages and deleting queues and messsages on queues.

Author:
D. Kavanagh, developer@dotech.com

Field Summary
static int MAX_MESSAGES
           
protected  String queueId
           
 
Fields inherited from class com.xerox.amazonws.common.AWSConnection
headers
 
Constructor Summary
protected MessageQueue(String queueUrl, String awsAccessId, String awsSecretKey, boolean isSecure, int port, String server)
           
 
Method Summary
 void addPermission(String label, String accountId, String action)
          Adds a permission to this message queue.
static List<MessageQueue> createList(String[] queueUrls, String awsAccessId, String awsSecretKey, boolean isSecure, int port, String server, org.apache.http.client.HttpClient hc)
           
 void deleteMessage(Message msg)
          Deletes the message identified by message object on the queue this object represents.
 void deleteMessage(String receiptHandle)
          Deletes the message identified by receiptHandle on the queue this object represents.
 void deleteQueue()
          Deletes the message queue represented by this object.
 int getApproximateNumberOfMessages()
          Gets the visibility timeout for the queue.
 Map<String,String> getQueueAttributes(QueueAttribute qAttr)
          Gets queue attributes.
 URL getUrl()
          This method provides the URL for the message queue represented by this object.
 int getVisibilityTimeout()
          Gets the visibility timeout for the queue.
 boolean isEncoding()
          This method returns the state of the base64 encoding flag.
protected
<T> T
makeRequestInt(org.apache.http.client.methods.HttpRequestBase method, String action, Map<String,String> params, Class<T> respType)
           
protected  URL makeURL(String resource)
          Overriding this because the queue name is baked into the URL and QUERY assembles the URL within the baseclass.
 Message receiveMessage()
          Attempts to receive a message from the queue.
 Message receiveMessage(int visibilityTimeout)
          Attempts to receive a message from the queue.
protected  Message[] receiveMessages(BigInteger numMessages, BigInteger visibilityTimeout, List<String> attributes)
          Internal implementation of receiveMessages.
 Message[] receiveMessages(int numMessages)
          Attempts to retrieve a number of messages from the queue.
 Message[] receiveMessages(int numMessages, int visibilityTimeout)
          Attempts to retrieve a number of messages from the queue.
 Message[] receiveMessages(int numMessages, int visibilityTimeout, List<String> attributes)
          Attempts to retrieve a number of messages from the queue.
 void removePermission(String label)
          Removes a permission from this message queue.
 String sendMessage(String msg)
          Sends a message to a specified queue.
 void setEncoding(boolean enable)
          This method sets the state of the encoding flag.
 void setMessageVisibilityTimeout(Message msg, int timeout)
          Sets the message visibility timeout.
 void setMessageVisibilityTimeout(String receiptHandle, int timeout)
          Sets the message visibility timeout.
 void setQueueAttribute(String attribute, String value)
          Sets a queue attribute.
 void setVisibilityTimeout(int timeout)
          Sets the visibility timeout of the queue.
 
Methods inherited from class com.xerox.amazonws.common.AWSQueryConnection
close, close, getConnectionManagerTimeout, getConnectionTimeout, getHeaders, getHttpClient, getMaxConnections, getMaxRetries, getServerTimeZone, getSoTimeout, getString, httpDate, makeRequest, setConnectionManagerTimeout, setConnectionTimeout, setHttpClient, setMaxConnections, setMaxRetries, setProxyValues, setProxyValues, setProxyValues, setServerTimeZone, setSoTimeout, useSystemProxy
 
Methods inherited from class com.xerox.amazonws.common.AWSConnection
encode, encode, getAlgorithm, getAwsAccessKeyId, getPort, getResourcePrefix, getSecretAccessKey, getServer, getSignatureVersion, isSecure, setResourcePrefix, setServer, setSignatureVersion, urlencode
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_MESSAGES

public static final int MAX_MESSAGES
See Also:
Constant Field Values

queueId

protected String queueId
Constructor Detail

MessageQueue

protected MessageQueue(String queueUrl,
                       String awsAccessId,
                       String awsSecretKey,
                       boolean isSecure,
                       int port,
                       String server)
                throws SQSException
Throws:
SQSException
Method Detail

getUrl

public URL getUrl()
This method provides the URL for the message queue represented by this object.

Overrides:
getUrl in class AWSConnection
Returns:
generated queue service url

isEncoding

public boolean isEncoding()
This method returns the state of the base64 encoding flag. By default, all messages are encoded on send and decoded on receive.

Returns:
state of encoding flag

setEncoding

public void setEncoding(boolean enable)
This method sets the state of the encoding flag. Use this to override the default and turn off automatic base64 encoding.

Parameters:
enable - the new state of the encoding flag

sendMessage

public String sendMessage(String msg)
                   throws SQSException
Sends a message to a specified queue. The message must be between 1 and 256K bytes long.

Parameters:
msg - the message to be sent
Throws:
SQSException - wraps checked exceptions

receiveMessage

public Message receiveMessage()
                       throws SQSException
Attempts to receive a message from the queue. The queue default visibility timeout is used.

Returns:
the message object
Throws:
SQSException - wraps checked exceptions

receiveMessage

public Message receiveMessage(int visibilityTimeout)
                       throws SQSException
Attempts to receive a message from the queue.

Parameters:
visibilityTimeout - the duration (in seconds) the retrieved message is hidden from subsequent calls to retrieve.
Returns:
the message object
Throws:
SQSException - wraps checked exceptions

receiveMessages

public Message[] receiveMessages(int numMessages)
                          throws SQSException
Attempts to retrieve a number of messages from the queue. If less than that are availble, the max returned is the number of messages in the queue, but not necessarily all messages in the queue will be returned. The queue default visibility timeout is used.

Parameters:
numMessages - the maximum number of messages to return
Returns:
an array of message objects
Throws:
SQSException - wraps checked exceptions

receiveMessages

public Message[] receiveMessages(int numMessages,
                                 int visibilityTimeout)
                          throws SQSException
Attempts to retrieve a number of messages from the queue. If less than that are availble, the max returned is the number of messages in the queue, but not necessarily all messages in the queue will be returned.

Parameters:
numMessages - the maximum number of messages to return
visibilityTimeout - the duration (in seconds) the retrieved message is hidden from subsequent calls to retrieve.
Returns:
an array of message objects
Throws:
SQSException - wraps checked exceptions

receiveMessages

public Message[] receiveMessages(int numMessages,
                                 int visibilityTimeout,
                                 List<String> attributes)
                          throws SQSException
Attempts to retrieve a number of messages from the queue. If less than that are availble, the max returned is the number of messages in the queue, but not necessarily all messages in the queue will be returned.

Parameters:
numMessages - the maximum number of messages to return
visibilityTimeout - the duration (in seconds) the retrieved message is hidden from subsequent calls to retrieve.
attributes - the attributes you'd like to get (SenderId, SentTimestamp, All, ApproximateReceiveCount, ApproximateFirstReceiveTimestamp)
Returns:
an array of message objects
Throws:
SQSException - wraps checked exceptions

receiveMessages

protected Message[] receiveMessages(BigInteger numMessages,
                                    BigInteger visibilityTimeout,
                                    List<String> attributes)
                             throws SQSException
Internal implementation of receiveMessages.

Parameters:
numMessages - the maximum number of messages to return
visibilityTimeout - the duration (in seconds) the retrieved message is hidden from subsequent calls to retrieve.
attributes - the attributes you'd like to get (SenderId, SentTimestamp)
Returns:
an array of message objects
Throws:
SQSException - wraps checked exceptions

deleteMessage

public void deleteMessage(Message msg)
                   throws SQSException
Deletes the message identified by message object on the queue this object represents.

Parameters:
msg - the message to be deleted
Throws:
SQSException - wraps checked exceptions

deleteMessage

public void deleteMessage(String receiptHandle)
                   throws SQSException
Deletes the message identified by receiptHandle on the queue this object represents.

Parameters:
receiptHandle - the handle of the message to be deleted
Throws:
SQSException - wraps checked exceptions

deleteQueue

public void deleteQueue()
                 throws SQSException
Deletes the message queue represented by this object. Will delete non-empty queue.

Throws:
SQSException - wraps checked exceptions

setMessageVisibilityTimeout

public void setMessageVisibilityTimeout(Message msg,
                                        int timeout)
                                 throws SQSException
Sets the message visibility timeout.

Parameters:
msg - the message
timeout - the duration (in seconds) the retrieved message is hidden from subsequent calls to retrieve.
Throws:
SQSException - wraps checked exceptions

setMessageVisibilityTimeout

public void setMessageVisibilityTimeout(String receiptHandle,
                                        int timeout)
                                 throws SQSException
Sets the message visibility timeout.

Parameters:
receiptHandle - the handle of the message to be deleted
timeout - the duration (in seconds) the retrieved message is hidden from subsequent calls to retrieve.
Throws:
SQSException - wraps checked exceptions

getVisibilityTimeout

public int getVisibilityTimeout()
                         throws SQSException
Gets the visibility timeout for the queue. Uses getQueueAttributes(QueueAttribute).

Throws:
SQSException - wraps checked exceptions

getApproximateNumberOfMessages

public int getApproximateNumberOfMessages()
                                   throws SQSException
Gets the visibility timeout for the queue. Uses getQueueAttributes(QueueAttribute).

Throws:
SQSException - wraps checked exceptions

getQueueAttributes

public Map<String,String> getQueueAttributes(QueueAttribute qAttr)
                                      throws SQSException
Gets queue attributes. This is provided to expose the underlying functionality. Currently supported attributes are; ApproximateNumberOfMessages CreatedTimestamp LastModifiedTimestamp VisibilityTimeout RequestPayer Policy

Returns:
a map of attributes and their values
Throws:
SQSException - wraps checked exceptions

setVisibilityTimeout

public void setVisibilityTimeout(int timeout)
                          throws SQSException
Sets the visibility timeout of the queue. Uses setQueueAttribute(String, String).

Parameters:
timeout - the duration (in seconds) the retrieved message is hidden from subsequent calls to retrieve.
Throws:
SQSException - wraps checked exceptions

setQueueAttribute

public void setQueueAttribute(String attribute,
                              String value)
                       throws SQSException
Sets a queue attribute. This is provided to expose the underlying functionality, although the only attribute at this time is visibility timeout.

Parameters:
attribute - name of the attribute being set
value - the value being set for this attribute
Throws:
SQSException - wraps checked exceptions

addPermission

public void addPermission(String label,
                          String accountId,
                          String action)
                   throws SQSException
Adds a permission to this message queue.

Parameters:
label - a name for this permission
accountId - the AWS account ID for the account to share this queue with
action - a value to indicate how much to share (SendMessage, ReceiveMessage, ChangeMessageVisibility, DeleteMessage, GetQueueAttributes)
Throws:
SQSException - wraps checked exceptions

removePermission

public void removePermission(String label)
                      throws SQSException
Removes a permission from this message queue.

Parameters:
label - a name for the permission to be removed
Throws:
SQSException - wraps checked exceptions

makeURL

protected URL makeURL(String resource)
               throws MalformedURLException
Overriding this because the queue name is baked into the URL and QUERY assembles the URL within the baseclass.

Overrides:
makeURL in class AWSConnection
Parameters:
resource - The resource name (bucketName + "/" + key).
Throws:
SQSException - wraps checked exceptions
MalformedURLException

makeRequestInt

protected <T> T makeRequestInt(org.apache.http.client.methods.HttpRequestBase method,
                               String action,
                               Map<String,String> params,
                               Class<T> respType)
                    throws SQSException
Throws:
SQSException

createList

public static List<MessageQueue> createList(String[] queueUrls,
                                            String awsAccessId,
                                            String awsSecretKey,
                                            boolean isSecure,
                                            int port,
                                            String server,
                                            org.apache.http.client.HttpClient hc)
                                     throws SQSException
Throws:
SQSException