aws-sdk 1.2.6 → 1.3.0

data/lib/aws/record/model.rb

@@ -0,0 +1,429 @@
+# 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.
+
+# todo move these to included modules (like validations and naming)
+
+require 'aws/record/abstract_base'
+require 'aws/record/model/scope'
+require 'aws/record/model/attributes'
+require 'aws/record/model/finder_methods'
+
+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 :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+
+    #
+    # For more information about the various attribute macros available, 
+    # and what options they accept, see {AttributeMacros}.
+    #
+    # === 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, :deafult_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
+
+      extend AbstractBase
+
+      class << self
+
+        # Creates the SimpleDB domain that is configured for this class.
+        #
+        #   class Product < AWS::Record::Model
+        #   end
+        #
+        #   Product.create_table #=> creates the SimpleDB domain 'Product'
+        #
+        # If you shard you data across multiple domains, you can specify the
+        # shard name:
+        #
+        #   # create two domains, with the given names
+        #   Product.create_domain :shard_name => 'products-1'
+        #   Product.create_domain :shard_name => 'products-2'
+        #
+        # If you share a single AWS account with multiple applications, you
+        # can provide a domain prefix to group domains and to avoid name
+        # collisions:
+        #
+        #   AWS::Record.domain_prefix = 'myapp-'
+        #
+        #   # creates the domain 'myapp-Product'
+        #   Product.create_domain
+        #
+        #   # creates the domain 'myapp-products-1'
+        #   Product.create_domain :shard_name => 'products-1'
+        #
+        # @param [Hash] options Hash of options passed to 
+        #   {SimpleDB::DomainCollection#create}.  
+        #
+        # @option options [String] :shard_name Defaults to the class name.  The
+        #   shard name will be prefixed with {AWS::Record.domain_prefix},
+        #   and that becomes the domain name.
+        #
+        # @return [SimpleDB::Domain]
+        #
+        def create_domain shard_name = nil
+          sdb.domains.create(sdb_domain_name(shard_name))
+        end
+
+        # @return [AWS::SimpleDB::Domain]
+        # @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.
+      # @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.
+      # @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
+
+      # @private
+      protected
+      def create_storage
+        to_add = serialize_attributes
+        sdb_item.attributes.add(to_add.merge(opt_lock_conditions))
+      end
+
+      # @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]
+      # @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

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

