aws-sdk 1.2.6 → 1.3.0

data/lib/aws/record/hash_model/attributes.rb

@@ -0,0 +1,182 @@
+# 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.
+
+require 'aws/record/attributes.rb'
+
+module AWS
+  module Record
+    class HashModel
+      class << self
+  
+        # Adds a string attribute to this class.
+        #
+        # @example A standard string attribute
+        #
+        #   class Recipe < AWS::Record::Model
+        #     string_attr :name
+        #   end
+        #
+        #   recipe = Recipe.new(:name => "Buttermilk Pancakes")
+        #   recipe.name #=> 'Buttermilk Pancakes'
+        #
+        # @example A string attribute with +:set+ set to true
+        #
+        #   class Recipe < AWS::Record::Model
+        #     string_attr :tags, :set => true
+        #   end
+        #
+        #   recipe = Recipe.new(:tags => %w(popular dessert))
+        #   recipe.tags #=> #<Set: {"popular", "desert"}> 
+        #
+        # @param [Symbol] name The name of the attribute.
+        # @param [Hash] options
+        # @option options [Boolean] :set (false) When true this attribute
+        #   can have multiple values.
+        def string_attr name, options = {}
+          add_attribute(Attributes::StringAttr.new(name, options))
+        end
+  
+        # Adds an integer attribute to this class.
+        #
+        #   class Recipe < AWS::Record::Model
+        #     integer_attr :servings
+        #   end
+        #
+        #   recipe = Recipe.new(:servings => '10')
+        #   recipe.servings #=> 10
+        #
+        # @param [Symbol] name The name of the attribute.
+        # @param [Hash] options
+        # @option options [Boolean] :set (false) When true this attribute
+        #   can have multiple values.
+        def integer_attr name, options = {}
+          add_attribute(Attributes::IntegerAttr.new(name, options))
+        end
+  
+        # Adds a float attribute to this class.
+        #
+        #   class Listing < AWS::Record::Model
+        #     float_attr :score
+        #   end
+        #
+        #   listing = Listing.new(:score => '123.456')
+        #   listing.score # => 123.456
+        #
+        # @param [Symbol] name The name of the attribute.
+        # @param [Hash] options
+        # @option options [Boolean] :set (false) When true this attribute
+        #   can have multiple values.
+        def float_attr name, options = {}
+          add_attribute(Attributes::FloatAttr.new(name, options))
+        end
+  
+        # Adds a boolean attribute to this class.
+        #
+        # @example
+        #
+        #   class Book < AWS::Record::Model
+        #     boolean_attr :read
+        #   end
+        #
+        #   b = Book.new
+        #   b.read? # => false
+        #   b.read = true
+        #   b.read? # => true
+        #
+        #   listing = Listing.new(:score => '123.456'
+        #   listing.score # => 123.456
+        #
+        # @param [Symbol] name The name of the attribute.
+        def boolean_attr name, options = {}
+  
+          attr = add_attribute(Attributes::BooleanAttr.new(name, options))
+  
+          # add the boolean question mark method
+          define_method("#{attr.name}?") do
+            !!__send__(attr.name)
+          end
+  
+        end
+  
+        # Adds a datetime attribute to this class.
+        #
+        # @example A standard datetime attribute
+        #
+        #   class Recipe < AWS::Record::Model
+        #     datetime_attr :invented
+        #   end
+        #
+        #   recipe = Recipe.new(:invented => Time.now)
+        #   recipe.invented #=> <DateTime ...>
+        #
+        # If you add a datetime_attr for +:created_at+ and/or +:updated_at+ those
+        # will be automanaged.
+        #
+        # @param [Symbol] name The name of the attribute.
+        #
+        # @param [Hash] options
+        #
+        # @option options [Boolean] :set (false) When true this attribute
+        #   can have multiple date times.
+        #
+        def datetime_attr name, options = {}
+          add_attribute(Attributes::DateTimeAttr.new(name, options))
+        end
+  
+        # Adds a date attribute to this class.
+        #
+        # @example A standard date attribute
+        #
+        #   class Person < AWS::Record::Model
+        #     date_attr :birthdate
+        #   end
+        #
+        #   baby = Person.new
+        #   baby.birthdate = Time.now
+        #   baby.birthdate #=> <Date: ....>
+        #
+        # @param [Symbol] name The name of the attribute.
+        #
+        # @param [Hash] options
+        #
+        # @option options [Boolean] :set (false) When true this attribute
+        #   can have multiple dates.
+        #
+        def date_attr name, options = {}
+          add_attribute(Attributes::DateAttr.new(name, options))
+        end
+  
+        # A convenience method for adding the standard two datetime attributes
+        # +:created_at+ and +:updated_at+.
+        #
+        # @example
+        #
+        #   class Recipe < AWS::Record::Model
+        #     timestamps
+        #   end
+        #
+        #   recipe = Recipe.new
+        #   recipe.save
+        #   recipe.created_at #=> <DateTime ...>
+        #   recipe.updated_at #=> <DateTime ...>
+        # 
+        def timestamps
+          c = datetime_attr :created_at
+          u = datetime_attr :updated_at
+          [c, u]
+        end
+    
+      end
+    end
+  end
+end

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

