right_aws 1.9.0 → 3.1.0

data/lib/sdb/active_sdb.rb

@@ -21,13 +21,6 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-begin
-  require 'uuidtools'
-rescue LoadError => e
-  STDERR.puts("RightSDB Alpha requires the uuidtools gem.  Run \'gem install uuidtools\' and try again.")
-  exit
-end
-
 module RightAws
 
   # = RightAws::ActiveSdb -- RightScale SDB interface (alpha release)
@@ -39,9 +32,6 @@ module RightAws
   #   require 'right_aws'
   #   require 'sdb/active_sdb'
   #   
-  # Additionally, the ActiveSdb class requires the 'uuidtools' gem; this gem is not normally required by RightAws and is not installed as a 
-  # dependency of RightAws.
-  #
   # Simple ActiveSdb usage example:
   #
   #  class Client < RightAws::ActiveSdb::Base 
@@ -92,6 +82,59 @@ module RightAws
   #  # remove domain
   #  Client.delete_domain
   #
+  #  # Dynamic attribute accessors
+  #
+  #  class KdClient < RightAws::ActiveSdb::Base
+  #  end
+  #
+  #  client = KdClient.select(:all, :order => 'expiration').first
+  #    pp client.attributes #=>
+  #      {"name"=>["Putin"],
+  #       "post"=>["president"],
+  #       "country"=>["Russia"],
+  #       "expiration"=>["2008"],
+  #       "id"=>"376d2e00-75b0-11dd-9557-001bfc466dd7",
+  #       "gender"=>["male"]}
+  #
+  #    pp client.name    #=> ["Putin"]
+  #    pp client.country #=> ["Russia"]
+  #    pp client.post    #=> ["president"]
+  #
+  # # Columns and simple typecasting
+  #
+  #  class Person < RightAws::ActiveSdb::Base
+  #    columns do
+  #      name
+  #      email
+  #      score         :Integer
+  #      is_active     :Boolean
+  #      registered_at :DateTime
+  #      created_at    :DateTime, :default => lambda{ Time.now }
+  #    end
+  #  end
+  #  Person::create( :name => 'Yetta E. Andrews', :email => 'nulla.facilisis@metus.com', :score => 100, :is_active => true, :registered_at => Time.local(2000, 1, 1) )
+  #
+  #  person = Person.find_by_email 'nulla.facilisis@metus.com'
+  #  person.reload
+  #
+  #  pp person.attributes #=>
+  #    {"name"=>["Yetta E. Andrews"],
+  #     "created_at"=>["2010-04-02T20:51:58+0400"],
+  #     "id"=>"0ee24946-3e60-11df-9d4c-0025b37efad0",
+  #     "registered_at"=>["2000-01-01T00:00:00+0300"],
+  #     "is_active"=>["T"],
+  #     "score"=>["100"],
+  #     "email"=>["nulla.facilisis@metus.com"]}
+  #  pp person.name                #=> "Yetta E. Andrews"
+  #  pp person.name.class          #=> String
+  #  pp person.registered_at.to_s  #=> "2000-01-01T00:00:00+03:00"
+  #  pp person.registered_at.class #=> DateTime
+  #  pp person.is_active           #=> true
+  #  pp person.is_active.class     #=> TrueClass
+  #  pp person.score               #=> 100
+  #  pp person.score.class         #=> Fixnum
+  #  pp person.created_at.to_s     #=> "2010-04-02T20:51:58+04:00"
+  #
   class ActiveSdb
     
     module ActiveSdbConnect
@@ -106,7 +149,6 @@ module RightAws
       #      :port         => 443                  # Amazon service port: 80 or 443(default)
       #      :protocol     => 'https'              # Amazon service protocol: 'http' or 'https'(default)
       #      :signature_version => '0'             # The signature version : '0' or '1'(default)
-      #      :multi_thread => true|false           # Multi-threaded (connection per each thread): true or false(default)
       #      :logger       => Logger Object        # Logger instance: logs to STDOUT if omitted 
       #      :nil_representation => 'mynil'}       # interpret Ruby nil as this string value; i.e. use this string in SDB to represent Ruby nils (default is the string 'nil')
 
