sparqcode-waz-storage 1.1.1

data/lib/waz/storage/exceptions.rb

@@ -0,0 +1,33 @@
+module WAZ
+  module Storage
+    # This class is the base exception from where all the exceptions raised from this API 
+    # inherit from. If you want to handle an exception that your code may throw and you don't
+    # know which specific type you should handle, handle this type of exception.
+    class StorageException < StandardError
+    end
+    
+    # This exception raises whenever a required parameter for initializing any class isn't provided. From
+    # WAZ::Storage::Base up to WAZ::Queues::Queue all of them use this exception.
+    class InvalidOption < StorageException
+      def initialize(missing_option)
+        super("You did not provide one of the required parameters. Please provide the #{missing_option}.")
+      end
+    end
+    
+    # This exception is raised when the user tries to perform an operation on any Storage API class
+    # without previously specificying the connection options.
+    class NotConnected < StorageException
+      def initialize
+        super("You should establish connection before using the services, the connection configuration is required.")
+      end
+    end
+    
+    # This exception if raised when the value given for an argument doesn't fall into the permitted values. For example
+    # if values on the blocklisttype aren't [all|uncommitted|committed]
+    class InvalidParameterValue < StorageException
+      def initialize(args = {})
+        super("The value supplied for the parameter #{args[:name]} is invalid. Permitted values are #{args[:values].join(',')}")
+      end
+    end
+  end
+end

data/lib/waz/storage/validation_rules.rb

@@ -0,0 +1,26 @@
+module WAZ
+  module Storage
+    class ValidationRules
+      class << self
+        # Validates that the Container/Queue name given matches with the requirements of Windows Azure. 
+        #
+        # -Container/Queue names must start with a letter or number, and can contain only letters, numbers, and the dash (-) character.
+        # -Every dash (-) character must be immediately preceded and followed by a letter or number.
+        # -All letters in a container name must be lowercase.
+        # -Container/Queue names must be from 3 through 63 characters long.
+        def valid_name?(name)
+          name =~ /^[a-z0-9][a-z0-9\-]{1,}[^-]$/ && name.length < 64
+        end
+
+        # Validates that the Table name given matches with the requirements of Windows Azure. 
+        #
+        # -Table names must start with at least one lower / upper character.
+        # -Table names can have character or any digit starting from the second position.
+        # -Table names must be from 3 through 63 characters long.
+        def valid_table_name?(name)
+          name =~ /^([a-z]|[A-Z]){1}([a-z]|[A-Z]|\d){2,62}$/
+        end
+      end
+    end
+  end
+end

data/lib/waz/storage/version.rb

@@ -0,0 +1,11 @@
+module WAZ
+  module Storage
+    module VERSION #:nodoc:
+      MAJOR    = '1'
+      MINOR    = '1'
+      TINY     = '1' 
+    end
+    
+    Version = [VERSION::MAJOR, VERSION::MINOR, VERSION::TINY].compact * '.'
+  end
+end

data/lib/waz/tables/edm_type_helper.rb

@@ -0,0 +1,45 @@
+module WAZ
+  module Tables
+    class EdmTypeHelper
+      class << self
+        def parse_from(item)
+          return nil if !item.attributes['m:null'].nil? and item.attributes['m:null'] == 'true'
+          case item.attributes['m:type']
+            when 'Edm.Int16', 'Edm.Int32', 'Edm.Int64'
+              item.text.to_i
+            when 'Edm.Single', 'Edm.Double'
+              item.text.to_f
+            when 'Edm.Boolean'
+              item.text == 'true'
+            when 'Edm.DateTime'
+              Time.parse(item.text)
+            when 'Edm.Binary'
+              StringIO.new(Base64.decode64(item.text))
+            else
+              item.text
+          end
+        end
+      
+        def parse_to(item)
+          case item.class.name
+            when 'String'
+              [item, 'Edm.String']
+            when 'Fixnum'
+              [item, 'Edm.Int32']
+            when 'Float'
+              [item, 'Edm.Double']
+            when 'TrueClass', 'FalseClass'          
+              [item, 'Edm.Boolean']
+            when 'Time'
+              [item.iso8601, 'Edm.DateTime']
+            when 'File', 'StringIO'
+              item.pos = 0
+              [Base64.encode64(item.read), 'Edm.Binary']
+            else
+              [item, 'Edm.String']
+          end
+        end
+      end
+    end
+  end
+end

