Services_Amazon_SQS
[ class tree: Services_Amazon_SQS ] [ index: Services_Amazon_SQS ] [ all elements ]

Class: Services_Amazon_SQS_Queue

Source Location: /Services_Amazon_SQS-0.3.0/Services/Amazon/SQS/Queue.php

Class Overview

Services_Amazon_SQS
   |
   --Services_Amazon_SQS_Queue

A queue in the Amazon SQS


Author(s):

Copyright:

  • 2008 Mike Brittain, 2008 Amazon.com, 2008-2009 silverorange

Methods


Inherited Variables

Inherited Methods

Class: Services_Amazon_SQS

Services_Amazon_SQS::__construct()
Creates a new SQS client
Services_Amazon_SQS::addRequiredParameters()
Adds required authentication and version parameters to an array of parameters
Services_Amazon_SQS::getRequestBackoffTime()
Gets the number of milliseconds to wait before the next reqeust when performing exponential backoff
Services_Amazon_SQS::isValidPermissionLabel()
Gets whether or not a permission label is valid
Services_Amazon_SQS::isValidVisibilityTimeout()
Gets whether or not a visibility timeout is valid
Services_Amazon_SQS::sendRequest()
Sends a HTTP request to the queue service
Services_Amazon_SQS::setMaximumRetries()
Sets the maximum number of retries to make when encountering internal errors on SQS
Services_Amazon_SQS::setRequest()
Sets the HTTP request object to use
Services_Amazon_SQS::signParameters()
Signs an array of request parameters using the Amazon Web Services Signature Version 2 signing method

Class Details

[line 70]
A queue in the Amazon SQS

This class allows sending objects to and receiving objects from a queue on the Amazon SQS. Use the queue URL provided by Amazon through the list or creating methods when instantiating this class.



[ Top ]


Method Detail

__construct (Constructor)   [line 107]

Services_Amazon_SQS_Queue __construct( string $queueUrl, Services_Amazon_SQS_Account|string $accessKey, [string $secretAccessKey = ''], [ $request = null])

Creates a PHP SQS queue object

Queue objects are created with the full URL because Amazon reserves the right to change the URL scheme for queues created in the future. Always use the full queue URL.

  • Access: public

Overrides Services_Amazon_SQS::__construct() (Creates a new SQS client)

Parameters:

string   $queueUrl     the URL of this queue.
Services_Amazon_SQS_Account|string   $accessKey     either a Services_Amazon_SQS_Account object or a string containing the SQS access key for an account.
string   $secretAccessKey     if the second parameter is an account object, this parameter is ignored. Otherwise, this parameter is required and is the secret access key for the SQS account.
HTTP_Request2   $request     optional. The HTTP request object to use. If not specified, a HTTP request object is created automatically.

[ Top ]

addPermission   [line 663]

void addPermission( string $label, $principals)

Adds a permission to this queue for a specific principal

Permissions that may be granted on this queue are:

  • * (all permissions)
  • SendMessage
  • ReceiveMessage
  • DeleteMessage
  • ChangeMessageVisibility
  • GetQueueAttributes
Example use:
  1.  <?php
  2.  $queue->addPermission(
  3.      'billing-read-only',
  4.      array(
  5.          array(
  6.              'account'   => '123456789012',
  7.              'permission => 'ReceiveMessage'
  8.          ),
  9.          array(
  10.              'account'   => '123456789012',
  11.              'permission => 'GetQueueAttributes'
  12.          ),
  13.      )
  14.  );
  15.  ?>

  • See: Services_Amazon_SQS_Queue::removePermission()
  • Throws: InvalidArgumentException if no principals are specified, or if the specified principals do not contain the account and permission fields.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_InvalidPermissionLabelException if the specified permission label is not valid.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string   $label     a unique identifier for this permission. This label can be used to revoke the permission at a later date.
array   $principals     an array of principals receiving the permission. Each array element is a separate array containing the following keys:
  • account - the id of the AWS account which will receive the permission. This is <em>not</em> an AWS key id.
  • permission - the permission to grant.

[ Top ]

changeMessageVisibility   [line 402]

void changeMessageVisibility( string $handle, integer $timeout)

Changes the visibility timeout for a message in this queue

Once a message is received, it is invisible to the queue for the duration of the visibility timeout. After receiving the message, the visibility timeout may be increased if the queue operation will take longer than the default visibility timeout.

Message visibility may be changed multiple times, but a single received message can not have a total visibility timeout period exceeding 12 hours.

