aws-sdk 1.0.1 → 1.0.2

data/lib/aws/record/base.rb

@@ -19,7 +19,9 @@ require 'aws/indifferent_hash'
 
 require 'aws/record/naming'
 require 'aws/record/attribute_macros'
+require 'aws/record/scopes'
 require 'aws/record/finder_methods'
+require 'aws/record/optimistic_locking'
 require 'aws/record/validations'
 require 'aws/record/dirty_tracking'
 require 'aws/record/conversion'
@@ -288,6 +290,9 @@ module AWS
       extend Validations
       extend AttributeMacros
       extend FinderMethods
+      extend OptimisticLocking
+      extend Scopes
+
       include Conversion
       include DirtyTracking
   
@@ -410,6 +415,41 @@ module AWS
         persisted? ? !!@_deleted : false
       end
 
+      class << self
+
+        # @return [Hash<String,Attribute>] Returns a hash of all of the
+        #   configured attributes for this class.
+        def attributes
+          @attributes ||= {}
+        end
+
+        # Allows you to override the default domain name for this record.  
+        # The defualt domain name is the class name.
+        # @param [String] The domain name that should be used for this class.
+        def set_domain_name name
+          @_domain_name = name
+        end
+
+        # @return [String] Returns the full prefixed domain name for this class.
+        def domain_name
+          @_domain_name ||= self.to_s
+          "#{Record.domain_prefix}#{@_domain_name}"
+        end
+
+        # Creates the SimpleDB domain that is configured for this class.
+        def create_domain
+          AWS::SimpleDB.new.domains.create(domain_name)
+        end
+
+        # @return [AWS::SimpleDB::Domain] Returns a reference to the domain
+        #   this class will save data to.
+        # @private
+        def sdb_domain
+          AWS::SimpleDB.new.domains[domain_name]
+        end
+
+      end
+
       # If you define a custom setter, you use #[]= to set the value 
       # on the record.
       #

data/lib/aws/record/finder_methods.rb

@@ -16,6 +16,7 @@ require 'aws/record/scope'
 
 module AWS
   module Record
+
     module FinderMethods
   
       # @param [String] id The id of the record to load.
@@ -83,8 +84,22 @@ module AWS
         _new_scope.find(*args)
       end
 
-      # Equivalent to +find(:all)+
-      def all(options = {})
+      # 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 = {}
         find(:all, options)
       end
 
@@ -188,75 +203,6 @@ module AWS
         _new_scope.limit(limit)
       end
 
-      # @private
-      def _new_scope
-        Scope.new(self)
-      end
-      private :_new_scope
-
-      # A configuration method to override the default domain name.
-      # @param [String] The domain name that should be used for this class.
-      def set_domain_name name
-        @_domain_name = name
-      end
-
-      # @return [String] Returns the full prefixed domain name for this class.
-      # 
-      def domain_name
-        @_domain_name ||= self.to_s
-        "#{Record.domain_prefix}#{@_domain_name}"
-      end
-
-      # @return [AWS::SimpleDB::Domain] A reference to the domain
-      #   this class will save data to.
-      def sdb_domain
-        AWS::SimpleDB.new.domains[domain_name]
-      end
-
-      # Creates the SimpleDB domain that is configured for this class.
-      def create_domain
-        AWS::SimpleDB.new.domains.create(domain_name)
-      end
-
-      # @return [Hash] A hash of Attribute objects that represent the
-      #   "columns" objects in this domain use.
-      def attributes
-        @attributes ||= {}
-      end
-
-      # @param [Symbol] name The name of the scope.  Scope names should be
-      #   method-safe and should not conflict with any of the class 
-      #   methods of {Record::Base} or {Record::Scope}.
-      #
-      # Adding a scope using built-in scope modifiers:
-      #
-      #   scope :top_10, order(:rating, :desc).limit(10)
-      #
-      def scope name, scope = nil, &block
-        
-        raise ArgumentError, "only a scope or block may be passed, not both" if
-          scope and block_given?
-
-        if scope
-          method_definition = lambda { scope }
-        else
-          method_definition = block
-        end
-
-        extend(Module.new { define_method(name, &method_definition) })
-
-      end
-
-      def optimistic_locking attribute_name = :version_id
-        attribute = integer_attr(attribute_name)
-        @optimistic_locking_attr = attribute
-      end
-
-      # @private
-      def optimistic_locking_attr
-        @optimistic_locking_attr
-      end
-
     end
   end
 end

data/lib/aws/record/optimistic_locking.rb