data/lib/waz/tables/exceptions.rb

@@ -0,0 +1,45 @@
+module WAZ
+  module Tables
+    # This exception is raised while trying to create table that already exists.
+    class TableAlreadyExists < WAZ::Storage::StorageException
+      def initialize(name)
+        super("The table #{name} already exists on your account.")
+      end
+    end
+
+    # This exception is raised while trying to delete an unexisting table.    
+    class TableDoesNotExist < WAZ::Storage::StorageException
+      def initialize(name)
+        super("The specified table #{name} does not exist.")
+      end
+    end
+    
+    # This exception is raised when an invalid table name is provided.
+    class InvalidTableName < WAZ::Storage::StorageException
+      def initialize(name)
+        super("The table name #{name} is invalid, it must start with at least one lower/upper characted, must be from 3 through 63 characters long and can have character or any digit starting from the second position")
+      end
+    end
+    
+    # This exception is raised when provided more than the 252 properties allowed by the Rest API.
+    class TooManyProperties < WAZ::Storage::StorageException
+      def initialize(total)
+        super("The entity contains more properties than allowed (252). The entity has #{total} properties.")
+      end
+    end
+
+    # This exception is raised when the specified entity already exists.
+    class EntityAlreadyExists < WAZ::Storage::StorageException
+      def initialize(row_key)
+        super("The specified entity already exists. RowKey: #{row_key}")
+      end
+    end
+    
+    # This exception is raised while trying to delete an unexisting entity.    
+    class EntityDoesNotExist < WAZ::Storage::StorageException
+      def initialize(key)
+        super("The specified entity with #{key} does not exist.")
+      end
+    end
+  end
+end

data/lib/waz/tables/service.rb

