Amazon Simple Queue System (SQS) Integration

These are the functions available to OpenBD for interacting with the Simple Queue Service from Amazon Web Services.

Amazon SQS provides the following major features:

  • Redundant infrastructure - Guarantees delivery of your messages at least once, highly concurrent access to messages, and high availability for sending and retrieving messages
  • Multiple writers and readers - Multiple parts of your system can send or receive messages at the same time
  • SQS locks the message during processing, keeping other parts of your system from processing the message simultaneously.
  • Configurable settings per queue - All of your queues don't have to be exactly alike
  • Variable message size - Your messages can be up to 8 KB in size
  • For even larger messages, you can store the contents of the message using the Amazon Simple Storage Service (Amazon S3) or Amazon SimpleDB and use Amazon SQS to hold a pointer to the Amazon S3 or Amazon SDB object. Alternately, you can split the larger message into smaller ones.
  • Unlimited queues and messages - You can have as many queues and messages in the Amazon SQS system as you want
  • Access control - You can control who can send messages to a queue, and who can receive messages from a queue

http://aws.amazon.com/sqs/

Registering the datasource

To register an Amazon datasource you simply make a call to the function AmazonRegisterDataSource(). You only need to register an Amazon datasource once for the duration of the life time of the server.

<cfset amzDS = AmazonRegisterDataSource( "amz", "--amazonkey--", "--amazonsecretkey ----" )>

Creating and Deleting Queue

This function creates a new Amazon SQS queue. Every message is sent to a given queue waiting for processing. Messages will remain on the queue for a period of 4 days only.

<cfset AmazonRegisterDataSource( "testamz", "--amazonkey--", "--amazonsecretkey ----" )>

<!--- Create Queue --->
<cfset queueUrl = AmazonsqsCreateQueue("testamz", "testQueue" )>

<!--- Delete the Queue --->
<cfset AmazonsqsDeleteQueue( "testamz", queueUrl )>

This function will return the URL to the queue. This will be used as a parameter to many of the queue related functions. If a major error occurred it will throw a CFML exception that can be caught.

Sending and Receiving Messages

Send a message to the queue using the AmazonSqsSendMessage(). A message can be any ASCII text, but is limited to 8KB.

<cfset AmazonRegisterDataSource( "testamz", "--amazonkey--", "--amazonsecretkey ----" )>

<!--- Create Queue --->
<cfset queueUrl = AmazonsqsCreateQueue("testamz", "testQueue" )>

<!--- Send the message --->
<cfset myMessage= "This is a test message">
<cfset AmazonSqsSendMessage( "testamz", queueUrl, myMessage )>

<!--- Receive message --->
<cfset message = AmazonSqsReceiveMessage( "testamz", queueUrl )>
<cfif ArrayLen(message) neq 0>
  <cfset AmazonSqsDeleteMessage("testamz", queueUrl, message[1]["ReceiptHandle"] )>
</cfif>

When you receive a message, you have time to process it, but once you are finished you must delete it again. If you don't delete it within the visibility timeout period, then the message will be made available again to another requester.

Functions for SQS

There are functions that let you operate with all of the services provided by SQS.

Function Name Description
AmazonSqsAddPermission Adds the given permission to the queue within the account
AmazonSqsChangeMessageVisibility Changes the visibility of the given message by the value given
AmazonSqsCreateQueue Creates a new Amazon SQS queue, with the default visibility. Returns the Queue URL
AmazonSqsDeleteMessage Deletes the message on the queue
AmazonSqsDeleteQueue Deletes the queue
AmazonSqsGetAttributes Gets the attributes for the given queue url
AmazonSqsListQueues Returns all the queues for this account
AmazonSqsReceiveMessage Returns the messages available for processing sitting in teh queue
AmazonSqsRemovePermission Removes the given label permission from the queue
AmazonSqsSendMessage Adds the given message to the queue
AmazonSqsSetHost Changes the host endpoint for the Amazon SQS service. Defaults to queue.amazonaws.com. Possible: us-west-1.queue.amazonaws.com, eu-west-1.queue.amazonaws.com, ap-southeast-1.queue.amazonaws.com