Class: AWS::SQS::Queue

Inherits:
Object
  • Object
show all
Defined in:
lib/aws/sqs/queue.rb

Overview

Represents an Amazon SQS Queue.

Examples:

Sending a message

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

Polling for messages indefinitely

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

Defined Under Namespace

Classes: SentMessage

Constant Summary collapse

DEFAULT_POLL_INTERVAL =

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

1

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#url ⇒ String (readonly)

Returns The queue URL.

Returns:

  • (String) —

    The queue URL.



42
43
44
 
# File 'lib/aws/sqs/queue.rb', line 42

def url
  @url
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Returns true if the other queue has the same url.

Returns:

  • (Boolean) —

    Returns true if the other queue has the same url.



422
423
424
 
# File 'lib/aws/sqs/queue.rb', line 422

def ==(other)
  other.kind_of?(Queue) and other.url == url
end

#approximate_number_of_messages ⇒ Integer Also known as: visible_messages

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.

Returns:



268
269
270
 
# File 'lib/aws/sqs/queue.rb', line 268

def approximate_number_of_messages
  get_attribute("ApproximateNumberOfMessages").to_i
end

#approximate_number_of_messages_not_visible ⇒ Integer Also known as: invisible_messages

Returns The approximate number of messages that are not timed-out and not deleted. For more information, see Resources Required to Process Messages in the Amazon SQS Developer Guide.

Returns:

  • (Integer) —

    The approximate number of messages that are not timed-out and not deleted. For more information, see Resources Required to Process Messages in the Amazon SQS Developer Guide.



278
279
280
 
# File 'lib/aws/sqs/queue.rb', line 278

def approximate_number_of_messages_not_visible
  get_attribute("ApproximateNumberOfMessagesNotVisible").to_i
end

#arn ⇒ String

Returns The queue’s Amazon resource name (ARN).

Returns:

  • (String) —

    The queue’s Amazon resource name (ARN).



352
353
354
 
# File 'lib/aws/sqs/queue.rb', line 352

def arn
  @arn ||= get_attribute("QueueArn")
end

#created_timestamp ⇒ Time

Returns The time when the queue was created.

Returns:

  • (Time) —

    The time when the queue was created.



307
308
309
 
# File 'lib/aws/sqs/queue.rb', line 307

def created_timestamp
  Time.at(get_attribute("CreatedTimestamp").to_i)
end

#delete ⇒ nil

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.

Returns:

  • (nil) 


61
62
63
64
 
# File 'lib/aws/sqs/queue.rb', line 61

def delete
  client.delete_queue(:queue_url => url)
  nil
end

#exists? ⇒ Boolean

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.

Returns True if the queue exists.

Returns:

  • (Boolean) —

    True if the queue exists.



362
363
364
365
366
367
368
369
 
# File 'lib/aws/sqs/queue.rb', line 362

def exists?
  client.get_queue_attributes(:queue_url => url,
                              :attribute_names => ["QueueArn"])
rescue Errors::NonExistentQueue, Errors::InvalidAddress
  false
else
  true
end

#last_modified_timestamp ⇒ Time

Returns The time when the queue was last changed.

Returns:

  • (Time) —

    The time when the queue was last changed.



312
313
314
 
# File 'lib/aws/sqs/queue.rb', line 312

def last_modified_timestamp
  Time.at(get_attribute("LastModifiedTimestamp").to_i)
end

#maximum_message_size ⇒ Integer

Returns The limit of how many bytes a message can contain before Amazon SQS rejects it.

Returns:

  • (Integer) —

    The limit of how many bytes a message can contain before Amazon SQS rejects it.



318
319
320
 
# File 'lib/aws/sqs/queue.rb', line 318

def maximum_message_size
  get_attribute("MaximumMessageSize").to_i
end

#maximum_message_size=(size) ⇒ Object

Sets the maximum message size for the queue.

Parameters:

  • size (Integer) —

    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).

Returns:

  • Retuns the passed size argument.



329
330
331
 
# File 'lib/aws/sqs/queue.rb', line 329

def maximum_message_size=(size)
  set_attribute("MaximumMessageSize", size.to_s)
end

#message_retention_period ⇒ Integer

Returns The number of seconds Amazon SQS retains a message.

Returns:

  • (Integer) —

    The number of seconds Amazon SQS retains a message.



335
336
337
 
# File 'lib/aws/sqs/queue.rb', line 335

def message_retention_period
  get_attribute("MessageRetentionPeriod").to_i
end

#message_retention_period=(period) ⇒ Object

Sets the message retention period for the queue

Parameters:

  • period (Integer) —

    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).

Returns:

  • Returns the passed period argument.



346
347
348
349
 
# File 'lib/aws/sqs/queue.rb', line 346

