Class WAZ::Queues::Queue
In: lib/waz/queues/queue.rb
Parent: Object

This class represents a Queue on Windows Azure Queues API. These are the methods implemented from Microsoft‘s API description available on MSDN at msdn.microsoft.com/en-us/library/dd179363.aspx

  # list available queues
  WAZ::Queues::Queue.list

  # create a queue (here you can also send hashed metadata)
  WAZ::Queues::Queue.create('test-queue')

  # get a specific queue
  queue = WAZ::Queues::Queue.find('test-queue')

  # get queue properties (including default headers)
  queue.metadata #=> hash containing beautified metadata (:x_ms_meta_name)

  # set queue properties (should follow x-ms-meta to be persisted)
  # if you specify the optional parameter overwrite, existing metadata
  # will be deleted else merged with new one.
  queue.put_properties!(:x_ms_meta_MyProperty => "my value")

  # delete queue
  queue.destroy!

  # clear queue contents
  queue.clear

  # enqueue a message
  queue.enqueue!("payload of the message")

  # peek a message/s (do not alter visibility, it can't be deleted neither)
  # num_of_messages (1 to 32) to be peeked (default 1)
  message = queue.peek

  # lock a message/s.
  # num_of_messages (1 to 32) to be peeked (default 1)
  # visiblity_timeout (default 60 sec. max 7200 [2hrs])
  message = queue.lock

Methods

clear   create   destroy!   enqueue!   ensure   find   list   lock   metadata   new   peek   put_properties!   service_instance   size  

Attributes

metadata  [RW] 
name  [RW] 
url  [RW] 

Public Class methods

Creates a queue on the current account. If provided the metadata hash will specify additional metadata to be stored on the queue. (Remember that metadata on the storage account must start with :x_ms_metadata_{yourCustomPropertyName}, if not it will not be persisted).

[Source]

    # File lib/waz/queues/queue.rb, line 57
57:         def create(queue_name, metadata = {})
58:           raise WAZ::Storage::InvalidParameterValue, {:name => "name", :values => ["lower letters, numbers or - (hypen), and must not start or end with - (hyphen)"]} unless WAZ::Storage::ValidationRules.valid_name?(queue_name)
59:           service_instance.create_queue(queue_name, metadata)
60:           WAZ::Queues::Queue.new(:name => queue_name, :url => service_instance.generate_request_uri(queue_name))
61:         end

Syntax‘s sugar for find(:queue_name) or create(:queue_name)

[Source]

    # File lib/waz/queues/queue.rb, line 75
75:         def ensure(queue_name)
76:           return (self.find(queue_name) or self.create(queue_name))
77:         end

Finds a queue by it‘s name, in case that it isn‘t found on the current storage account it will return nil shilding the user from a ResourceNotFound exception.

[Source]

    # File lib/waz/queues/queue.rb, line 65
65:         def find(queue_name)
66:           begin 
67:             metadata = service_instance.get_queue_metadata(queue_name)
68:             WAZ::Queues::Queue.new(:name => queue_name, :url => service_instance.generate_request_uri(queue_name), :metadata => metadata)
69:           rescue RestClient::ResourceNotFound
70:             return nil
71:           end
72:         end

Returns an array of the queues (WAZ::Queues::Queue) existing on the current Windows Azure Storage account.

include_metadata defines if the metadata is retrieved along with queue data.

[Source]

    # File lib/waz/queues/queue.rb, line 47
47:         def list(include_metadata = false)
48:           options = include_metadata ? { :include => 'metadata' } : {}
49:           service_instance.list_queues(options).map do |queue|
50:             WAZ::Queues::Queue.new(queue)
51:           end
52:         end

[Source]

    # File lib/waz/queues/queue.rb, line 90
90:       def initialize(options = {})
91:         raise WAZ::Storage::InvalidOption, :name unless options.keys.include?(:name)
92:         raise WAZ::Storage::InvalidOption, :url unless options.keys.include?(:url)
93:         self.name = options[:name]
94:         self.url = options[:url]
95:         self.metadata = options[:metadata]
96:       end

This method is internally used by this class. It‘s the way we keep a single instance of the service that wraps the calls the Windows Azure Queues API. It‘s initialized with the values from the default_connection on WAZ::Storage::Base initialized thru establish_connection!

[Source]

    # File lib/waz/queues/queue.rb, line 82
82:         def service_instance
83:           options = WAZ::Storage::Base.default_connection.merge(:type_of_service => "queue")
84:           (@service_instances ||= {})[options[:account_name]] ||= Service.new(options)
85:         end

Public Instance methods

Marks every message on the queue for deletion (to be later garbage collected).

[Source]

     # File lib/waz/queues/queue.rb, line 160
160:       def clear
161:         self.class.service_instance.clear_queue(self.name)
162:       end

Deletes the queue from the current storage account.

[Source]

     # File lib/waz/queues/queue.rb, line 99
 99:       def destroy!
100:         self.class.service_instance.delete_queue(self.name)
101:       end

Enqueues a message on current queue. message is just a string that should be UTF-8 serializable and ttl specifies the time-to-live of the message in the queue (in seconds).

[Source]

     # File lib/waz/queues/queue.rb, line 118
118:       def enqueue!(message, ttl = 604800)
119:         self.class.service_instance.enqueue(self.name, message, ttl)
120:       end

Since Windows Azure Queues implement a Peek-Lock pattern the method lock will lock a message preventing other users from picking/locking the current message from the queue.

The API supports multiple message processing by specifiying num_of_messages (up to 32)

The visibility_timeout parameter (optional) specifies for how long the message will be hidden from other users.

[Source]

     # File lib/waz/queues/queue.rb, line 135
135:       def lock(num_of_messages = 1, visibility_timeout = nil)
136:         options = {}
137:         options[:num_of_messages] = num_of_messages
138:         options[:visiblity_timeout] = visibility_timeout unless visibility_timeout.nil?
139:         messages = self.class.service_instance.get_messages(self.name, options).map do |raw_message|
140:                     WAZ::Queues::Message.new(raw_message.merge(:queue_name => self.name))
141:                   end
142:         return messages.first() if num_of_messages == 1
143:         return messages
144:       end

Retrieves the metadata headers associated with the quere.

[Source]

     # File lib/waz/queues/queue.rb, line 104
104:       def metadata
105:         metadata ||= self.class.service_instance.get_queue_metadata(self.name)
106:       end

Returns top N (default 1, up to 32) message from the queue without performing any modification on the message. Since the message it‘s retrieved read-only users cannot delete the peeked message.

[Source]

     # File lib/waz/queues/queue.rb, line 149
149:       def peek(num_of_messages = 1)
150:         options = {}
151:         options[:num_of_messages] = num_of_messages
152:         messages = self.class.service_instance.peek(self.name, options).map do |raw_message|
153:                     WAZ::Queues::Message.new(raw_message.merge(:queue_name => self.name))
154:                   end
155:         return messages.first() if num_of_messages == 1
156:         return messages
157:       end

Sets the metadata given on the new_metadata, when overwrite passed different than true it overrides the metadata for the queue (removing all existing metadata)

[Source]

     # File lib/waz/queues/queue.rb, line 110
110:       def put_properties!(new_metadata = {}, overwrite = false)
111:         new_metadata.merge!(metadata.reject { |k, v| !k.to_s.start_with? "x_ms_meta"} ) unless overwrite
112:         self.class.service_instance.set_queue_metadata(new_metadata)
113:       end

Returns the approximated queue size.

[Source]

     # File lib/waz/queues/queue.rb, line 123
123:       def size
124:         metadata[:x_ms_approximate_messages_count].to_i
125:       end

[Validate]