@@ -0,0 +1,377 @@
+# 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 Model
+
+      module Attributes
+
+        class BooleanAttr < Record::Attributes::BooleanAttr
+          def self.serialize boolean, options = {}
+            super.to_s
+          end
+        end
+
+        class IntegerAttr < Record::Attributes::IntegerAttr
+          def self.serialize integer, options = {}
+            super.to_s
+          end
+        end
+
+        class FloatAttr < Record::Attributes::FloatAttr
+          def self.serialize float, options = {}
+            super.to_s
+          end
+        end
+
+        class SortableIntegerAttr < IntegerAttr
+
+          def initialize name, options = {}
+            range = options[:range]
+            raise ArgumentError, "missing required option :range" unless range
+            raise ArgumentError, ":range should be a integer range" unless
+              range.is_a?(Range) and range.first.is_a?(Integer)
+            super(name, options)
+          end
+          
+          # Returns a serialized representation of the integer value suitable for
+          # storing in SimpleDB.
+          #
+          #   attribute.serialize(123)
+          #   #=> '123'
+          #
+          #   # padded to the correct number of digits
+          #   attribute.serialize('123', :range => (0..10_000)
+          #   #=> '00123'
+          #
+          #   # offset applied to make all values positive
+          #   attribute.serialize('-55', :range => (-100..10_000)
+          #   #=> '00045'
+          #
+          # @param [Integer] integer The number to serialize.
+          # @param [Hash] options
+          # @option options [required,Range] :range A range that represents the 
+          #   minimum and maximum values this integer can be.
+          #   The returned value will have an offset applied (if min is
+          #   less than 0) and will be zero padded.
+          # @return [String] A serialized representation of the integer.
+          def self.serialize integer, options = {}
+            expect(Integer, integer) do
+              check_range(integer, options)
+              offset_and_precision(options) do |offset,precision|
+                "%0#{precision}d" % (integer.to_i + offset)
+              end
+            end
+          end
+
+          def self.deserialize string_value, options = {}
+            offset_and_precision(options) do |offset,precision|
+              string_value.to_i - offset
+            end
+          end
+
+          protected
+          def self.offset_and_precision options, &block
+
+            min = options[:range].first
+            max = options[:range].last
+
+            offset = min < 0 ? min * -1 : 0
+            precision = (max + offset).to_s.length
+
+            yield(offset, precision)
+
+          end
+
+          def self.check_range number, options
+            unless options[:range].include?(number)
+              msg = "unable to serialize `#{number}`, falls outside " +
+               "the range #{options[:range]}"
+              raise msg
+            end
+          end
+
+        end
+
+        class SortableFloatAttr < FloatAttr
+
+          def initialize name, options = {}
+            range = options[:range]
+            raise ArgumentError, "missing required option :range" unless range
+            raise ArgumentError, ":range should be an integer range" unless
+              range.is_a?(Range) and range.first.is_a?(Integer)
+            super(name, options)
+          end
+
+          def self.serialize float, options = {}
+            expect(Float, float) do 
+              left, right = float.to_s.split('.')
+              left = SortableIntegerAttr.serialize(left.to_i, options)
+              SortableIntegerAttr.check_range(float, options)
+              "#{left}.#{right}"
+            end
+          end
+
+          def self.deserialize string_value, options = {}
+            left, right = float.to_s.split('.')
+            left = SortableIntegerAttr.deserialize(left, options)
+            "#{left}.#{right}".to_f
+          end
+
+        end
+
+      end
+
+      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(Record::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 sortable integer attribute to this class.
+        #
+        #   class Person < AWS::Record::Model
+        #     sortable_integer_attr :age, :range => 0..150
+        #   end
+        #
+        #   person = Person.new(:age => 10)
+        #   person.age #=> 10
+        #
+        # === Validations
+        # 
+        # It is recomended to apply a validates_numericality_of with
+        # minimum and maximum value constraints.  If a value is assigned
+        # to a sortable integer that falls outside of the +:range: it will
+        # raise a runtime error when the record is saved.
+        #
+        # === Difference Between Sortable an Regular Integer Attributes
+        #
+        # Because SimpleDB does not support numeric types, all values must
+        # be converted to strings.  This complicates sorting by numeric values.
+        # To accomplish sorting numeric attributes the values must be
+        # zero padded and have an offset applied to eliminate negative values.
+        #
+        # @param [Symbol] name The name of the attribute.
+        # @param [Hash] options
+        # @option options [Range] :range A numeric range the represents the
+        #   minimum and  maximum values this attribute should accept.
+        # @option options [Boolean] :set (false) When true this attribute
+        #   can have multiple values.
+        def sortable_integer_attr name, options = {}
+          add_attribute(Attributes::SortableIntegerAttr.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 sortable float attribute to this class.
+        #
+        # Persisted values are stored (and sorted) as strings.  This makes it
+        # more difficult to sort numbers because they don't sort 
+        # lexicographically unless they have been offset to be positive and
+        # then zero padded.
+        #
+        # === Postive Floats
+        #
+        # To store floats in a sort-friendly manor:
+        #
+        #   sortable_float_attr :score, :range => (0..10)
+        #
+        # This will cause values like 5.5 to persist as a string like '05.5' so 
+        # that they can be sorted lexicographically.
+        #
+        # === Negative Floats
+        #
+        # If you need to store negative sortable floats, increase your +:range+
+        # to include a negative value.
+        #
+        #   sortable_float_attr :position, :range => (-10..10)
+        #
+        # AWS::Record will add 10 to all values and zero pad them 
+        # (e.g. -10.0 will be represented as '00.0' and 10 will be represented as 
+        # '20.0').  This will allow the values to be compared lexicographically.
+        #
+        # @note If you change the +:range+ after some values have been persisted
+        #   you must also manually migrate all of the old values to have the
+        #   correct padding & offset or they will be interpreted differently.
+        #
+        # @param [Symbol] name The name of the attribute.
+        # @param [Hash] options
+        # @option options [Range] :range The range of numbers this attribute
+        #   should represent.  The min and max values of this range will determine
+        #   how many digits of precision are required and how much of an offset
+        #   is required to make the numbers sort lexicographically.
+        # @option options [Boolean] :set (false) When true this attribute
+        #   can have multiple values.
+        def sortable_float_attr name, options = {}
+          add_attribute(Attributes::SortableFloatAttr.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(Record::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(Record::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