aws-sdk-v1 1.52.0

data/lib/aws/record/attributes.rb

@@ -0,0 +1,388 @@
+# 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.
+
+require 'date'
+
+module AWS
+  module Record
+      module Attributes
+
+      # Base class for all of the AWS::Record attributes.
+      class BaseAttr
+
+        # @param [Symbol] name Name of this attribute.  It should be a name that
+        #   is safe to use as a method.
+        # @param [Hash] options
+        # @option options [String] :persist_as Defaults to the name of the
+        #   attribute.  You can pass a string to specify what the attribute
+        #   will be named in the backend storage.
+        # @option options [Boolean] :set (false) When true this attribute can
+        #   accept multiple unique values.
+        def initialize name, options = {}
+          @name = name.to_s
+          @options = options.dup
+          if options[:set] and !self.class.allow_set?
+            raise ArgumentError, "invalid option :set for #{self.class}"
+          end
+        end
+
+        # @return [String] The name of this attribute
+        attr_reader :name
+
+        # @return [Hash] Attribute options passed to the constructor.
+        attr_reader :options
+
+        # @return [Boolean] Returns true if this attribute can have
+        #   multiple values.
+        def set?
+          options[:set] ? true : false
+        end
+
+        # @return Returns the default value for this attribute.
+        def default_value
+          if options[:default_value].is_a?(Proc)
+            options[:default_value].call
+          else
+            options[:default_value]
+          end
+        end
+
+        # @return [String] Returns the name this attribute will use
+        #   in the storage backend.
+        def persist_as
+          (options[:persist_as] || @name).to_s
+        end
+
+        # @param [Mixed] raw_value A single value to type cast.
+        # @return [Mixed] Returns the type casted value.
+        def type_cast raw_value
+          self.class.type_cast(raw_value, options)
+        end
+
+        # @param [String] serialized_value The serialized string value.
+        # @return [Mixed] Returns a deserialized type-casted value.
+        def deserialize serialized_value
+          self.class.deserialize(serialized_value, options)
+        end
+
+        # Takes the type casted value and serializes it
+        # @param [Mixed] type_casted_value A single value to serialize.
+        # @return [Mixed] Returns the serialized value.
+        def serialize type_casted_value
+          self.class.serialize(type_casted_value, options)
+        end
+
+        # @param [String] serialized_value The raw value returned from AWS.
+        # @return [Mixed] Returns the type-casted deserialized value.
+        def self.deserialize serialized_value, options = {}
+          self.type_cast(serialized_value, options)
+        end
+
+        # @return [Boolean] Returns true if this attribute type can be used
+        #   with the `:set => true` option.  Certain attirbutes can not
+        #   be represented with multiple values (like BooleanAttr).
+        def self.allow_set?
+          raise NotImplementedError
+        end
+
+        # @api private
+        protected
+        def self.expect klass, value, &block
+          unless value.is_a?(klass)
+            raise ArgumentError, "expected a #{klass}, got #{value.class}"
+          end
+          yield if block_given?
+        end
+
+      end
+
+      class StringAttr < BaseAttr
+
+        # Returns the value cast to a string.  Empty strings are returned as
+        # nil by default.  Type casting is done by calling #to_s on the value.
+        #
+        #     string_attr.type_cast(123)
+        #     # => '123'
+        #
+        #     string_attr.type_cast('')
+        #     # => nil
+        #
+        #     string_attr.type_cast('', :preserve_empty_strings => true)
+        #     # => ''
+        #
+        # @param [Mixed] raw_value
+        # @param [Hash] options
+        # @option options [Boolean] :preserve_empty_strings (false) When true,
+        #   empty strings are preserved and not cast to nil.
+        # @return [String,nil] The type casted value.
+        def self.type_cast raw_value, options = {}
+          case raw_value
+          when nil     then nil
+          when ''      then options[:preserve_empty_strings] ? '' : nil
+          when String  then raw_value
+          else raw_value.to_s
+          end
+        end
+
+        # Returns a serialized representation of the string value suitable for
+        # storing in SimpleDB.
+        # @param [String] string
+        # @param [Hash] options
+        # @return [String] The serialized string.
+        def self.serialize string, options = {}
+          unless string.is_a?(String)
+            msg = "expected a String value, got #{string.class}"
+            raise ArgumentError, msg
+          end
+          string
+        end
+
+        # @api private
+        def self.allow_set?
+          true
+        end
+
+      end
+
+      class BooleanAttr < BaseAttr
+
+        def self.type_cast raw_value, options = {}
+          case raw_value
+          when nil then nil
+          when '' then nil
+          when false, 'false', '0', 0 then false
+          else true
+          end
+        end
+
+        def self.serialize boolean, options = {}
+          case boolean
+          when false then 0
+          when true  then 1
+          else
+            msg = "expected a boolean value, got #{boolean.class}"
+            raise ArgumentError, msg
+          end
+        end
+
+        # @api private
+        def self.allow_set?
+          false
+        end
+
+      end
+
+      class IntegerAttr < BaseAttr
+
+        # Returns value cast to an integer.  Empty strings are cast to
+        # nil by default.  Type casting is done by calling #to_i on the value.
+        #
+        #     int_attribute.type_cast('123')
+        #     #=> 123
+        #
+        #     int_attribute.type_cast('')
+        #     #=> nil
+        #
+        # @param [Mixed] raw_value The value to type cast to an integer.
+        # @return [Integer,nil] Returns the type casted integer or nil
+        def self.type_cast raw_value, options = {}
+          case raw_value
+          when nil      then nil
+          when ''       then nil
+          when Integer  then raw_value
+          else
+            raw_value.respond_to?(:to_i) ?
+              raw_value.to_i :
+              raw_value.to_s.to_i
+          end
+        end
+
+        # Returns a serialized representation of the integer value suitable for
+        # storing in SimpleDB.
+        #
+        #     attribute.serialize(123)
+        #     #=> '123'
+        #
+        # @param [Integer] integer The number to serialize.
+        # @param [Hash] options
+        # @return [String] A serialized representation of the integer.
+        def self.serialize integer, options = {}
+          expect(Integer, integer) { integer }
+        end
+
+        # @api private
+        def self.allow_set?
+          true
+        end
+
+      end
+
+      class FloatAttr < BaseAttr
+
+        def self.type_cast raw_value, options = {}
+          case raw_value
+          when nil   then nil
+          when ''    then nil
+          when Float then raw_value
+          else
+            raw_value.respond_to?(:to_f) ?
+              raw_value.to_f :
+              raw_value.to_s.to_f
+          end
+        end
+
+        def self.serialize float, options = {}
+          expect(Float, float) { float }
+        end
+
+        # @api private
+        def self.allow_set?
+          true
+        end
+
+      end
+
+      class DateAttr < BaseAttr
+
+        # Returns value cast to a Date object.  Empty strings are cast to
+        # nil.  Values are cast first to strings and then passed to
+        # Date.parse.  Integers are treated as timestamps.
+        #
+        #     date_attribute.type_cast('2000-01-02T10:11:12Z')
+        #     #=> #<Date: 4903091/2,0,2299161>
+        #
+        #     date_attribute.type_cast(1306170146)
+        #     #<Date: 4911409/2,0,2299161>
+        #
+        #     date_attribute.type_cast('')
+        #     #=> nil
+        #
+        #     date_attribute.type_cast(nil)
+        #     #=> nil
+        #
+        # @param [Mixed] raw_value The value to cast to a Date object.
+        # @param [Hash] options
+        # @return [Date,nil]
+        def self.type_cast raw_value, options = {}
+          case raw_value
+          when nil      then nil
+          when ''       then nil
+          when Date     then raw_value
+          when Integer  then
+            begin
+              Date.parse(Time.at(raw_value).to_s) # assumed timestamp
+            rescue
+              nil
+            end
+          else
+            begin
+              Date.parse(raw_value.to_s) # Time, DateTime or String
+            rescue
+              nil
+            end
+          end
+        end
+
+        # Returns a Date object encoded as a string (suitable for sorting).
+        #
+        #     attribute.serialize(DateTime.parse('2001-01-01'))
+        #     #=> '2001-01-01'
+        #
+        # @param [Date] date The date to serialize.
+        #
+        # @param [Hash] options
+        #
+        # @return [String] Returns the date object serialized to a string
+        #   ('YYYY-MM-DD').
+        #
+        def self.serialize date, options = {}
+          unless date.is_a?(Date)
+            raise ArgumentError, "expected a Date value, got #{date.class}"
+          end
+          date.strftime('%Y-%m-%d')
+        end
+
+        # @api private
+        def self.allow_set?
+          true
+        end
+
+      end
+
+      class DateTimeAttr < BaseAttr
+
+        # Returns value cast to a DateTime object.  Empty strings are cast to
+        # nil.  Values are cast first to strings and then passed to
+        # DateTime.parse.  Integers are treated as timestamps.
+        #
+        #     datetime_attribute.type_cast('2000-01-02')
+        #     #=> #<DateTime: 4903091/2,0,2299161>
+        #
+        #     datetime_attribute.type_cast(1306170146)
+        #     #<DateTime: 106086465073/43200,-7/24,2299161>
+        #
+        #     datetime_attribute.type_cast('')
+        #     #=> nil
+        #
+        #     datetime_attribute.type_cast(nil)
+        #     #=> nil
+        #
+        # @param [Mixed] raw_value The value to cast to a DateTime object.
+        # @param [Hash] options
+        # @return [DateTime,nil]
+        def self.type_cast raw_value, options = {}
+          case raw_value
+          when nil      then nil
+          when ''       then nil
+          when DateTime then raw_value
+          when Integer  then
+            begin
+              DateTime.parse(Time.at(raw_value).to_s) # timestamp
+            rescue
+              nil
+            end
+          else
+            begin
+              DateTime.parse(raw_value.to_s) # Time, Date or String
+            rescue
+              nil
+            end
+          end
+        end
+
+        # Returns a DateTime object encoded as a string (suitable for sorting).
+        #
+        #     attribute.serialize(DateTime.parse('2001-01-01'))
+        #     #=> '2001-01-01T00:00:00:Z)
+        #
+        # @param [DateTime] datetime The datetime object to serialize.
+        # @param [Hash] options
+        # @return [String] Returns the datetime object serialized to a string
+        #   in ISO8601 format (e.g. '2011-01-02T10:11:12Z')
+        def self.serialize datetime, options = {}
+          unless datetime.is_a?(DateTime)
+            msg = "expected a DateTime value, got #{datetime.class}"
+            raise ArgumentError, msg
+          end
+          datetime.strftime('%Y-%m-%dT%H:%M:%S%Z')
+        end
+
+        # @api private
+        def self.allow_set?
+          true
+        end
+
+      end
+    end
+  end
+end

