aws-sdk 1.2.6 → 1.3.0

data/lib/aws/record/model/finder_methods.rb

@@ -0,0 +1,232 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+module AWS
+  module Record
+    class Model
+      class << self
+
+        # @param [String] id The id of the record to load.
+        # @param [Hash] options
+        # @option options [String] :shard Specifies what shard (i.e. domain)
+        #   should be searched.
+        # @raise [RecordNotFound] Raises a record not found exception if there
+        #   was no data found for the given id.
+        # @return [Record::HashModel] Returns the record with the given id.
+        def find_by_id id, options = {}
+  
+          domain = sdb_domain(options[:shard] || options[:domain])
+  
+          data = domain.items[id].data.attributes
+  
+          raise RecordNotFound, "no data found for id: #{id}" if data.empty?
+  
+          obj = self.new(:shard => domain)
+          obj.send(:hydrate, id, data)
+          obj
+  
+        end
+        alias_method :[], :find_by_id
+  
+        # Finds records in SimpleDB and returns them as objects of the 
+        # current class.
+        #
+        # Finding +:all+ returns an enumerable scope object
+        #
+        #  People.find(:all, :order => [:age, :desc], :limit => 10).each do |person|
+        #    puts person.name
+        #  end
+        #
+        # Finding +:first+ returns a single record (or nil)
+        #
+        #  boss = People.find(:first, :where => { :boss => true })
+        #
+        # Find accepts a hash of find modifiers (+:where+, +:order+ and
+        # +:limit+).  You can also choose to omit these modifiers and
+        # chain them on the scope object returned.  In the following
+        # example only one request is made to SimpleDB (when #each is
+        # called)
+        #
+        #   people = People.find(:all)
+        #
+        #   johns = people.where(:name => 'John Doe')
+        #
+        #   johns.order(:age, :desc).limit(10).each do |suspects|
+        #     # ...
+        #   end
+        #
+        # See also {#where}, {#order} and {#limit} for more
+        # information and options.
+        #
+        # @overload find(id)
+        #   @param id The record to find, raises an exception if the record is
+        #     not found.
+        #
+        # @overload find(mode, options = {})
+        #   @param [:all,:first] mode (:all) When finding +:all+ matching records
+        #     and array is returned of records.  When finding +:first+ then
+        #     +nil+ or a single record will be returned.
+        #   @param [Hash] options
+        #   @option options [Mixed] :where Conditions that determine what
+        #     records are returned.
+        #   @option options [String,Array] :sort The order records should be 
+        #     returned in.
+        #   @option options [Integer] :limit The max number of records to fetch.
+        def find *args
+          new_scope.find(*args)
+        end
+  
+        # Returns a chainable scope object that restricts further scopes to a
+        # particular domain.
+        #
+        #  Book.domain('books-2').each do |book|
+        #    # ...
+        #  end
+        #
+        # @param [String] domain
+        # @return [Scope] Returns a scope for restricting the domain of subsequent
+        def shard shard_name
+          new_scope.shard(shard_name)
+        end
+        alias_method :domain, :shard
+  
+        # Returns an enumerable scope object represents all records.
+        #
+        #   Book.all.each do |book|
+        #     # ...
+        #   end
+        #
+        # This method is equivalent to +find(:all)+, and therefore you can also
+        # pass aditional options.  See {#find} for more information on what 
+        # options you can pass.
+        #
+        #   Book.all(:where => { :author' => 'me' }).each do |my_book|
+        #     # ...
+        #   end
+        #
+        # @return [Scope] Returns an enumerable scope object.
+        def all options = {}
+          new_scope.find(:all, options)
+        end
+
+        # Yields once for each record.
+        def each &block
+          all.each(&block)
+        end
+  
+        # Counts records in SimpleDB.
+        #
+        # With no arguments, counts all records:
+        #
+        #   People.count
+        #
+        # Accepts query options to count a subset of records:
+        #
+        #   People.count(:where => { :boss => true })
+        #
+        # You can also count records on a scope object:
+        #
+        #   People.find(:all).where(:boss => true).count
+        #
+        # See {#find} and {Scope#count} for more details.
+        #
+        # @param [Hash] options (<code>{}</code>) Options for counting
+        #   records.
+        #
+        # @option options [Mixed] :where Conditions that determine what
+        #   records are counted.
+        # @option options [Integer] :limit The max number of records to count.
+        def count(options = {})
+          new_scope.count(options)
+        end
+        alias_method :size, :count
+  
+        # @return [Object,nil] Returns the first record found.  If there were
+        #   no records found, nil is returned.
+        def first options = {}
+          new_scope.first(options)
+        end
+  
+        # Limits which records are retried from SimpleDB when performing a find.
+        #   
+        # Simple string condition
+        #
+        #   Car.where('color = "red" or color = "blue"').each {|car| ... }
+        #   
+        # String with placeholders for quoting params
+        #
+        #   Car.where('color = ?', 'red')
+        #
+        #   Car.where('color = ? OR style = ?', 'red', 'compact')
+        #
+        #   # produces a condition using in, like: WHERE color IN ('red', 'blue')
+        #   Car.where('color IN ?', ['red','blue'])
+        # 
+        # Hash arguments
+        #
+        #   # WHERE age = '40' AND gender = 'male'
+        #   People.where(:age => 40, :gender => 'male').each {|person| ... }
+        #
+        #   # WHERE name IN ('John', 'Jane')
+        #   People.where(:name => ['John', 'Jane']).each{|person| ... }
+        #
+        # Chaining where with other scope modifiers
+        #
+        #   # 10 most expensive red cars
+        #   Car.where(:color => 'red').order(:price, :desc).limit(10)
+        #   
+        # @overload where(conditions_hash)
+        # @overload where(sql_fragment[, quote_params, ...])
+        #
+        # @param [Hash] conditions_hash A hash of attributes to values.  Each 
+        #   key/value pair from the hash becomes a find condition.  All conditions
+        #   are joined by AND.
+        def where *args
+          new_scope.where(*args)
+        end
+  
+        # Defines the order in which records are returned when performing a find.
+        # SimpleDB only allows sorting by one attribute per request.
+        #
+        #   # oldest to youngest
+        #   People.order(:age, :desc).each {|person| ... }
+        #
+        # You can chain order with the other scope modifiers:
+        #
+        #   Pepole.order(:age, :desc).limit(10).each {|person| ... }
+        #
+        # @overload order(attribute, direction = :asc)
+        # @param [String,Symbol] attribute The attribute in SimpleDB to sort by.
+        # @param [:asc,:desc] direction (:asc) The direction to sort, ascending
+        #   or descending order.
+        def order *args
+          new_scope.order(*args)
+        end
+  
+        # The maximum number of records to return.  By default, all records
+        # matching the where conditions will be returned from a find.
+        # 
+        #   People.limit(10).each {|person| ... }
+        #
+        # Limit can be chained with other scope modifiers:
+        #
+        #   People.where(:age => 40).limit(10).each {|person| ... }
+        #
+        def limit limit
+          new_scope.limit(limit)
+        end
+
+      end
+    end
+  end
+end