def message_retention_period=(period)
  set_attribute("MessageRetentionPeriod", period.to_s)
  period
end

#policy ⇒ Policy

Returns the current queue policy if there is one. Returns nil otherwise.

Returns:

  • (Policy) —

    Returns the current queue policy if there is one. Returns nil otherwise.



389
390
391
392
393
394
395
396
397
398
 
# File 'lib/aws/sqs/queue.rb', line 389

def policy
  if policy_json = get_attribute('Policy')
    policy = SQS::Policy.from_json(policy_json)
    policy.extend(PolicyProxy)
    policy.queue = self
    policy
  else
    nil
  end
end

#policy=(policy) ⇒ nil

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.

Parameters:

  • 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.

Returns:

  • (nil) 


410
411
412
413
414
415
416
417
418
 
# File 'lib/aws/sqs/queue.rb', line 410

def policy= policy
  policy_string = case policy
  when nil, '' then ''
  when String  then policy
  else policy.to_json
  end
  set_attribute('Policy', policy_string)
  nil
end

#poll(opts = {}) {|message| ... } ⇒ 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.

Parameters:

  • opts (Hash) (defaults to: {}) —

    Options for polling.

Options Hash (opts):

  • :poll_interval (Float, Integer) —

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

  • :idle_timeout (Integer) —

    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.

  • :initial_timeout (Integer) —

    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.

  • :batch_size (Integer) —

    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.

  • :visibilitiy_timeout (Integer) —

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

  • :attributes (Array<Symbol, String>) —

    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.

Yield Parameters:

Returns:

  • (nil) 


241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/aws/sqs/queue.rb', line 241

def poll(opts = {}, &block)
  poll_interval = opts[:poll_interval] || DEFAULT_POLL_INTERVAL
  opts[:limit] = opts.delete(:batch_size) if
    opts.key?(:batch_size)

  last_message_at = Time.now
  got_first = false
  loop do
    got_msg = false
    receive_messages(opts) do |message|
      got_msg = got_first = true
      last_message_at = Time.now
      yield(message)
    end
    unless got_msg
      Kernel.sleep(poll_interval) unless poll_interval == 0
      return if hit_timeout?(got_first, last_message_at, opts)
    end
  end
  nil
end

#receive_message(opts = {}) {|message| ... } ⇒ ReceivedMessage Also known as: receive_messages

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.

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.

Parameters:

  • opts (Hash) (defaults to: {}) —

    Options for receiving messages.

Options Hash (opts):

  • :limit (Integer) —

    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).

  • :visibilitiy_timeout (Integer) —

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

  • :attributes (Array<Symbol, String>) —

    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.

Yield Parameters:

Returns:

  • (ReceivedMessage) —

    Returns the received message (or messages) only if a block is not given to this method.



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/aws/sqs/queue.rb', line 162

def receive_message(opts = {}, &block)
  resp = client.receive_message(receive_opts(opts))

  messages = resp.messages.map do |m|
    ReceivedMessage.new(self, m.message_id, m.receipt_handle,
                        :body => m.body,
                        :md5 => m.md5_of_body,
                        :attributes => m.attributes)
  end

  if block
    call_message_block(messages, block)
  elsif opts[:limit] && opts[:limit] != 1
    messages
  else
    messages.first
  end
end

#send_message(body) ⇒ SentMessage

Delivers a message to this queue.

Parameters:

  • body (String) —

    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 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

Returns:

  • (SentMessage) —

    An object containing information about the message that was sent.



101
102
103
104
105
106
107
108
 
# File 'lib/aws/sqs/queue.rb', line 101

def send_message(body)
  resp = client.send_message(:queue_url => url,
                             :message_body => body)
  msg = SentMessage.new
  msg.message_id = resp.message_id
  msg.md5 = resp.md5_of_message_body
  msg
end

#visibility_timeout ⇒ Integer

Returns the visibility timeout for the queue. For more information about visibility timeout, see Visibility Timeout in the Amazon SQS Developer Guide.

Returns:

  • (Integer) —

    Returns the visibility timeout for the queue. For more information about visibility timeout, see Visibility Timeout in the Amazon SQS Developer Guide.



288
289
290
 
# File 'lib/aws/sqs/queue.rb', line 288

def visibility_timeout
  get_attribute("VisibilityTimeout").to_i
end

#visibility_timeout=(timeout) ⇒ Object

Sets the visibility timeout for the queue.

Parameters:

  • timeout (Integer) —

    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).

Returns:

  • Returns the value passed as a timeout.



301
302
303
304
 
# File 'lib/aws/sqs/queue.rb', line 301

def visibility_timeout=(timeout)
  set_attribute("VisibilityTimeout", timeout.to_s)
  timeout
end