data/lib/aws/record/conversion.rb

@@ -0,0 +1,38 @@
+# 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
+
+    # @api private
+    module Conversion
+
+      # @api private
+      def to_model
+        self
+      end
+
+      # @api private
+      def to_key
+        persisted? ? [id] : nil
+      end
+
+      # @api private
+      def to_param
+        persisted? ? to_key.join('-') : nil
+      end
+
+    end
+
+  end
+end

data/lib/aws/record/dirty_tracking.rb

@@ -0,0 +1,287 @@
+# 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
+
+    # Provides a way to track changes in your records.
+    #
+    #     my_book = Book['bookid']
+    #
+    #     my_book.changed? #=> false
+    #     my_book.title #=> "My Book"
+    #     my_book.title = "My Awesome Book"
+    #     my_book.changed? #=> true
+    #
+    #     my_book = Book['bookid']
+    #
+    # You can inspect further and get a list of changed attributes
+    #
+    #     my_book.changed #=> ['title']
+    #
+    # Or you can get a more detailed description of the changes.  {#changes}
+    # returns a hash of changed attributes (keys) with their old and new
+    # values.
+    #
+    #     my_book.changes
+    #     #=> { 'title' => ['My Book', 'My Awesome Book']
+    #
+    # For every configured attribute you also get a handful of methods
+    # for inspecting changes on that attribute.  Given the following
+    # attribute:
+    #
+    #     string_attr :title
+    #
+    # You can now call any of the following methods:
+    #
+    #   * title_changed?
+    #   * title_change
+    #   * title_was
+    #   * reset_title!
+    #   * title_will_change!
+    #
+    # Given the title change from above:
+    #
+    #     my_book.title_changed? #=> true
+    #     my_book.title_change #=> ['My Book', 'My Awesome Book']
+    #     my_book.title_was #=> ['My Book']
+    #
+    #     my_book.reset_title!
+    #     my_book.title #=> 'My Book'
+    #
+    # ## In-Place Editing
+    #
+    # Dirty tracking works by comparing incoming attribute values upon
+    # assignment against the value that was there previously.  If you
+    # use functions against the value that modify it (like gsub!)
+    # you must notify your record about the coming change.
+    #
+    #     my_book.title #=> 'My Book'
+    #     my_book.title_will_change!
+    #     my_book.title.gsub!(/My/, 'Your')
+    #     my_book.title_change #=> ['My Book', 'Your Book']
+    #
+    # ## Partial Updates
+    #
+    # Dirty tracking makes it possible to only persist those attributes
+    # that have changed since they were loaded.  This speeds up requests
+    # against AWS when saving data.
+    #
+    module DirtyTracking
+
+      # Returns true if this model has unsaved changes.
+      #
+      #     b = Book.new(:title => 'My Book')
+      #     b.changed?
+      #     #=> true
+      #
+      # New objects and objects freshly loaded should not have any changes:
+      #
+      #     b = Book.new
+      #     b.changed?      #=> false
+      #
+      #     b = Book.first
+      #     b.changed?      #=> false
+      #
+      # @return [Boolean] Returns true if any of the attributes have
+      #   unsaved changes.
+      def changed?
+        !orig_values.empty?
+      end
+
+      # Returns an array of attribute names that have changes.
+      #
+      #     book.changed #=> []
+      #     person.title = 'New Title'
+      #     book.changed #=> ['title']
+      #
+      # @return [Array] Returns an array of attribute names that have
+      #   unsaved changes.
+      def changed
+        orig_values.keys
+      end
+
+      # Returns the changed attributes in a hash.  Keys are attribute names,
+      # values are two value arrays.  The first value is the previous
+      # attribute value, the second is the current attribute value.
+      #
+      #     book.title = 'New Title'
+      #     book.changes
+      #     #=> { 'title' => ['Old Title', 'New Title'] }
+      #
+      # @return [Hash] Returns a hash of attribute changes.
+      def changes
+        changed.inject({}) do |changes, attr_name|
+          changes[attr_name] = attribute_change(attr_name)
+          changes
+        end
+      end
+
+      # Returns true if the named attribute has unsaved changes.
+      #
+      # This is an attribute method.  The following two expressions
+      # are equivilent:
+      #
+      #     book.title_changed?
+      #     book.attribute_changed?(:title)
+      #
+      # @param [String] attribute_name Name of the attribute to check
+      #   for changes.
+      #
+      # @return [Boolean] Returns true if the named attribute
+      #   has unsaved changes.
+      # @api private
+      private
+      def attribute_changed? attribute_name
+        orig_values.keys.include?(attribute_name)
+      end
+
+      # Returns an array of the old value and the new value for
+      # attributes that have unsaved changes, returns nil otherwise.
+      #
+      # This is an attribute method.  The following two expressions
+      # are equivilent:
+      #
+      #     book.title_change
+      #     book.attribute_change(:title)
+      #
+      # @example Asking for changes on an unchanged attribute
+      #
+      #   book = Book.new
+      #   book.title_change #=> nil
+      #
+      # @example Getting changed attributes on a new object
+      #
+      #   book = Book.new(:title => 'My Book')
+      #   book.title_change #=> [nil, 'My Book']
+      #
+      # @example Getting changed attributes on a loaded object
+      #
+      #   book = Book.first
+      #   book.title = 'New Title'
+      #   book.title_change #=> ['Old Title', 'New Title']
+      #
+      # @param [String] attribute_name Name of the attribute to fetch
+      #   a change for.
+      # @return [Boolean] Returns true if the named attribute
+      #   has unsaved changes.
+      # @api private
+      private
+      def attribute_change attribute_name
+        self.class.attribute_for(attribute_name) do |attribute|
+          if orig_values.has_key?(attribute.name)
+            [orig_values[attribute.name], __send__(attribute.name)]
+          else
+            nil
+          end
+        end
+      end
+
+      # Returns the previous value for changed attributes, or the current
+      # value for unchanged attributes.
+      #
+      # This is an attribute method.  The following two expressions
+      # are equivilent:
+      #
+      #      book.title_was
+      #      book.attribute_was(:title)
+      #
+      # @example Returns the previous value for changed attributes:
+      #
+      #   book = Book.where(:title => 'My Book').first
+      #   book.title = 'New Title'
+      #   book.title_was #=> 'My Book'
+      #
+      # @example Returns the current value for unchanged attributes:
+      #
+      #   book = Book.where(:title => 'My Book').first
+      #   book.title_was #=> 'My Book'
+      #
+      # @return Returns the previous value for changed attributes
+      #   or the current value for unchanged attributes.
+      # @api private
+      private
+      def attribute_was attribute_name
+        self.class.attribute_for(attribute_name) do |attribute|
+          name = attribute.name
+          orig_values.has_key?(name) ? orig_values[name] : __send__(name)
+        end
+      end
+
+      # Reverts any changes to the attribute, restoring its original value.
+      # @param [String] attribute_name Name of the attribute to reset.
+      # @return [nil]
+      # @api private
+      private
+      def reset_attribute! attribute_name
+        __send__("#{attribute_name}=", attribute_was(attribute_name))
+        nil
+      end
+
+      # Indicate to the record that you are about to edit an attribute
+      # in place.
+      # @param [String] attribute_name Name of the attribute that will
+      #   be changed.
+      # @return [nil]
+      # @api private
+      private
+      def attribute_will_change! attribute_name
+        self.class.attribute_for(attribute_name) do |attribute|
+          name = attribute.name
+          unless orig_values.has_key?(name)
+            was = __send__(name)
+            begin
+              # booleans, nil, etc all #respond_to?(:clone), but they raise
+              # a TypeError when you attempt to dup them.
+              orig_values[name] = was.clone
+            rescue TypeError
+              orig_values[name] = was
+            end
+          end
+        end
+        nil
+      end
+
+      private
+      def orig_values
+        @_orig_values ||= {}
+      end
+
+      private
+      def clear_change! attribute_name
+        orig_values.delete(attribute_name)
+      end
+
+      private
+      def ignore_changes &block
+        begin
+          @_ignore_changes = true
+          yield
+        ensure
+          @_ignore_changes = false
+        end
+      end
+
+      private
+      def if_tracking_changes &block
+        yield unless @_ignore_changes
+      end
+
+      private
+      def clear_changes!
+        orig_values.clear
+      end
+
+    end
+  end
+end