data/lib/aws/record/model/scope.rb

@@ -0,0 +1,213 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+  
+module AWS
+  module Record
+    class Model
+
+      # The primary interface for finding records with {AWS::Record::Model}.
+      #
+      # == Getting a Scope Object
+      #
+      # You should normally never need to construct a Scope object directly.
+      # Scope objects are returned from the AWS::Record::Model finder methods
+      # (e.g. +shard+, +where+, +order+, +limit+, etc).
+      #
+      #   books = Book.where(:author => 'John Doe')
+      #   books.class #=> AWS::Record::Scope, not Array
+      #
+      # Scopes are also returned from methods defined with the +scope+ method.
+      #
+      # == Chaining Scopes
+      #
+      # Scope objects represent a request, but do not actualy make a request
+      # until required.  This allows you to chain requests
+      #
+      #   # no request made by the following 2 statements
+      #   books = Book.where(:author => 'John Doe')
+      #   books = books.limit(10)
+      #
+      #   books.each do |book|
+      #     # yields up to 10 books
+      #   end
+      #
+      # Each of the following methods returns a scope that can be chained.
+      #
+      # * {#shard}
+      # * {#where}
+      # * {#order}
+      # * {#limit}
+      #
+      # == Terminating Scopes
+      #
+      # To terminate a scope you can enumerate it or call #first.
+      #
+      #   # terminate a scope by enumerating
+      #   Book.limit(10).each {|book| ... }
+      #
+      #   # terminate a scope by getting the first value
+      #   Book.where('author' => 'John Doe').first
+      #
+      class Scope < Record::Scope
+        
+        # @private
+        def initialize base_class, options = {}
+          super
+          @options[:where] ||= []
+        end
+  
+        def new attributes = {}
+
+          attributes = attributes.dup
+
+          @options[:where].each do |conditions|
+            if conditions.size == 1 and conditions.first.is_a?(Hash)
+              attributes.merge!(conditions.first)
+            end
+          end
+  
+          super(attributes)
+  
+        end
+  
+        # Applies conditions to the scope that limit which records are returned.
+        # Only those matching all given conditions will be returned.
+        #
+        # @overload where(conditions_hash)
+        #   Specify a hash of conditions to query with.  Multiple conditions
+        #   are joined together with AND.
+        #
+        #     Book.where(:author => 'John Doe', :softcover => true)
+        #     # where `author` = `John Doe` AND `softcover` = `1`
+        #
+        #   @param [Hash] conditions
+        #
+        # @overload where(conditions_string, *values)
+        #   A sql-like query fragment with optional placeholders and values.
+        #   Placeholders are replaced with properly quoted values.
+        #
+        #     Book.where('author = ?', 'John Doe')
+        #
+        #   @param [String] conditions_string A sql-like where string with
+        #     question mark placeholders.  For each placeholder there should
+        #     be a value that will be quoted into that position.
+        #   @param [String] *values A value that should be quoted into the
+        #     corresponding (by position) placeholder.
+        #
+        # @return [Scope] Returns a new scope with the passed conditions applied.
+        def where *conditions
+          if conditions.empty?
+            raise ArgumentError, 'missing required condition'
+          end
+          _with(:where => @options[:where] + [conditions])
+        end
+    
+        # Specifies how to sort records returned.  
+        #
+        #   # enumerate books, starting with the most recently published ones
+        #   Book.order(:published_at, :desc).each do |book|
+        #     # ...
+        #   end
+        #
+        # Only one order may be applied.  If order is specified more than
+        # once the last one in the chain takes precedence:
+        #
+        #    
+        #   # books returned by this scope will be ordered by :published_at
+        #   # and not :author.
+        #   Book.where(:read => false).order(:author).order(:published_at)
+        #
+        # @param [String,Symbol] attribute_name The attribute to sort by.
+        # @param [:asc, :desc] order (:asc) The direct to sort.
+        def order attribute_name, order = :asc
+          _with(:order => [attribute_name, order])
+        end
+    
+        # @private
+        private
+        def _each_object &block
+  
+          items = _item_collection
+  
+          items.select.each do |item_data|
+            obj = base_class.new(:shard => _shard)
+            obj.send(:hydrate, item_data.name, item_data.attributes)
+            yield(obj)
+          end
+  
+        end
+    
+        # Merges another scope with this scope.  Conditions are added together
+        # and the limit and order parts replace those in this scope (if set).
+        # @param [Scope] scope A scope to merge with this one.
+        # @return [Scope] Returns a new scope with merged conditions and 
+        #   overriden order and limit.
+        # @private
+        private
+        def _merge_scope scope
+          merged = self
+          scope.instance_variable_get('@options').each_pair do |opt_name,opt_value|
+            unless [nil, []].include?(opt_value)
+              if opt_name == :where
+                opt_value.each do |condition| 
+                  merged = merged.where(*condition) 
+                end
+              else
+                merged = merged.send(opt_name, *opt_value)
+              end
+            end
+          end
+          merged
+        end
+  
+        # Consumes a hash of options (e.g. +:where+, +:order+ and +:limit+) and
+        # builds them onto the current scope, returning a new one.
+        # @param [Hash] options
+        # @option options :where
+        # @option options :order
+        # @option options [Integer] :limit
+        # @return [Scope] Returns a new scope with the hash of scope 
+        #   options applied.
+        # @private
+        private
+        def _handle_options options
+          scope = self
+          options.each_pair do |method, args|
+            if method == :where and args.is_a?(Hash)
+              # splatting a hash turns it into an array, bad juju
+              scope = scope.send(method, args)
+            else
+              scope = scope.send(method, *args)
+            end
+          end
+          scope
+        end
+  
+        # Converts this scope object into an AWS::SimpleDB::ItemCollection
+        # @return [SimpleDB::ItemCollection]
+        # @private
+        private
+        def _item_collection
+          items = base_class.sdb_domain(_shard).items
+          items = items.order(*@options[:order]) if @options[:order]
+          items = items.limit(*@options[:limit]) if @options[:limit]
+          @options[:where].each do |where_condition|
+            items = items.where(*where_condition)
+          end
+          items
+        end
+  
+      end
+    end
+  end
+end

