Class AWS::SQS::Queue
In: lib/aws/sqs/queue.rb
Parent: Object

Represents an Amazon SQS Queue.

@example Sending a message

  msg = queue.send_message("HELLO")
  puts "Sent message: #{msg.id}"

@example Polling for messages indefinitely

  queue.poll do |msg|
    puts "Got message: #{msg.body}"
  end

Methods

Included Modules

Core::Model

Classes and Modules

Module AWS::SQS::Queue::PolicyProxy
Class AWS::SQS::Queue::SentMessage

Constants

DEFAULT_POLL_INTERVAL = 1   The default number of seconds to wait between polling requests for new messages.

Attributes

url  [R]  @return [String] The queue URL.

Public Class methods

Public Instance methods

@return [Boolean] Returns true if the other queue has the same

  url.

@return [Integer] The approximate number of visible messages

  in a queue.  For more information, see {Resources Required
  to Process
  Messages}[http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/IntroductionArticle.html#ApproximateNumber]
  in the Amazon SQS Developer Guide.

@return [Integer] Returns an approximate count of messages delayed.

@return [Integer] The approximate number of messages that

  are not timed-out and not deleted.  For more information,
  see {Resources Required to Process
  Messages}[http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/IntroductionArticle.html#ApproximateNumber]
  in the Amazon SQS Developer Guide.

@return [String] The queue‘s Amazon resource name (ARN).

@overload batch_change_message_visibility(visibility_timeout, *messages)

  Accepts a single +:visibility_timeout+ value and a list of
  messages ({ReceivedMessage} objects or receipt handle strings).
  This form of the method is useful when you want to set the same
  timeout value for each message.

    queue.bacth_change_message_visibility(10, messages)

  @param [Integer] visibility_timeout The new value for the message's
    visibility timeout (in seconds).

  @param [ReceivedMessage,String] message A list of up to 10 messages
    to change the visibility timeout for.

  @raise [BatchChangeVisibilityError] Raises this error when one
    or more of the messages failed the visibility update.

  @return [nil]

@overload batch_change_message_visibility(*messages_with_timeouts)

  Accepts a list of hashes.  Each hash should provide the visibility
  timeout and message (a {ReceivedMessage} object or the recipt handle
  string).

  Use this form when each message needs a different visiblity timeout.

    messages = []
    messages << { :message => 'handle1', :visibility_timeout => 5 }
    messages << { :message => 'handle2', :visibility_timeout => 10 }

    queue.bacth_change_message_visibility(*messages)

  @param [Hash] message A list hashes, each with a +:visibility_timeout+
    and a +:message+.

  @raise [BatchChangeVisibilityError] Raises this error when one
    or more of the messages failed the visibility update.

  @return [nil]

@param [ReceivedMessage,String] message A list of up to 10 messages

  to delete.  Each message should be a {ReceivedMessage} object
  or a received message handle (string).

@raise [Errors::BatchDeleteSend] Raised when one or more of the

  messages failed to delete.  The raised error has a list
  of the failures.

@return [nil]

Sends a batch of up to 10 messages in a single request.

  queue.send_messages('message-1', 'message-2')

You can also set an optional delay for all of the messages:

  # delay all messages 1 hour
  queue.batch_send(msg1, msg2, :delay_seconds => 3600)

If you need to set a custom delay for each message you can pass hashes:

  messages = []
  messages << { :message_body => 'msg1', :delay_seconds => 60 }
  messages << { :message_body => 'msg2', :delay_seconds => 30 }

  queue.batch_send(messages)

@param [String,Hash] messages A list of messages. Each message

  should be a string, or a hash with a +:message_body+,
  and optionally +:delay_seconds+.

@raise [Errors::BatchSendError] Raises this error when one or more

  of the messages failed to send, but others did.  On the raised
  object you can access a list of the messages that failed, and
  a list of messages that succeeded.

@return [Array<SentMessage>] Returns an array of sent message objects.

  Each object responds to #message_id and #md5_of_message_body.
  The message id is generated by Amazon SQS.

@return [Time] The time when the queue was created.

@return [Integer] Gets the current default delay for messages sent

  to the queue.

Sets the default delay for messages sent to the queue. @param [Integer] seconds How many seconds a message will be delayed.

Deletes the queue, regardless of whether it is empty.

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, calling {send_message} 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. @return [nil]

eql?(other)

Alias for #==

@return [Boolean] True if the queue exists.

@note This may raise an exception if you don‘t have

  permission to access the queue attributes.  Also, it may
  return true for up to 60 seconds after a queue has been
  deleted.

@private

invisible_messages()

@return [Time] The time when the queue was last changed.

@return [Integer] The limit of how many bytes a message can

  contain before Amazon SQS rejects it.

Sets the maximum message size for the queue.

@param [Integer] size The limit of how many bytes a message

  can contain before Amazon SQS rejects it.  This must be an
  integer from 1024 bytes (1KB) up to 65536 bytes
  (64KB). The default for this attribute is 8192 (8KB).

@return Retuns the passed size argument.

@return [Integer] The number of seconds Amazon SQS retains a

  message.

Sets the message retention period for the queue

@param [Integer] period The number of seconds Amazon SQS

  retains a message.  Must be an integer from 3600 (1 hour)
  to 1209600 (14 days). The default for this attribute is
  345600 (4 days).

@return Returns the passed period argument.

@return [Policy] Returns the current queue policy if there is one.

  Returns +nil+ otherwise.

Set the policy on this queue.

If you pass nil or an empty string then it will have the same effect as deleting the policy.

@param policy The policy to set. This policy can be a {Policy} object,

  a json policy string, or any other object that responds with a policy
  string when it received #to_json.

@return [nil]

Polls continually for messages. For example, you can use this to poll indefinitely:

 queue.poll { |msg| puts msg.body }

Or, to poll indefinitely for the first message and then continue polling until no message is received for a period of at least ten seconds:

 queue.poll(:initial_timeout => false,
            :idle_timeout => 10) { |msg| puts msg.body }

As with the block form of {receive_message}, this method automatically deletes the message then the block exits normally.

@yieldparam [ReceivedMessage] message Each message that was received.

@param [Hash] opts Options for polling.

@option opts [Float, Integer] :poll_interval The number of

  seconds to wait before retrying when no messages are
  received.  The default is 1 second.

@option opts [Integer] :idle_timeout The maximum number of

  seconds to spend polling while no messages are being
  returned.  By default this method polls indefinitely
  whether messages are received or not.

@option opts [Integer] :initial_timeout The maximum number

  of seconds to spend polling before the first message is
  received.  This option defaults to the value of
  +:idle_timeout+.  You can specify +false+ to poll
  indefinitely for the first message when +:idle_timeout+ is
  set.

@option opts [Integer] :batch_size The maximum number of

  messages to retrieve in a single request.  By default
  messages are received one at a time.  Valid values:
  integers from 1 to 10.

@option opts [Integer] :visibilitiy_timeout The duration (in

  seconds) that the received messages are hidden from
  subsequent retrieve requests.  Valid values: integer from
  0 to 43200 (maximum 12 hours)

@option opts [Array<Symbol, String>] :attributes The

  attributes to populate in each received message.  Valid values:

  * +:all+ (to populate all attributes)
  * +:sender_id+
  * +:sent_at+
  * +:receive_count+
  * +:first_received_at+

  See {ReceivedMessage} for documentation on each
  attribute's meaning.

@return [nil]

Retrieves one or more messages. When a block is given, each message is yielded to the block and then deleted as long as the block exits normally. When no block is given, you must delete the message yourself using {ReceivedMessage#delete}.

@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 call to
  {#receive_message}. If the number of messages in the queue
  is extremely small, you might not receive any messages.
  To poll continually for messages, use the {#poll} method,
  which automatically retries the request after a
  configurable delay.

@param [Hash] opts Options for receiving messages.

@option opts [Integer] :limit The maximum number of messages

  to receive.  By default this is 1, and the return value is
  a single message object.  If this options is specified and
  is not 1, the return value is an array of message objects;
  however, the array may contain fewer objects than you
  requested.  Valid values: integers from 1 to 10.

  Not necessarily all the messages in the queue are returned
  (for more information, see the preceding note about
  machine sampling).

@option opts [Integer] :visibilitiy_timeout The duration (in

  seconds) that the received messages are hidden from
  subsequent retrieve requests.  Valid values: integer from
  0 to 43200 (maximum 12 hours)

@option opts [Array<Symbol, String>] :attributes The

  attributes to populate in each received message.  Valid values:

  * +:all+ (to populate all attributes)
  * +:sender_id+
  * +:sent_at+
  * +:receive_count+
  * +:first_received_at+

  See {ReceivedMessage} for documentation on each
  attribute's meaning.

@yieldparam [ReceivedMessage] message Each message that was received.

@return [ReceivedMessage] Returns the received message (or messages)

  only if a block is not given to this method.
receive_messages(opts = {}, &block)

Alias for receive_message

Delivers a message to this queue.

@param [String] body The message to send. The maximum

  allowed message size is 64 KB.  The message may only
  contain Unicode characters from the following list,
  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

@param [Hash] options

@option options [Integer] :delay_seconds The number of seconds to

  delay the message. The message will become available for
  processing after the delay time has passed.
  If you don't specify a value, the default value for the
  queue applies.  Should be from 0 to 900 (15 mins).

@return [SentMessage] An object containing information about

  the message that was sent.

@return [Integer] Returns the visibility timeout for the

  queue. For more information about visibility timeout, see
  {Visibility
  Timeout}[http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/IntroductionArticle.html#AboutVT]
  in the Amazon SQS Developer Guide.

Sets the visibility timeout for the queue.

@param [Integer] timeout The length of time (in seconds)

  that a message received from a queue will be invisible to
  other receiving components when they ask to receive
  messages.  Valid values: integers from 0 to 43200 (12
  hours).

@return Returns the value passed as a timeout.

visible_messages()

Protected Instance methods

[Validate]