@@ -0,0 +1,34 @@
+# Copyright 2011 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.
+
+require 'aws/simple_db'
+require 'aws/record/scope'
+
+module AWS
+  module Record
+
+    module OptimisticLocking
+
+      def optimistic_locking attribute_name = :version_id
+        attribute = integer_attr(attribute_name)
+        @optimistic_locking_attr = attribute
+      end
+
+      # @private
+      def optimistic_locking_attr
+        @optimistic_locking_attr
+      end
+
+    end
+  end
+end

data/lib/aws/record/scope.rb

@@ -13,17 +13,82 @@
   
 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
+    #
     class Scope
   
       include Enumerable
-  
-      attr_reader :base_class
       
+      # @param [Record::Base] base_class A class that extends 
+      #   {AWS::Record::Base}.  
+      # @param [Hash] options
+      # @option options :
+      # @private
       def initialize base_class, options = {}
         @base_class = base_class
         @options = options
       end
   
+      # @return [Class] Returns the AWS::Record::Base extending class that
+      #   this scope will find records for.
+      attr_reader :base_class
+  
+      # @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.
+      #   
+      # @overload find(:first, options = {})
+      #   Returns the first record found.  If no records were matched then
+      #   nil will be returned (raises no exceptions).
+      #   @param [Symbol] mode (:first)
+      #   @return [Object,nil] Returns the first record or nil if no
+      #     records matched the conditions.
+      #
+      # @overload find(:all, options = {})
+      #   Returns an enumerable Scope object that represents all matching
+      #   records.  No request is made to AWS until the scope is enumerated.
+      #
+      #     Book.find(:all, :limit => 100).each do |book|
+      #       # ...
+      #     end
+      #
+      #   @param [Symbol] mode (:all)
+      #   @return [Scope] Returns an enumerable scope object.
+      #
       def find id_or_mode, options = {}
 
         scope = _handle_options(options)
@@ -35,16 +100,17 @@ module AWS
         else
           object = scope.where('itemName() = ?', id_or_mode).limit(1).first
           if object.nil?
-            raise RecordNotFound, "no data found for id: #{id_or_mode}"
+            raise RecordNotFound, "no data found for record `#{id_or_mode}`"
           end
           object
         end
   
       end
 
-      def count(options = {})
-        if scope = _handle_options(options) and
-            scope != self
+      # @return [Integer] Returns the number of records that match the
+      #   current scoped finder.
+      def count options = {}
+        if scope = _handle_options(options) and scope != self
           scope.count
         else
           _item_collection.count
@@ -52,6 +118,31 @@ module AWS
       end
       alias_method :size, :count
 
+      # 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'
@@ -59,14 +150,47 @@ module AWS
         _with(:where => Record.as_array(@options[:where]) + [conditions])
       end
   
-      def order attribute, order = :asc
-        _with(:order => [attribute, order])
+      # 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.
+      #
+      #   books = Book.limit(100)
+      #
+      # @param [Integer] limit The maximum number of records to return.
+      # @return [Scope] Returns a new scope that has the applied limit.
       def limit limit
         _with(:limit => limit)
       end
   
+      # Yields once for each record matching the request made by this scope.
+      #
+      #   books = Book.where(:author => 'me').order(:price, :asc).limit(10)
+      #
+      #   books.each do |book|
+      #     puts book.attributes.to_yaml
+      #   end
+      #
+      # @yieldparam [Object] record 
       def each &block
         if block_given?
           _each_object(&block)
@@ -76,12 +200,13 @@ module AWS
       end
   
       # @private
+      private
       def _empty?
         @options == {}
       end
-      private :_empty?
   
       # @private
+      private
       def _each_object &block
 
         items = _item_collection
@@ -93,22 +218,27 @@ module AWS
         end
 
       end
-      private :_each_object
   
       # @private
+      private
       def _with options
         Scope.new(base_class, @options.merge(options))
       end
-      private :_with
   
       # @private
+      private
       def method_missing scope_name, *args
         # @todo only proxy named scope methods
         _merge_scope(base_class.send(scope_name, *args))
       end
-      private :method_missing
   
+      # 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|
@@ -124,10 +254,18 @@ module AWS
         end
         merged
       end
-      private :_merge_scope
 
+      # 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
-      def _handle_options(options)
+      private
+      def _handle_options options
         scope = self
         options.each_pair do |method, args|
           if method == :where and args.is_a?(Hash)
@@ -139,9 +277,11 @@ module AWS
         end
         scope
       end
-      private :_handle_options
 
+      # Converts this scope object into an AWS::SimpleDB::ItemCollection
+      # @return [SimpleDB::ItemCollection]
       # @private
+      private
       def _item_collection
         items = base_class.sdb_domain.items
         items = items.order(*@options[:order]) if @options[:order]
@@ -151,7 +291,7 @@ module AWS
         end
         items
       end
-      private :_item_collection
+
     end
   end
 end