@@ -242,7 +284,31 @@ module RightAws
         def delete_domain
           connection.delete_domain(domain)
         end
-        
+
+        def columns(&block)
+          @columns ||= ColumnSet.new
+          @columns.instance_eval(&block) if block
+          @columns
+        end
+
+        def column?(col_name)
+          columns.include?(col_name)
+        end
+
+        def type_of(col_name)
+          columns.type_of(col_name)
+        end
+
+        def serialize(attribute, value)
+          s = serialization_for_type(type_of(attribute))
+          s ? s.serialize(value) : value.to_s
+        end
+
+        def deserialize(attribute, value)
+          s = serialization_for_type(type_of(attribute))
+          s ? s.deserialize(value) : value
+        end
+
         # Perform a find request.
         #  
         # Single record: 
@@ -294,6 +360,8 @@ module RightAws
         #    Client.find(:first)                      #=> #<Client:0xb77d0d40 @attributes={"id"=>"2937601a-e45d-11dc-a75f-001bfc466dd7"}, @new_record=false>
         #    Client.find(:first, :auto_load => true)  #=> #<Client:0xb77d0d40 @attributes={"id"=>"2937601a-e45d-11dc-a75f-001bfc466dd7", "name"=>["Cat"], "toys"=>["Jons socks", "clew", "mice"]}, @new_record=false>
         #
+        # see http://docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?UsingQuery.html
+        #
         def find(*args)
           options = args.last.is_a?(Hash) ? args.pop : {}
           case args.first
@@ -303,12 +371,137 @@ module RightAws
           end
         end
 
+        # Perform a SQL-like select request.
+        #
+        # Single record:
+        #
+        #  Client.select(:first)
+        #  Client.select(:first, :conditions=> [ "name=? AND wife=?", "Jon", "Sandy"])
+        #  Client.select(:first, :conditions=> { :name=>"Jon", :wife=>"Sandy" }, :select => :girfriends)
+        #
+        # Bunch of records:
+        #
+        #  Client.select(:all)
+        #  Client.select(:all, :limit => 10)
+        #  Client.select(:all, :conditions=> [ "name=? AND 'girlfriend'=?", "Jon", "Judy"])
+        #  Client.select(:all, :conditions=> { :name=>"Sandy" }, :limit => 3)
+        #
+        # Records by ids:
+        #
+        #  Client.select('1')
+        #  Client.select('1234987b4583475347523948')
+        #  Client.select('1','2','3','4', :conditions=> ["toys=?", "beer"])
+        #
+        # Find helpers: RightAws::ActiveSdb::Base.select_by_... and RightAws::ActiveSdb::Base.select_all_by_...
+        #
+        #  Client.select_by_name('Matias Rust')
+        #  Client.select_by_name_and_city('Putin','Moscow')
+        #  Client.select_by_name_and_city_and_post('Medvedev','Moscow','president')
+        #
+        #  Client.select_all_by_author('G.Bush jr')
+        #  Client.select_all_by_age_and_gender_and_ethnicity('34','male','russian')
+        #  Client.select_all_by_gender_and_country('male', 'Russia', :order => 'name')
+        #
+        # Continue listing:
+        #
+        #  # initial listing
+        #  Client.select(:all, :limit => 10)
+        #  # continue listing
+        #  begin
+        #    Client.select(:all, :limit => 10, :next_token => Client.next_token)
+        #  end while Client.next_token
+        #
+        #  Sort oder:
+        #  If :order=>'attribute' option is specified then result response (ordered by 'attribute') will contain only items where attribute is defined (is not null).
+        #  
+        #    Client.select(:all)                         # returns all records
+        #    Client.select(:all, :order => 'gender')     # returns all records ordered by gender where gender attribute exists
+        #    Client.select(:all, :order => 'name desc')  # returns all records ordered by name in desc order where name attribute exists
+        #
+        # see http://docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?UsingSelect.html
+        #
+        def select(*args)
+          options = args.last.is_a?(Hash) ? args.pop : {}
+          case args.first
+            when :all   then sql_select(options)
+            when :first then sql_select(options.merge(:limit => 1)).first
+            else             select_from_ids args, options
+          end
+        end
+
+        def generate_id # :nodoc:
+          AwsUtils::generate_unique_token
+        end
+
       protected
 
