aws-sdk 1.51.0 → 1.52.0

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

@@ -1,172 +0,0 @@
-# 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

@@ -1,108 +0,0 @@
-# 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

@@ -1,453 +0,0 @@
-# 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