@@ -0,0 +1,178 @@
+# 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 HashModel
+      class << self
+
+        # @param [String] id The id of the record to load.
+        # @param [Hash] options
+        # @option options [String] :shard Specifies what shard (i.e. table)
+        #   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 = {}
+  
+          table = dynamo_db_table(options[:shard])
+
+          data = table.items[id].attributes.to_h
+  
+          raise RecordNotFound, "no data found for id: #{id}" if data.empty?
+  
+          obj = self.new(:shard => table)
+          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 [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 table.
+        #
+        #  Book.shard('books-2').each do |book|
+        #    # ...
+        #  end
+        #
+        # @param [String] shard_name
+        # @return [Scope] Returns a scope for restricting the table searched.
+        def shard shard_name
+          new_scope.shard(shard_name)
+        end
+        alias_method :domain, :shard # backwards compat
+  
+        # 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 Amazon DynamoDB.
+        #
+        #   class Product < AWS::Record::HashModel
+        #   end
+        #
+        #   # returns the count of records in the 'Product' table
+        #   Product.count
+        #
+        # You can specify the table via #shard
+        #
+        #   # returns the count of records in the 'products-1' table
+        #   Product.shard('products-1').count
+        #
+        # You can also specify the shard as an option to #count.
+        #
+        #   Product.count(:shard => 'table-name')
+        #
+        # Chaining #count with #limit has no effect on the count.
+        #
+        #   Product.limit(10).count # same as Product.count, limit ignored
+        #
+        # @param [Hash] options
+        #
+        # @option [String] :shard Which shard to count records in.
+        # 
+        # @return [Integer] The count of records in the table.
+        #
+        def count
+          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
+  
+        # 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/hash_model/scope.rb

@@ -0,0 +1,108 @@
+# 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 HashModel
+
+      # The primary interface for finding records with {AWS::Record::HashModel}.
+      #
+      # == Getting a Scope Object
+      #
+      # You should normally never need to construct a Scope object directly.
+      # Scope objects are returned from the AWS::Record::HashModel finder 
+      # methods # (e.g. +shard+ and +limit+).
+      #
+      #   books = Book.limit(100)
+      #   books.class #=> AWS::Record::HashModel::Scope
+      #
+      # Scopes are also returned from methods defined with the +scope+ method.
+      #
+      #   class Book < AWS::Record::HashModel
+      #      scope :sampling, limit(10)
+      #   end
+      #
+      #   Book.sampling #=> returns a scope that limits to 10
+      #
+      # == 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.shard('books-1') # what table to search
+      #   books = books.limit(10) # how many records to fetch
+      #
+      #   books.each do |book|
+      #     # yields up to 10 books from the table 'books-1'
+      #   end
+      #
+      # The following methods returns a scope that can be chained.
+      #
+      # * {#shard}
+      # * {#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 record
+      #   Book.shard('books-1').first
+      #
+      class Scope < Record::Scope
+    
+        private
+        def _each_object &block
+  
+          items = _item_collection
+  
+          items.select(:limit => @options[:limit]).each do |item_data|
+            obj = base_class.new(:shard => _shard)
+            obj.send(:hydrate, item_data.attributes['id'], item_data.attributes)
+            yield(obj)
+          end
+  
+        end
+    
+        private
+        def _merge_scope scope
+          merged = self
+          scope.instance_variable_get('@options').each_pair do |opt_name,opt_value|
+            unless [nil, []].include?(opt_value)
+              merged = merged.send(opt_name, *opt_value)
+            end
+          end
+          merged
+        end
+  
+        private
+        def _handle_options options
+          scope = self
+          options.each_pair do |method, args|
+            scope = scope.send(method, *args)
+          end
+          scope
+        end
+  
+        private
+        def _item_collection
+          base_class.dynamo_db_table(_shard).items
+        end
+  
+      end
+    end
+  end
+end