aws-sdk-v1 1.52.0

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

@@ -0,0 +1,172 @@
+# Copyright 2011-2013 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 Amazon DynamoDB and returns them as objects of
+        # the current class.
+        #
+        # Finding `:all` returns an enumerable scope object
+        #
+        #     People.find(:all, :limit => 10).each do |person|
+        #       puts person.name
+        #     end
+        #
+        # Finding `:first` returns a single record (or nil)
+        #
+        #     boss = People.find(:first)
+        #
+        # Find accepts a hash of find modifiers (`:shard` 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, :limit => 10)
+        #
+        #     people = people.limit(10).find(:all)
+        #
+        # @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] :shard The shard name of the Amazon
+        #     DynamoDB table to search.
+        #   @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.
+        #
+        #     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 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
+
+        # 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-2013 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

data/lib/aws/record/model.rb

@@ -0,0 +1,453 @@
+# Copyright 2011-2013 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.
+
+# todo move these to included modules (like validations and naming)
+
+
+module AWS
+  module Record
+
+    # An ActiveRecord-like interface built ontop of Amazon SimpleDB.
+    #
+    #     class Book < AWS::Record::Model
+    #
+    #       string_attr :title
+    #       string_attr :author
+    #       integer_attr :number_of_pages
+    #
+    #       timestamps # adds a :created_at and :updated_at pair of timestamps
+    #
+    #     end
+    #
+    #     b = Book.new(:title => 'My Book', :author => 'Me', :pages => 1)
+    #     b.save
+    #
+    # # Attribute Macros
+    #
+    # When extending AWS::Record::Model you should first consider what
+    # attributes your class should have.  Unlike ActiveRecord, AWS::Record
+    # models are not backed by a database table/schema.  You must choose what
+    # attributes (and what types) you need.
+    #
+    # * `string_attr`
+    # * `boolean_attr`
+    # * `integer_attr`
+    # * `float_attr`
+    # * `datetime_attr`
+    # * `date_attr`
+    #
+    # ### Usage
+    #
+    # Normally you just call these methods inside your model class definition:
+    #
+    #     class Book < AWS::Record::Model
+    #       string_attr :title
+    #       boolean_attr :has_been_read
+    #       integer_attr :number_of_pages
+    #       float_attr :weight_in_pounds
+    #       datetime_attr :published_at
+    #     end
+    #
+    # For each attribute macro a pair of setter/getter methods are added #
+    # to your class (and a few other useful methods).
+    #
+    #     b = Book.new
+    #     b.title = "My Book"
+    #     b.has_been_read = true
+    #     b.number_of_pages = 1000
+    #     b.weight_in_pounds = 1.1
+    #     b.published_at = Time.now
+    #     b.save
+    #
+    #     b.id #=> "0aa894ca-8223-4d34-831e-e5134b2bb71c"
+    #     b.attributes
+    #     #=> { 'title' => 'My Book', 'has_been_read' => true, ... }
+    #
+    # ### Default Values
+    #
+    # All attribute macros accept the `:default_value` option.  This sets
+    # a value that is populated onto all new instnaces of the class.
+    #
+    #     class Book < AWS::Record::Model
+    #       string_attr :author, :default_value => 'Me'
+    #     end
+    #
+    #     Book.new.author #=> 'Me'
+    #
+    # ### Multi-Valued (Set) Attributes
+    #
+    # AWS::Record permits storing multiple values with a single attribute.
+    #
+    #     class Book < AWS::Record::Model
+    #       string_attr :tags, :set => true
+    #     end
+    #
+    #     b = Book.new
+    #     b.tags #=> #<Set: {}>
+    #
+    #     b.tags = ['fiction', 'fantasy']
+    #     b.tags #=> #<Set: {'fiction', 'fantasy'}>
+    #
+    # These multi-valued attributes are treated as sets, not arrays.  This
+    # means:
+    #
+    # * values are unordered
+    # * duplicate values are automatically omitted
+    #
+    # Please consider these limitations when you choose to use the `:set`
+    # option with the attribute macros.
+    #
+    # # Validations
+    #
+    # It's important to validate models before there are persisted to keep
+    # your data clean.  AWS::Record supports most of the ActiveRecord style
+    # validators.
+    #
+    #     class Book < AWS::Record::Model
+    #       string_attr :title
+    #       validates_presence_of :title
+    #     end
+    #
+    #     b = Book.new
+    #     b.valid? #=> false
+    #     b.errors.full_messages #=> ['Title may not be blank']
+    #
+    # Validations are checked before saving a record.  If any of the validators
+    # adds an error, the the save will fail.
+    #
+    # For more information about the available validation methods see
+    # {Validations}.
+    #
+    # # Finder Methods
+    #
+    # You can find records by their ID.  Each record gets a UUID when it
+    # is saved for the first time.  You can use this ID to fetch the record
+    # at a latter time:
+    #
+    #     b = Book["0aa894ca-8223-4d34-831e-e5134b2bb71c"]
+    #
+    #     b = Book.find("0aa894ca-8223-4d34-831e-e5134b2bb71c")
+    #
+    # If you try to find a record by ID that has no data an error will
+    # be raised.
+    #
+    # ### All
+    #
+    # You can enumerate all of your records using `all`.
+    #
+    #     Book.all.each do |book|
+    #       puts book.id
+    #     end
+    #
+    #     Book.find(:all) do |book|
+    #       puts book.id
+    #     end
+    #
+    # Be careful when enumerating all.  Depending on the number of records
+    # and number of attributes each record has, this can take a while,
+    # causing quite a few requests.
+    #
+    # ### First
+    #
+    # If you only want a single record, you should use `first`.
+    #
+    #     b = Book.first
+    #
+    # ### Modifiers
+    #
+    # Frequently you do not want ALL records or the very first record.  You
+    # can pass options to `find`, `all` and `first`.
+    #
+    #     my_books = Book.find(:all, :where => 'owner = "Me"')
+    #
+    #     book = Book.first(:where => { :has_been_read => false })
+    #
+    # You can pass as find options:
+    #
+    # * `:where` - Conditions that must be met to be returned
+    # * `:order` - The order to sort matched records by
+    # * `:limit` - The maximum number of records to return
+    #
+    # # Scopes
+    #
+    # More useful than writing query fragments all over the place is to
+    # name your most common conditions for reuse.
+    #
+    #     class Book < AWS::Record::Model
+    #
+    #       scope :mine, where(:owner => 'Me')
+    #
+    #       scope :unread, where(:has_been_read => false)
+    #
+    #       scope :by_popularity, order(:score, :desc)
+    #
+    #       scope :top_10, by_popularity.limit(10)
+    #
+    #     end
+    #
+    #     # The following expression returns 10 books that belong
+    #     # to me, that are unread sorted by popularity.
+    #     next_good_reads = Book.mine.unread.top_10
+    #
+    # There are 3 standard scope methods:
+    #
+    # * `where`
+    # * `order`
+    # * `limit`
+    #
+    # ### Conditions (where)
+    #
+    # Where accepts aruments in a number of forms:
+    #
+    # 1. As an sql-like fragment. If you need to escape values this form is
+    #    not suggested.
+    #
+    #        Book.where('title = "My Book"')
+    #
+    # 2. An sql-like fragment, with placeholders.  This escapes quoted
+    #    arguments properly to avoid injection.
+    #
+    #        Book.where('title = ?', 'My Book')
+    #
+    # 3. A hash of key-value pairs. This is the simplest form, but also the
+    #    least flexible.  You can not use this form if you need more complex
+    #    expressions that use or.
+    #
+    #        Book.where(:title => 'My Book')
+    #
+    # ### Order
+    #
+    # This orders the records as returned by AWS.  Default ordering is ascending.
+    # Pass the value :desc as a second argument to sort in reverse ordering.
+    #
+    #     Book.order(:title)        # alphabetical ordering
+    #     Book.order(:title, :desc) # reverse alphabetical ordering
+    #
+    # You may only order by a single attribute. If you call order twice in the
+    # chain, the last call gets presedence:
+    #
+    #     Book.order(:title).order(:price)
+    #
+    # In this example the books will be ordered by :price and the order(:title)
+    # is lost.
+    #
+    # ### Limit
+    #
+    # Just call `limit` with an integer argument.  This sets the maximum
+    # number of records to retrieve:
+    #
+    #     Book.limit(2)
+    #
+    # ### Delayed Execution
+    #
+    # It should be noted that all finds are lazy (except `first`).  This
+    # means the value returned is not an array of records, rather a handle
+    # to a {Scope} object that will return records when you enumerate over them.
+    #
+    # This allows you to build an expression without making unecessary requests.
+    # In the following example no request is made until the call to
+    # each_with_index.
+    #
+    #     all_books = Books.all
+    #     ten_books = all_books.limit(10)
+    #
+    #     ten_books.each_with_index do |book,n|
+    #       puts "#{n + 1} : #{book.title}"
+    #     end
+    #
+    class Model
+
+      require 'aws/record/model/attributes'
+      require 'aws/record/model/finder_methods'
+      require 'aws/record/model/scope'
+
+      extend AbstractBase
+
+      # The id for each record is auto-generated.  The default strategy
+      # generates uuid strings.
+      # @return [String] Returns the id string (uuid) for this record.  Retuns
+      #   nil if this is a new record that has not been persisted yet.
+      def id
+        @_id
+      end
+
+      # @return [Hash] A hash with attribute names as hash keys (strings) and
+      #   attribute values (of mixed types) as hash values.
+      def attributes
+        attributes = super
+        attributes['id'] = id if persisted?
+        attributes
+      end
+
+      class << self
+
+        # Creates the SimpleDB domain that is configured for this class.
+        #
+        #     class Product < AWS::Record::Model
+        #     end
+        #
+        #     Product.create_table #=> 'Product'
+        #
+        # If you share a single AWS account with multiple applications, you
+        # can provide a domain prefix for your model classes.
+        #
+        #     AWS::Record.domain_prefix = 'myapp-'
+        #
+        #     Product.create_table #=> 'myapp-Product'
+        #
+        # If you have set a model shard name, this is used in place of the
+        # class name.
+        #
+        #     AWS::Record.domain_prefix = 'prod-'
+        #     class Product < AWS::Record::Model
+        #       set_shard_name 'products'
+        #     end
+        #
+        #     Product.create_table #=> 'prod-products'
+        #
+        # If you shard you data across multiple domains, you can specify the
+        # shard name:
+        #
+        #     # create two domains, with the given names
+        #     Product.create_domain 'products-1'
+        #     Product.create_domain 'products-2'
+        #
+        # @param [optional,String] shard_name Defaults to the class name.
+        #
+        # @return [SimpleDB::Domain]
+        #
+        def create_domain shard_name = nil
+          sdb.domains.create(sdb_domain_name(shard_name))
+        end
+
+        # @return [AWS::SimpleDB::Domain]
+        # @api private
+        def sdb_domain shard_name = nil
+          sdb.domains[sdb_domain_name(shard_name)]
+        end
+
+        protected
+        def sdb_domain_name shard_name = nil
+          "#{AWS::Record.domain_prefix}#{self.shard_name(shard_name)}"
+        end
+
+        protected
+        def sdb
+          AWS::SimpleDB.new
+        end
+
+      end
+
+      # @return [SimpleDB::Item] Returns a reference to the item as stored in
+      #   simple db.
+      # @api private
+      private
+      def sdb_item
+        sdb_domain.items[id]
+      end
+
+      # @return [SimpleDB::Domain] Returns the domain this record is
+      #   persisted to or will be persisted to.
+      private
+      def sdb_domain
+        self.class.sdb_domain(shard)
+      end
+
+      # This function accepts a hash of item data (as returned from
+      # AttributeCollection#to_h or ItemData#attributes) and returns only
+      # the key/value pairs that are configured attribues for this class.
+      # @api private
+      private
+      def deserialize_item_data item_data
+
+        marked_for_deletion = item_data['_delete_'] || []
+
+        data = {}
+        item_data.each_pair do |attr_name,values|
+
+          attribute = self.class.attributes[attr_name]
+
+          next unless attribute
+          next if marked_for_deletion.include?(attr_name)
+
+          if attribute.set?
+            data[attr_name] = values.map{|v| attribute.deserialize(v) }
+          else
+            data[attr_name] = attribute.deserialize(values.first)
+          end
+
+        end
+        data
+      end
+
+      def hydrate(id, data)
+        @_id = id
+        super
+      end
+
+      # @api private
+      def populate_id
+        @_id = SecureRandom.uuid
+      end
+
+      # @api private
+      protected
+      def create_storage
+        to_add = serialize_attributes
+        sdb_item.attributes.add(to_add.merge(opt_lock_conditions))
+      end
+
+      # @api private
+      private
+      def update_storage
+
+        to_update = {}
+        to_delete = []
+
+        # serialized_attributes will raise error if the entire record is blank
+        attribute_values = serialize_attributes
+
+        changed.each do |attr_name|
+          if values = attribute_values[attr_name]
+            to_update[attr_name] = values
+          else
+            to_delete << attr_name
+          end
+        end
+
+        to_update.merge!(opt_lock_conditions)
+
+        if to_delete.empty?
+          sdb_item.attributes.replace(to_update)
+        else
+          sdb_item.attributes.replace(to_update.merge('_delete_' => to_delete))
+          sdb_item.attributes.delete(to_delete + ['_delete_'])
+        end
+
+      end
+
+      # @return [true]
+      # @api private
+      private
+      def delete_storage
+        sdb_item.delete(opt_lock_conditions)
+        @_deleted = true
+      end
+
+    end
+
+    # for backwards compatability with the old AWS::Record::Base
+    Base = Model
+
+  end
+end