Example usage:

  1.  <?php
  2.  // receive a message with a 10 second visibility timeout
  3.  $message $queue->receive(110);
  4.  // check if processing the message will take longer than ten seconds
  5.  if ($message['body'== 'this will take a long time'{
  6.     // if so, add five minutes to the visibility timeout
  7.     $queue->changeMessageVisibility($message['handle']300);
  8.  }
  9.  // now process the message
  10.  ?>

  • Throws: Services_Amazon_SQS_InvalidTimeoutException if the provided $timeout is not in the valid range for the given message.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string   $handle     the receipt handle of the message to update.
integer   $timeout     the new visibility timeout for the message.

[ Top ]

delete   [line 334]

void delete( string $handle)

Deletes a message from this queue
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Access: public

Parameters:

string   $handle     the receipt handle of the message to delete.

[ Top ]

getAttributes   [line 487]

array getAttributes( [string|array $name = 'All'])

Gets an associative array of one or more attributes of this queue

Currently, Amazon SQS only allows retrieving the values of the following attributes:

  • ApproximateNumberOfMessages - an approximation of the number
  • CreatedTimestamp - the date this queue was created.
  • LastModifiedTimestamp - the date this queue was last modified.
  • VisibilityTimeout - the default time period for which messages are made invisible when retrieved from this queue.
Timestamp values are formatted as Unix timestamps.

Additionally, the special attribute All may be used to retrieve all available attributes.

  • Return: an associative array of available attributes. The attribute name is the array key and the attribute value is the array value.
  • Throws: Services_Amazon_SQS_InvalidAttributeException if an invalid attribute name is requested.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string|array   $name     optional. The name or names of the attribute values to get or All to get all available attributes. If not specified, <kbd>All</kdb> is used. Multiple specific attributes may be retrieved using an array of attribute names.

[ Top ]

receive   [line 260]

array receive( [integer $count = 1], [integer $timeout = null])

Retrieves one or more messages from this queue

Retrieved messages are made invisible to subsequent requests for the duration of the visibility timeout. To permanently remove a message from this queue, first retrieve the message and them delete it using the Services_Amazon_SQS_Queue::delete() method.

  • Return: an array containing one or more retrieved messages. Each message in the returned array is represented as an associative array with the following keys:
    • id - the message id.
    • body - the body of the message.
    • handle - the receipt handle of the message.
  • See: Services_Amazon_SQS_Queue::changeMessageVisibility()
  • Throws: Services_Amazon_SQS_InvalidTimeoutException if the provided $timeout is not in the valid range.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

integer   $count     optional. The number of messages to retrieve from the queue. If not specified, one message is retrieved. At most, ten messages may be retrieved.
integer   $timeout     optional. The number of seconds that retrieved messages should be hidden from view in the queue. If not specified, the default visibility timeout of this queue is used.

[ Top ]

removePermission   [line 776]

void removePermission( string $label)

Removes a permission from this queue by the permission's label

Example use:

  1.  <?php
  2.  $queue->removePermission('billing-read-only');
  3.  ?>

  • See: Services_Amazon_SQS_Queue::addPermission()
  • Throws: Services_Amazon_SQS_InvalidPermissionLabelException if the specified permission label is not valid.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string   $label     the unique identifier of the permission to remove. This should be the same label used when the permission was added.

[ Top ]

send   [line 155]

string send( string $message)

Sends a message to this queue
  • Return: the message id of the message.
  • Throws: Services_Amazon_SQS_InvalidMessageException if the message contains characters outside the allowed set or if the message size is greater than 8192 bytes.
  • Throws: Services_Amazon_SQS_ChecksumException if the received checksum from Amazon does not match the calculated checksum of the sent message.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string   $message     the message to put in this queue.

[ Top ]

setAttribute   [line 567]

void setAttribute( string $name, mixed $value)

Sets an attribute of this queue

Currently, Amazon SQS only allows setting the VisibilityTimeout attribute. This attribute sets the default time period for which messages are made invisible when retrieved from this queue.

  • Throws: Services_Amazon_SQS_InvalidAttributeException if an invalid attribute name is set.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string   $name     the attribute name.
mixed   $value     the attribute value.

[ Top ]

__toString   [line 124]

string __toString( )

Gets a string representation of this queue

Specifically, this returns the queue URL of this queue.

  • Return: the URL of this queue.
  • Access: public

[ Top ]


Documentation generated on Tue, 24 Nov 2009 17:00:04 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.