data/lib/aws/record/scope.rb

@@ -14,90 +14,59 @@
 module AWS
   module Record
 
-    # The primary interface for finding records with AWS::Record.
-    #
-    # == Getting a Scope Object
-    #
-    # You should normally never need to construct a Scope object directly.
-    # Scope objects are returned from the AWS::Record::Base finder methods
-    # (e.g. +find+ +all+, +where+, +order+, +limit+, etc).
-    #
-    #   books = Book.where(:author => 'John Doe')
-    #   books.class #=> AWS::Record::Scope, not Array
-    #
-    # Scopes are also returned from methods defined with the +scope+ method.
-    #
-    # == Delayed Execution
-    #
-    # Scope objects represent a select expression, but do not actually
-    # cause a request to be made until enumerated.
-    #
-    #   # no request made yet
-    #   books = Book.where(:author => 'John Doe')
-    #
-    #   # a request is made now
-    #   books.each {|book| ... }
-    #
-    # You can refine a scope object by calling other scope methods on
-    # it.
-    #
-    #   # refine the previous books Scope, no request
-    #   top_10 = books.order(:popularity, :desc).limit(10)
-    #
-    #   # another request is made now
-    #   top_10.first
-    #
+    # Base class for {AWS::Record::Model::Scope} and
+    # {AWS::Record::HashModel::Scope}.
     class Scope
   
       include Enumerable
       