+        # Select
+
+        def select_from_ids(args, options) # :nodoc:
+          cond = []
+          # detect amount of records requested
+          bunch_of_records_requested = args.size > 1 || args.first.is_a?(Array)
+          # flatten ids
+          args = Array(args).flatten
+          args.each { |id| cond << "id=#{self.connection.escape(id)}" }
+          ids_cond = "(#{cond.join(' OR ')})"
+          # user defined :conditions to string (if it was defined)
+          options[:conditions] = build_conditions(options[:conditions])
+          # join ids condition and user defined conditions
+          options[:conditions] = options[:conditions].right_blank? ? ids_cond : "(#{options[:conditions]}) AND #{ids_cond}"
+          result = sql_select(options)
+          # if one record was requested then return it
+          unless bunch_of_records_requested
+            record = result.first
+            # railse if nothing was found
+            raise ActiveSdbError.new("Couldn't find #{name} with ID #{args}") unless record
+            record
+          else
+            # if a bunch of records was requested then return check that we found all of them
+            # and return as an array
+            unless args.size == result.size
+              id_list = args.map{|i| "'#{i}'"}.join(',')
+              raise ActiveSdbError.new("Couldn't find all #{name} with IDs (#{id_list}) (found #{result.size} results, but was looking for #{args.size})")
+            else
+              result
+            end
+          end
+        end
+
+        def sql_select(options) # :nodoc:
+          @next_token = options[:next_token]
+          select_expression = build_select(options)
+          # request items
+          query_result = self.connection.select(select_expression, @next_token)
+          @next_token = query_result[:next_token]
+          items = query_result[:items].map do |hash|
+            id, attributes = hash.shift
+            new_item = self.new( attributes.merge({ 'id' => id }))
+            new_item.mark_as_old
+            new_item
+          end
+          items
+        end
+
+        # select_by helpers
+        def select_all_by_(format_str, args, options) # :nodoc:
+          fields = format_str.to_s.sub(/^select_(all_)?by_/,'').split('_and_')
+          conditions = fields.map { |field| "#{field}=?" }.join(' AND ')
+          options[:conditions] = [conditions, *args]
+          select(:all, options)
+        end
+
+        def select_by_(format_str, args, options) # :nodoc:
+          options[:limit] = 1
+          select_all_by_(format_str, args, options).first
+        end
+
+        # Query
+
         # Returns an array of query attributes.
         # Query_expression must be a well formated SDB query string:
         # query_attributes("['title' starts-with 'O\\'Reily'] intersection ['year' = '2007']") #=> ["title", "year"]