@@ -0,0 +1,178 @@
+module WAZ
+  module Tables
+    # This is internally used by the waz-tables part of the gem and it exposes the Windows Azure Blob API REST methods 
+    # implementation. You can use this class to perform an specific operation that isn't provided by the current API.
+    class Service
+      include WAZ::Storage::SharedKeyCoreService
+      
+      DATASERVICES_NAMESPACE = "http://schemas.microsoft.com/ado/2007/08/dataservices"      
+      DATASERVICES_METADATA_NAMESPACE = "http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
+      
+      # Creates a table on the current Windows Azure Storage account.
+      def create_table(table_name)
+        raise WAZ::Tables::InvalidTableName, table_name unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)
+
+        payload = "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" \
+                  "<entry xmlns:d=\"#{DATASERVICES_NAMESPACE}\" xmlns:m=\"#{DATASERVICES_METADATA_NAMESPACE}\" xmlns=\"http://www.w3.org/2005/Atom\">" \
+                  "<title /><updated>#{Time.now.utc.iso8601}</updated><author><name/></author><id/>" \
+                  "<content type=\"application/xml\"><m:properties><d:TableName>#{table_name}</d:TableName></m:properties></content></entry>"
+
+        begin
+          execute :post, 'Tables', {}, default_headers, payload
+          return {:name => table_name, :url => "#{self.base_url}/Tables('#{table_name}"}
+        rescue RestClient::RequestFailed
+          raise WAZ::Tables::TableAlreadyExists, table_name if $!.http_code == 409
+        end
+      end
+      
+      # Delete a table on the current Windows Azure Storage account.
+      def delete_table(table_name)
+        raise WAZ::Tables::InvalidTableName, table_name unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)
+        begin
+          execute :delete, "Tables('#{table_name}')", {}, default_headers
+        rescue RestClient::ResourceNotFound
+          raise WAZ::Tables::TableDoesNotExist, table_name if $!.http_code == 404
+        end
+      end
+      
+      # Lists all existing tables on the current storage account.
+      # remove Content-Type if it's not working
+      def list_tables(next_table_name = nil)
+        query = { 'NextTableName' => next_table_name } unless next_table_name.nil?
+        content = execute :get, "Tables", query ||= {}, default_headers
+
+        doc = REXML::Document.new(content)
+        tables = REXML::XPath.each(doc, '/feed/entry').map do |item|
+            { :name => REXML::XPath.first(item.elements['content'], "m:properties/d:TableName", {"m" => DATASERVICES_METADATA_NAMESPACE, "d" => DATASERVICES_NAMESPACE}).text,
+              :url => REXML::XPath.first(item, "id").text }
+        end
+        
+        return tables, content.headers[:x_ms_continuation_nexttablename]
+      end
+      
+      # Retrieves an existing table on the current storage account.
+      # remove Content-Type if it's not working
+      def get_table(table_name)
+        raise WAZ::Tables::InvalidTableName, table_name unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)        
+        
+        begin
+          content = execute :get, "Tables('#{table_name}')", {}, default_headers
+          doc = REXML::Document.new(content)
+          item = REXML::XPath.first(doc, "entry")
+          return {  :name => REXML::XPath.first(item.elements['content'], "m:properties/d:TableName", {"m" => DATASERVICES_METADATA_NAMESPACE, "d" => DATASERVICES_NAMESPACE}).text,
+                    :url => REXML::XPath.first(item, "id").text }
+        rescue RestClient::ResourceNotFound
+          raise WAZ::Tables::TableDoesNotExist, table_name if $!.http_code == 404
+        end        
+      end
+             
+      # Insert a new entity on the provided table for the current storage account
+      # TODO: catch all api errors as described on Table Service Error Codes on MSDN (http://msdn.microsoft.com/en-us/library/dd179438.aspx)
+      def insert_entity(table_name, entity)
+        raise WAZ::Tables::InvalidTableName, table_name unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)
+        raise WAZ::Tables::TooManyProperties, entity.length if entity.length > 252 
+        
+        begin
+          response = execute(:post, table_name, {}, default_headers, generate_payload(table_name, entity))
+          return parse_response(response)          
+        rescue RestClient::RequestFailed          
+          raise WAZ::Tables::EntityAlreadyExists, entity[:row_key] if $!.http_code == 409 and $!.response.body.include?('EntityAlreadyExists')          
+        end     
+      end
+      
+      # Update an existing entity on the current storage account.
+      # TODO: handle specific errors
+      def update_entity(table_name, entity)
+        raise WAZ::Tables::InvalidTableName, table_name unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)
+        response = execute(:put, "#{table_name}(PartitionKey='#{entity[:partition_key]}',RowKey='#{entity[:row_key]}')", {}, default_headers.merge({'If-Match' => '*'}) , generate_payload(table_name, entity))
+        return parse_response(response)
+      end
+      
+      # Merge an existing entity on the current storage account.
+      # The Merge Entity operation updates an existing entity by updating the entity's properties. 
+      # This operation does not replace the existing entity, as the Update Entity operation does
+      # TODO: handle specific errors
+      def merge_entity(table_name, entity)
+        raise WAZ::Tables::InvalidTableName, table_name unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)
+        response = execute(:merge, "#{table_name}(PartitionKey='#{entity[:partition_key]}',RowKey='#{entity[:row_key]}')", {}, default_headers.merge({'If-Match' => '*'}), generate_payload(table_name, entity))
+        return parse_response(response)
+      end
+      
+      # Delete an existing entity in a table.
+      def delete_entity(table_name, partition_key, row_key)
+        raise WAZ::Tables::InvalidTableName, table_name unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)
+        
+        begin
+          execute :delete, "#{table_name}(PartitionKey='#{partition_key}',RowKey='#{row_key}')", {}, default_headers.merge({'If-Match' => '*'})
+        rescue RestClient::ResourceNotFound
+          raise WAZ::Tables::TableDoesNotExist, table_name if $!.http_code == 404 and $!.response.body.include?('TableNotFound')
+          raise WAZ::Tables::EntityDoesNotExist, "(PartitionKey='#{partition_key}',RowKey='#{row_key}')" if $!.http_code == 404
+        end
+      end
+      
+      # Retrieves an existing entity on the current storage account.
+      # TODO: handle specific errors
+      def get_entity(table_name, partition_key, row_key)
+        raise WAZ::Tables::InvalidTableName, table_name unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)
+        response = execute(:get, "#{table_name}(PartitionKey='#{partition_key}',RowKey='#{row_key}')", {}, default_headers)
+        return parse_response(response)
+      end    
+      
+      # Retrieves a set of entities on the current storage account for a given query.
+      # When the :top => n is passed it returns only the first n rows that match with the query
+      # Optional parameters:
+      # * :headers a hash containing the request headers
+      # * :expression the filter query that will be executed against the table (see http://msdn.microsoft.com/en-us/library/dd179421.aspx for more information), 
+      # * :top limits the amount of fields for this query. 
+      # * :continuation_token the hash obtained when you perform a query that has more than 1000 records or exceeds the allowed timeout (see http://msdn.microsoft.com/en-us/library/dd135718.aspx)
+      def query(table_name, options = {})
+        raise WAZ::Tables::InvalidTableName, table_name unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)
+        query = {'$filter' => (options[:expression] or '') }
+        query.merge!({ '$top' => options[:top] }) unless options[:top].nil?
+        query.merge!(options[:continuation_token]) unless options[:continuation_token].nil?
+        response = execute :get, "#{table_name}()", query, default_headers
+        continuation_token = {'NextPartitionKey' => response.headers[:x_ms_continuation_nextpartitionkey], 'NextRowKey' => response.headers[:x_ms_continuation_nextrowkey]}
+        parse_response(response, continuation_token)
+      end
+
+      private 
+        def generate_payload(table_name, entity)
+          payload = "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" \
+                     "<entry xmlns:d=\"#{DATASERVICES_NAMESPACE}\" xmlns:m=\"#{DATASERVICES_METADATA_NAMESPACE}\" xmlns=\"http://www.w3.org/2005/Atom\">" \
+                     "<id>#{generate_request_uri "#{table_name}"}(PartitionKey='#{REXML::Text.new(entity[:partition_key], false, nil, false).to_s}',RowKey='#{REXML::Text.new(entity[:row_key], false, nil, false).to_s}')</id>" \
+                     "<title /><updated>#{Time.now.utc.iso8601}</updated><author><name /></author><link rel=\"edit\" title=\"#{table_name}\" href=\"#{table_name}(PartitionKey='#{REXML::Text.new(entity[:partition_key], false, nil, false).to_s}',RowKey='#{REXML::Text.new(entity[:row_key], false, nil, false).to_s}')\" />" \
+                     "<content type=\"application/xml\"><m:properties>"
+
+          entity.sort_by { |k| k.to_s }.each do |k,v| 
+            value, type = EdmTypeHelper.parse_to(v)[0].to_s, EdmTypeHelper.parse_to(v)[1].to_s
+            payload << (!v.nil? ? "<d:#{k.to_s} m:type=\"#{k.edm_type || type}\">#{REXML::Text.new(value, false, nil, false).to_s}</d:#{k.to_s}>" : "<d:#{k.to_s} m:type=\"#{k.edm_type || type}\" m:null=\"true\" />") unless k.eql?(:partition_key) or k.eql?(:row_key) 
+          end  
+
+          payload << "<d:PartitionKey>#{REXML::Text.new(entity[:partition_key], false, nil, false).to_s}</d:PartitionKey>" \
+                     "<d:RowKey>#{REXML::Text.new(entity[:row_key], false, nil, false).to_s}</d:RowKey>" \
+                     "</m:properties></content></entry>"
+          return payload
+        end
+        
+        def parse_response(response, continuation_token = nil)
+          doc = REXML::Document.new(response)
+          entities = REXML::XPath.each(doc, '//entry').map do |entry|
+            fields = REXML::XPath.each(entry.elements['content'], 'm:properties/*', {"m" => DATASERVICES_METADATA_NAMESPACE}).map do |f|
+              { f.name.gsub(/PartitionKey/i, 'partition_key').gsub(/RowKey/i, 'row_key').to_sym => EdmTypeHelper.parse_from(f) }
+            end
+            Hash[*fields.collect {|h| h.to_a}.flatten]
+          end
+          entities = WAZ::Tables::TableArray.new(entities)          
+          entities.continuation_token = continuation_token
+          return (REXML::XPath.first(doc, '/feed')) ? entities : entities.first
+        end
+        
+        def default_headers
+          { 'Date' => Time.new.httpdate, 
+            'Content-Type' => 'application/atom+xml', 
+            'DataServiceVersion' => '1.0;NetFx', 
+            'MaxDataServiceVersion' => '1.0;NetFx' }
+        end
+    end
+  end
+end