-      # @param [Record::Base] base_class A class that extends 
-      #   {AWS::Record::Base}.  
+      # @param base_class A class that extends {AWS::Record::AbstractBase}.
       # @param [Hash] options
       # @option options :
       # @private
       def initialize base_class, options = {}
+
         @base_class = base_class
+
         @options = options.dup
-        @options[:where] ||= []
-        @options[:domain] ||= base_class.domain_name
+
+        # backwards compat
+        @options[:shard] = @options.delete(:domain) if @options[:domain]
+
       end
   
-      # @return [Class] Returns the AWS::Record::Base extending class that
+      # @return [Class] Returns the AWS::Record::Model extending class that
       #   this scope will find records for.
       attr_reader :base_class
 
       def new attributes = {}
 
-        options = {}
-        options.merge!(attributes)
-        unless options.key?(:domain) or options.key?('domain')
-          options[:domain] = _domain
-        end
+        attributes = attributes.dup
+        attributes[:shard] ||= attributes.delete(:shard)
+        attributes[:shard] ||= attributes.delete('shard')
+        # for backwards compatability, domain is accepted
+        attributes[:shard] ||= attributes.delete('domain')
+        attributes[:shard] ||= attributes.delete(:domain)
+        attributes[:shard] ||= _shard
 
-        @options[:where].each do |conditions|
-          if conditions.size == 1 and conditions.first.is_a?(Hash)
-            options.merge!(conditions.first)
-          end
-        end
-
-        base_class.new(options)
+        base_class.new(attributes)
 
       end
       alias_method :build, :new
 
-      # @param [String] domain
-      # @return [Scope] Returns a scope for restricting the domain of subsequent
-      #   scope operations
-      def domain name
-        _with(:domain => name)
+      # @param [String] shard_name
+      # @return [Scope] Returns a scope that specifies which shard
+      #   (i.e. SimpleDB domain) should be used.
+      def shard shard_name
+        _with(:shard => shard_name)
       end
+      alias_method :domain, :shard
   
       # @overload find(id)
       #   Finds and returns a single record by id.  If no record is found
       #   with the given +id+, then a RecordNotFound error will be raised.
       #   @param [String] id ID of the record to find.
-      #   @return [Record::Base] Returns the record.
+      #   @return Returns the record.
       #   
       # @overload find(:first, options = {})
       #   Returns the first record found.  If no records were matched then
@@ -125,7 +94,7 @@ module AWS
         when id_or_mode == :all   then scope
         when id_or_mode == :first then scope.limit(1).to_a.first
         else
-          base_class.find_by_id(id_or_mode, :domain => scope._domain)
+          base_class.find_by_id(id_or_mode, :shard => scope._shard)
         end
   
       end
@@ -141,64 +110,11 @@ module AWS
       end
       alias_method :size, :count
 
-      # @return [Record::Base,nil] Gets the first record from the domain
-      #   and returns it, or returns nil if the domain is empty.
+      # @return Returns the first record found, returns
+      #   nil if the domain/table is empty.
       def first options = {}
         _handle_options(options).find(:first)
       end