-        def query_attributes(query_expression)
+        def query_attributes(query_expression) # :nodoc:
           attrs = []
           array = query_expression.scan(/['"](.*?[^\\])['"]/).flatten
           until array.empty? do
@@ -334,8 +527,7 @@ module RightAws
         #
         def query(options) # :nodoc:
           @next_token = options[:next_token]
-          query_expression = options[:query_expression]
-          query_expression = connection.query_expression_from_array(query_expression) if query_expression.is_a?(Array)
+          query_expression = build_conditions(options[:query_expression])
           # add sort_options to the query_expression
           if options[:sort_option]
             sort_by, sort_order = sort_options(options[:sort_option])
@@ -345,7 +537,7 @@ module RightAws
             query_expression = query_expression.to_s
             # quote from Amazon:
             # The sort attribute must be present in at least one of the predicates of the query expression.
-            if query_expression.blank?
+            if query_expression.right_blank?
               query_expression = sort_query_expression
             elsif !query_attributes(query_expression).include?(sort_by)
               query_expression += " intersection #{sort_query_expression}"
@@ -358,14 +550,19 @@ module RightAws
           items = query_result[:items].map do |name| 
             new_item = self.new('id' => name)
             new_item.mark_as_old
-            new_item.reload if options[:auto_load]
+            reload_if_exists(record) if options[:auto_load]
             new_item
           end
           items
         end
 
+        # reload a record unless it is nil
+        def reload_if_exists(record) # :nodoc:
+          record && record.reload
+        end
+
         def reload_all_records(*list) # :nodoc:
-          list.flatten.each { |record| record.reload }
+          list.flatten.each { |record| reload_if_exists(record) }
         end
 
         def find_every(options) # :nodoc:
@@ -387,19 +584,20 @@ module RightAws
           # detect amount of records requested
           bunch_of_records_requested = args.size > 1 || args.first.is_a?(Array)
           # flatten ids
-          args = args.to_a.flatten
+          args = Array(args).flatten
           args.each { |id| cond << "'id'=#{self.connection.escape(id)}" }
           ids_cond = "[#{cond.join(' OR ')}]"
           # user defined :conditions to string (if it was defined)
-          if options[:conditions].is_a?(Array)
-            options[:conditions] = connection.query_expression_from_array(options[:conditions])
-          end
+          options[:conditions] = build_conditions(options[:conditions])
           # join ids condition and user defined conditions
-          options[:conditions] = options[:conditions].blank? ? ids_cond : "#{options[:conditions]} intersection #{ids_cond}"
+          options[:conditions] = options[:conditions].right_blank? ? ids_cond : "#{options[:conditions]} intersection #{ids_cond}"
           result = find_every(options)
           # if one record was requested then return it
           unless bunch_of_records_requested
-            options[:auto_load] ? reload_all_records(result.first).first : result.first
+            record = result.first
+            # railse if nothing was found
+            raise ActiveSdbError.new("Couldn't find #{name} with ID #{args}") unless record
+            options[:auto_load] ? reload_all_records(record).first : record
           else
             # if a bunch of records was requested then return check that we found all of them
             # and return as an array
@@ -425,22 +623,46 @@ module RightAws
           find_all_by_(format_str, args, options).first
         end
 
+        # Misc
+
         def method_missing(method, *args) # :nodoc:
-          if method.to_s[/^(find_all_by_|find_by_)/]
+          if method.to_s[/^(find_all_by_|find_by_|select_all_by_|select_by_)/]
             options = args.last.is_a?(Hash) ? args.pop : {}
-            if method.to_s[/^find_all_by_/]
-              find_all_by_(method, args, options)
-            else
-              find_by_(method, args, options)
-            end
+            __send__($1, method, args, options)
           else
             super(method, *args)
           end
         end
-      end
-      
-      def self.generate_id # :nodoc:
-        UUID.timestamp_create().to_s
+
+        def build_select(options) # :nodoc:
+          select     = options[:select]    || '*'
+          from       = options[:from]      || domain
+          conditions = options[:conditions] ? " WHERE #{build_conditions(options[:conditions])}" : ''
+          order      = options[:order]      ? " ORDER BY #{options[:order]}"                     : ''
+          limit      = options[:limit]      ? " LIMIT #{options[:limit]}"                        : ''
+          # mix sort by argument (it must present in response)
+          unless order.right_blank?
+            sort_by, sort_order = sort_options(options[:order])
+            conditions << (conditions.right_blank? ? " WHERE " : " AND ") << "(#{sort_by} IS NOT NULL)"
+          end
+          "SELECT #{select} FROM #{from}#{conditions}#{order}#{limit}"
+        end
+
+        def build_conditions(conditions) # :nodoc:
+          case
+          when conditions.is_a?(Array) then connection.query_expression_from_array(conditions)
+          when conditions.is_a?(Hash)  then connection.query_expression_from_hash(conditions)
+          else                              conditions
+          end
+        end
+
+        def serialization_for_type(type)
+          @serializations ||= {}
+          unless @serializations.has_key? type
+            @serializations[type] = ::RightAws::ActiveSdb.const_get("#{type}Serialization") rescue false
+          end
+          @serializations[type]
+        end
       end
       
       public
@@ -508,11 +730,15 @@ module RightAws
       def attributes=(attrs)
         old_id = @attributes['id']
         @attributes = uniq_values(attrs)
-        @attributes['id'] = old_id if @attributes['id'].blank? && !old_id.blank?
+        @attributes['id'] = old_id if @attributes['id'].right_blank? && !old_id.right_blank?
         self.attributes
       end
 
-      def connection 
+      def columns
+        self.class.columns
+      end
+
+      def connection
         self.class.connection
       end
 
@@ -526,7 +752,8 @@ module RightAws
       #  puts item['Cat'].inspect  #=> ["Jons socks", "clew", "mice"]
       #
       def [](attribute)
-        @attributes[attribute.to_s]
+        raw = @attributes[attribute.to_s]
+        self.class.column?(attribute) && raw ? self.class.deserialize(attribute, raw.first) : raw
       end
 
       # Updates the attribute identified by +attribute+ with the specified +values+.
@@ -537,7 +764,14 @@ module RightAws
       #
       def []=(attribute, values)
         attribute = attribute.to_s
-        @attributes[attribute] = attribute == 'id' ? values.to_s : values.to_a.uniq
+        @attributes[attribute] = case
+        when attribute == 'id'
+          values.to_s
+        when self.class.column?(attribute)
+          self.class.serialize(attribute, values)
+        else
+          Array(values).uniq
+        end
       end
 
       # Reload attributes from SDB. Replaces in-memory attributes.
@@ -550,7 +784,7 @@ module RightAws
         old_id = id
         attrs = connection.get_attributes(domain, id)[:attributes]
         @attributes = {}
-        unless attrs.blank?
+        unless attrs.right_blank?
           attrs.each { |attribute, values| @attributes[attribute] = values }
           @attributes['id'] = old_id
         end
@@ -576,7 +810,7 @@ module RightAws
         attrs_list.flatten.uniq.each do |attribute|
           attribute = attribute.to_s
           values = connection.get_attributes(domain, id, attribute)[:attributes][attribute]
-          unless values.blank?
+          unless values.right_blank?
             @attributes[attribute] = result[attribute] = values
           else
             @attributes.delete(attribute)
@@ -606,7 +840,7 @@ module RightAws
         prepare_for_update
         attrs = @attributes.dup
         attrs.delete('id')
-        connection.put_attributes(domain, id, attrs) unless attrs.blank?
+        connection.put_attributes(domain, id, attrs) unless attrs.right_blank?
         connection.put_attributes(domain, id, { 'id' => id }, :replace)
         mark_as_old
         @attributes
@@ -622,10 +856,10 @@ module RightAws
         prepare_for_update
         # if 'id' is present in attrs hash:
         # replace internal 'id' attribute and remove it from the attributes to be sent
-        @attributes['id'] = attrs['id'] unless attrs['id'].blank?
+        @attributes['id'] = attrs['id'] unless attrs['id'].right_blank?
         attrs.delete('id')
         # add new values to all attributes from list
-        connection.put_attributes(domain, id, attrs) unless attrs.blank?
+        connection.put_attributes(domain, id, attrs) unless attrs.right_blank?
         connection.put_attributes(domain, id, { 'id' => id }, :replace)
         attrs.each do |attribute, values|
           @attributes[attribute] ||= []
@@ -669,12 +903,12 @@ module RightAws
         prepare_for_update
         attrs = uniq_values(attrs)
         # if 'id' is present in attrs hash then replace internal 'id' attribute
-        unless attrs['id'].blank?
+        unless attrs['id'].right_blank?
           @attributes['id'] = attrs['id']
         else
           attrs['id'] = id
         end
-        connection.put_attributes(domain, id, attrs, :replace) unless attrs.blank?
+        connection.put_attributes(domain, id, attrs, :replace) unless attrs.right_blank?
         attrs.each { |attribute, values| attrs[attribute] = values }
         mark_as_old
         attrs
@@ -693,9 +927,17 @@ module RightAws
         raise_on_id_absence
         attrs = uniq_values(attrs)
         attrs.delete('id')
-        unless attrs.blank?
+        unless attrs.right_blank?
           connection.delete_attributes(domain, id, attrs)
-          attrs.each { |attribute, values| @attributes[attribute] -= values }
+          attrs.each do |attribute, values|
+            # remove the values from the attribute
+            if @attributes[attribute]
+              @attributes[attribute] -= values
+            else
+              # if the attribute is unknown remove it from a resulting list of fixed attributes
+              attrs.delete(attribute)
+            end
+          end
         end
         attrs
       end
@@ -714,7 +956,7 @@ module RightAws
         raise_on_id_absence
         attrs_list = attrs_list.flatten.map{ |attribute| attribute.to_s }
         attrs_list.delete('id')
-        unless attrs_list.blank?
+        unless attrs_list.right_blank?
           connection.delete_attributes(domain, id, attrs_list)
           attrs_list.each { |attribute| @attributes.delete(attribute) }
         end
@@ -749,25 +991,117 @@ module RightAws
         @new_record = false
       end
 
-    private    
-    
+      # support accessing attribute values via method call
+      def method_missing(method_sym, *args)
+        method_name = method_sym.to_s
+        setter = method_name[-1,1] == '='
+        method_name.chop! if setter
+
+        if @attributes.has_key?(method_name) || self.class.column?(method_name)
+          setter ? self[method_name] = args.first : self[method_name]
+        else
+          super
+        end
+      end
+
+    private
+
       def raise_on_id_absence
         raise ActiveSdbError.new('Unknown record id') unless id
       end
       
       def prepare_for_update
-        @attributes['id'] = self.class.generate_id if @attributes['id'].blank?
+        @attributes['id'] = self.class.generate_id if @attributes['id'].right_blank?
+        columns.all.each do |col_name|
+          self[col_name] ||= columns.default(col_name)
+        end
       end
       
       def uniq_values(attributes=nil) # :nodoc:
         attrs = {}
         attributes.each do |attribute, values|
           attribute = attribute.to_s
-          attrs[attribute] = attribute == 'id' ? values.to_s : values.to_a.uniq
-          attrs.delete(attribute) if values.blank?
+          attrs[attribute] = case
+          when attribute == 'id'
+            values.to_s
+          when self.class.column?(attribute)
+            values.is_a?(String) ? values : self.class.serialize(attribute, values)
+          else
+            Array(values).uniq
+          end
+          attrs.delete(attribute) if values.right_blank?
         end
         attrs
       end
     end
+
+    class ColumnSet
+      attr_accessor :columns
+      def initialize
+        @columns = {}
+      end
+
+      def all
+        @columns.keys
+      end
+
+      def column(col_name)
+        @columns[col_name.to_s]
+      end
+      alias_method :include?, :column
+
+      def type_of(col_name)
+        column(col_name) && column(col_name)[:type]
+      end
+
+      def default(col_name)
+        return nil unless include?(col_name)
+        default = column(col_name)[:default]
+        default.respond_to?(:call) ? default.call : default
+      end
+
+      def method_missing(method_sym, *args)
+        data_type = args.shift || :String
+        options = args.shift || {}
+        @columns[method_sym.to_s] = options.merge( :type => data_type )
+      end
+    end
+
+    class DateTimeSerialization
+      class << self
+        def serialize(date)
+          date.strftime('%Y-%m-%dT%H:%M:%S%z')
+        end
+
+        def deserialize(string)
+          r = DateTime.parse(string) rescue nil
+        end
+      end
+    end
+
+    class BooleanSerialization
+      class << self
+        def serialize(boolean)
+          boolean ? 'T' : 'F'
+        end
+
+        def deserialize(string)
+          string == 'T'
+        end
+      end
+    end
+
+    class IntegerSerialization
+      class << self
+        def serialize(int)
+          int.to_s
+        end
+
+        def deserialize(string)
+          string.to_i
+        end
+      end
+    end
+
   end
-end
+end