data/lib/waz/tables/table.rb

@@ -0,0 +1,75 @@
+module WAZ
+  module Tables
+    # This class represents a Table on Windows Azure Tables API. These are the methods implemented from Microsoft's API description 
+    # available on MSDN at http://msdn.microsoft.com/en-us/library/dd179423.aspx
+    #
+    #	# list available tables
+    #	tables = WAZ::Tables::Table.list
+    #
+    #	# list more tables
+    #	WAZ::Tables::Table.list(tables.continuation_token)
+    #
+  	# # get a specific table
+  	# my_table = WAZ::Tables::Table.find('my-table')
+  	#    
+    #	# delete table
+    #	my_table.destroy!
+    #
+    #	# create a new table
+    #	WAZ::Tables::Table.create('new-table')
+    #
+    class Table
+      class << self
+        INVALID_TABLE_ERROR_MESSAGE = "must start with at least one lower/upper characted, can have character or any digit starting from the second position, must be from 3 through 63 characters long"
+        
+        # Finds a table by name. It will return nil if no table was found.
+        def find(table_name)
+          raise WAZ::Storage::InvalidParameterValue, {:name => table_name, :values => [INVALID_TABLE_ERROR_MESSAGE]} unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)
+          begin 
+            WAZ::Tables::Table.new(service_instance.get_table(table_name))
+          rescue WAZ::Tables::TableDoesNotExist
+            return nil
+          end
+        end
+                
+        # Returns an array of the existing tables (WAZ::Tables::Table) on the current 
+        # Windows Azure Storage account.
+        def list(continuation_token = {})
+            table_list, next_table_name = service_instance.list_tables(continuation_token['NextTableName'])
+            tables = TableArray.new(table_list.map { |table| WAZ::Tables::Table.new({ :name => table[:name], :url => table[:url] }) })
+            tables.continuation_token = {'NextTableName' => next_table_name} unless next_table_name.nil?
+            return tables
+        end
+        
+        # Creates a table on the current account.
+        def create(table_name)
+          raise WAZ::Storage::InvalidParameterValue, {:name => table_name, :values => [INVALID_TABLE_ERROR_MESSAGE]} unless WAZ::Storage::ValidationRules.valid_table_name?(table_name)
+          WAZ::Tables::Table.new(service_instance.create_table(table_name))
+        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 Tables API. It's initialized with the values
+        # from the default_connection on WAZ::Storage::Base initialized thru establish_connection!
+        def service_instance
+          options = WAZ::Storage::Base.default_connection.merge(:type_of_service => "table")
+          (@service_instances ||= {})[options[:account_name]] ||= Service.new(options)
+        end       
+      end
+
+      attr_accessor :name, :url
+
+      def initialize(options = {})
+        raise WAZ::Storage::InvalidOption, :name unless options.keys.include?(:name) and !options[:name].empty?
+        raise WAZ::Storage::InvalidOption, :url unless options.keys.include?(:url) and !options[:url].empty?        
+        raise WAZ::Storage::InvalidParameterValue, {:name => options[:name], :values => [INVALID_TABLE_ERROR_MESSAGE]} unless WAZ::Storage::ValidationRules.valid_table_name?(options[:name])        
+        self.name = options[:name]
+        self.url = options[:url]        
+      end
+      
+      # Removes the table from the current account.
+      def destroy!
+        self.class.service_instance.delete_table(self.name)
+      end
+    end
+  end
+end