-
-      # Applies conditions to the scope that limit which records are returned.
-      # Only those matching all given conditions will be returned.
-      #
-      # @overload where(conditions_hash)
-      #   Specify a hash of conditions to query with.  Multiple conditions
-      #   are joined together with AND.
-      #
-      #     Book.where(:author => 'John Doe', :softcover => true)
-      #     # where `author` = `John Doe` AND `softcover` = `1`
-      #
-      #   @param [Hash] conditions
-      #
-      # @overload where(conditions_string, *values)
-      #   A sql-like query fragment with optional placeholders and values.
-      #   Placeholders are replaced with properly quoted values.
-      #
-      #     Book.where('author = ?', 'John Doe')
-      #
-      #   @param [String] conditions_string A sql-like where string with
-      #     question mark placeholders.  For each placeholder there should
-      #     be a value that will be quoted into that position.
-      #   @param [String] *values A value that should be quoted into the
-      #     corresponding (by position) placeholder.
-      #
-      # @return [Scope] Returns a new scope with the passed conditions applied.
-      def where *conditions
-        if conditions.empty?
-          raise ArgumentError, 'missing required condition'
-        end
-        _with(:where => @options[:where] + [conditions])
-      end
-  
-      # Specifies how to sort records returned.  
-      #
-      #   # enumerate books, starting with the most recently published ones
-      #   Book.order(:published_at, :desc).each do |book|
-      #     # ...
-      #   end
-      #
-      # Only one order may be applied.  If order is specified more than
-      # once the last one in the chain takes precedence:
-      #
-      #    
-      #   # books returned by this scope will be ordered by :published_at
-      #   # and not :author.
-      #   Book.where(:read => false).order(:author).order(:published_at)
-      #
-      # @param [String,Symbol] attribute_name The attribute to sort by.
-      # @param [:asc, :desc] order (:asc) The direct to sort.
-      def order attribute_name, order = :asc
-        _with(:order => [attribute_name, order])
-      end
   
       # Limits the maximum number of total records to return when finding
       # or counting.  Returns a scope, does not make a request.
@@ -229,28 +145,21 @@ module AWS
       end
 
       protected
-      def _domain
-        @options[:domain] 
+      def _shard
+        @options[:shard] || base_class.shard_name
       end
+      alias_method :domain, :shard
   
       # @private
       private
       def _each_object &block
-
-        items = _item_collection
-
-        items.select.each do |item_data|
-          obj = base_class.new(:domain => _domain)
-          obj.send(:hydrate, item_data.name, item_data.attributes)
-          yield(obj)
-        end
-
+        raise NotImplementedError
       end
   
       # @private
       private
       def _with options
-        Scope.new(base_class, @options.merge(options))
+        self.class.new(base_class, @options.merge(options))
       end
   
       # @private
@@ -260,66 +169,31 @@ module AWS
         _merge_scope(base_class.send(scope_name, *args))
       end
   
-      # Merges another scope with this scope.  Conditions are added together
-      # and the limit and order parts replace those in this scope (if set).
-      # @param [Scope] scope A scope to merge with this one.
-      # @return [Scope] Returns a new scope with merged conditions and 
-      #   overriden order and limit.
+      # Merges the one scope with the current scope, returning a 3rd.
+      # @param [Scope] scope
+      # @return [Scope]
       # @private
       private
       def _merge_scope scope
-        merged = self
-        scope.instance_variable_get('@options').each_pair do |opt_name,opt_value|
-          unless [nil, []].include?(opt_value)
-            if opt_name == :where
-              opt_value.each do |condition| 
-                merged = merged.where(*condition) 
-              end
-            else
-              merged = merged.send(opt_name, *opt_value)
-            end
-          end
-        end
-        merged
+        raise NotImplementedError
       end
 
-      # Consumes a hash of options (e.g. +:where+, +:order+ and +:limit+) and
-      # builds them onto the current scope, returning a new one.
-      # @param [Hash] options
-      # @option options :where
-      # @option options :order
-      # @option options [Integer] :limit
-      # @return [Scope] Returns a new scope with the hash of scope 
-      #   options applied.
+      # Consumes a hash of options (e.g. +:shard+, +:limit) and returns
+      # a new scope with those applied.
+      # @return [Scope]
       # @private
       private
       def _handle_options options
-        scope = self
-        options.each_pair do |method, args|
-          if method == :where and args.is_a?(Hash)
-            # splatting a hash turns it into an array, bad juju
-            scope = scope.send(method, args)
-          else
-            scope = scope.send(method, *args)
-          end
-        end
-        scope
+        raise NotImplementedError
       end
 
-      # Converts this scope object into an AWS::SimpleDB::ItemCollection
-      # @return [SimpleDB::ItemCollection]
       # @private
       private
       def _item_collection
-        items = base_class.sdb_domain(_domain).items
-        items = items.order(*@options[:order]) if @options[:order]
-        items = items.limit(*@options[:limit]) if @options[:limit]
-        @options[:where].each do |where_condition|
-          items = items.where(*where_condition)
-        end
-        items
+        raise NotImplementedError
       end
 
     end
+
   end
 end