data/lib/waz/tables/table_array.rb

@@ -0,0 +1,11 @@
+module WAZ
+  module Tables
+    class TableArray < Array
+      attr_accessor :continuation_token
+      
+      def initialize(array)
+        super(array)
+      end
+    end
+  end
+end

data/rakefile

@@ -0,0 +1,23 @@
+#!/usr/bin/env rake
+require 'rspec/core/rake_task'
+require 'rake/rdoctask'
+require 'bundler/gem_tasks'
+
+RSpec::Core::RakeTask.new do |t|
+  t.name = :specs
+  t.pattern = "tests/**/*_test.rb"
+  t.rcov = true
+  t.rcov_opts = ['--text-report', '--exclude', "exclude.*/.gem,test,Library,#{ENV['GEM_HOME']}", '--sort', 'coverage' ]
+  t.rspec_opts = ['-cfn']
+end
+
+namespace :docs do
+  Rake::RDocTask.new do |t|
+  	t.rdoc_dir = 'rdoc'
+  	t.title    = "Windows Azure Storage library - simple gem for accessing WAZ's Storage REST API"
+  	t.options << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object'
+  	t.options << '--charset' << 'utf-8'
+  	t.rdoc_files.include('README.rdoc')
+  	t.rdoc_files.include('lib/**/*.rb')
+  end
+end