aws-record 1.0.0.pre.8 → 1.0.0.pre.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 529b219269ff7db06904ac8069cd9d03c5a39b2f
-  data.tar.gz: de636bcd9279040598617f1cad6b9601f583a4fc
+  metadata.gz: e20ddd5caa633c5ac1a7acb5e0e6cacfeed52595
+  data.tar.gz: 7317f916341e270b2418d54753a7c0d20540cd7f
 SHA512:
-  metadata.gz: 0466dcde49ea6a9f0a026b806fba07f3e4152d7d115c8c6f89bcf1955903cd92ada636e51b72c161a8cb3f14178948514bf1e5bc11aa72995541f69559b81255
-  data.tar.gz: be394920aba460d6f28d1087077a13f17e25c4f07eb93f24e4ccdf1a7abb222f8d946db3766e6817966659c524d0e550a9273b95be657434bee5e82ba088697b
+  metadata.gz: be783b2361e461595023f044f6147d0bf6935c5a15bbfa585d9cf97b92f63faad4c4d585da6827ec4a93dc1e8581c8e1c7774a400463236695554647a6edb5b0
+  data.tar.gz: 6c22f85ad6a3ca6455d0ac8d04de0bc8849605818605130a430ee7789c47f9088d219f4d363790e6dc3224fc4b22c352b0447b4e61e4be141af7a8295a7f972a

data/lib/aws-record.rb

@@ -28,17 +28,17 @@ module Aws
     autoload :TableMigration,   'aws-record/record/table_migration'
     autoload :VERSION,          'aws-record/record/version'
 
-    module Attributes
-      autoload :StringMarshaler,    'aws-record/record/attributes/string_marshaler'
-      autoload :BooleanMarshaler,   'aws-record/record/attributes/boolean_marshaler'
-      autoload :IntegerMarshaler,   'aws-record/record/attributes/integer_marshaler'
-      autoload :FloatMarshaler,     'aws-record/record/attributes/float_marshaler'
-      autoload :DateMarshaler,      'aws-record/record/attributes/date_marshaler'
-      autoload :DateTimeMarshaler,  'aws-record/record/attributes/date_time_marshaler'
-      autoload :ListMarshaler,      'aws-record/record/attributes/list_marshaler'
-      autoload :MapMarshaler,       'aws-record/record/attributes/map_marshaler'
-      autoload :StringSetMarshaler, 'aws-record/record/attributes/string_set_marshaler'
-      autoload :NumericSetMarshaler, 'aws-record/record/attributes/numeric_set_marshaler'
+    module Marshalers
+      autoload :StringMarshaler,     'aws-record/record/marshalers/string_marshaler'
+      autoload :BooleanMarshaler,    'aws-record/record/marshalers/boolean_marshaler'
+      autoload :IntegerMarshaler,    'aws-record/record/marshalers/integer_marshaler'
+      autoload :FloatMarshaler,      'aws-record/record/marshalers/float_marshaler'
+      autoload :DateMarshaler,       'aws-record/record/marshalers/date_marshaler'
+      autoload :DateTimeMarshaler,   'aws-record/record/marshalers/date_time_marshaler'
+      autoload :ListMarshaler,       'aws-record/record/marshalers/list_marshaler'
+      autoload :MapMarshaler,        'aws-record/record/marshalers/map_marshaler'
+      autoload :StringSetMarshaler,  'aws-record/record/marshalers/string_set_marshaler'
+      autoload :NumericSetMarshaler, 'aws-record/record/marshalers/numeric_set_marshaler'
     end
 
   end

data/lib/aws-record/record.rb

@@ -50,6 +50,7 @@ module Aws
     #     # Attribute definitions go here...
     #   end
     def self.included(sub_class)
+      @track_mutations = true
       sub_class.send(:extend, RecordClassMethods)
       sub_class.send(:include, Attributes)
       sub_class.send(:include, ItemOperations)
@@ -183,6 +184,26 @@ module Aws
         @dynamodb_client ||= configure_client
       end
 
+      # Turns off mutation tracking for all attributes in the model.
+      def disable_mutation_tracking
+        @track_mutations = false
+      end
+
+      # Turns on mutation tracking for all attributes in the model. Note that
+      # mutation tracking is on by default, so you generally would not need to
+      # call this. It is provided in case there is a need to dynamically turn
+      # this feature on and off, though that would be generally discouraged and
+      # could cause inaccurate mutation tracking at runtime.
+      def enable_mutation_tracking
+        @track_mutations = true
+      end
+
+      # @return [Boolean] true if mutation tracking is enabled at the model
+      # level, false otherwise.
+      def mutation_tracking_enabled?
+        @track_mutations == false ? false : true
+      end
+
       private
       def _user_agent(custom)
         if custom

data/lib/aws-record/record/attribute.rb

@@ -21,7 +21,7 @@ module Aws
     # within the model class and item instances.
     class Attribute
 
-      attr_reader :name, :database_name, :dynamodb_type
+      attr_reader :name, :database_name, :dynamodb_type, :default_value
 
       # @param [Symbol] name Name of the attribute. It should be a name that is
       #  safe to use as a method.
@@ -39,11 +39,27 @@ module Aws
       #   "M", "L". Optional if this attribute will never be used for a key or
       #   secondary index, but most convenience methods for setting attributes
       #   will provide this.
+      # @option options [Boolean] :mutation_tracking Optional attribute used to
+      #   indicate whether mutations to values should be explicitly tracked when
+      #   determining if a value is "dirty". Important for collection types
+      #   which are often primarily modified by mutation of a single object
+      #   reference. By default, is false.
+      # @option options [Boolean] :persist_nil Optional attribute used to
+      #   indicate whether nil values should be persisted. If true, explicitly
+      #   set nil values will be saved to DynamoDB as a "null" type. If false,
+      #   nil values will be ignored and not persisted. By default, is false.
+      # @option options [Object] :default_value Optional attribute used to
+      #   define a "default value" to be used if the attribute's value on an
+      #   item is nil or not set at persistence time.
       def initialize(name, options = {})
         @name = name
         @database_name = options[:database_attribute_name] || name.to_s
         @dynamodb_type = options[:dynamodb_type]
         @marshaler = options[:marshaler] || DefaultMarshaler
+        @mutation_tracking = options[:mutation_tracking]
+        @persist_nil = options[:persist_nil]
+        dv = options[:default_value]
+        @default_value = type_cast(dv) unless dv.nil?
       end
 
       # Attempts to type cast a raw value into the attribute's type. This call
@@ -52,7 +68,9 @@ module Aws
       # @return [Object] the type cast object. Return type is dependent on the
       #  marshaler used. See your attribute's marshaler class for details.
       def type_cast(raw_value)
-        @marshaler.type_cast(raw_value)
+        cast_value = @marshaler.type_cast(raw_value)
+        cast_value = default_value if cast_value.nil?
+        cast_value
       end
 
       # Attempts to serialize a raw value into the attribute's serialized
@@ -62,7 +80,21 @@ module Aws
       # @return [Object] the serialized object. Return type is dependent on the
       #  marshaler used. See your attribute's marshaler class for details.
       def serialize(raw_value)
-        @marshaler.serialize(raw_value)
+        cast_value = type_cast(raw_value)
+        cast_value = default_value if cast_value.nil?
+        @marshaler.serialize(cast_value)
+      end
+
+      # @return [Boolean] true if this attribute should do active mutation
+      #  tracking, false otherwise. Default: false
+      def track_mutations?
+        @mutation_tracking ? true : false
+      end
+
+      # @return [Boolean] true if this attribute will actively persist nil
+      #   values, false otherwise. Default: false
+      def persist_nil?
+        @persist_nil ? true : false
       end
 
       # @api private

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

@@ -87,6 +87,18 @@ module Aws
         #   "M", "L". Optional if this attribute will never be used for a key or
         #   secondary index, but most convenience methods for setting attributes
         #   will provide this.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate whether mutations to values should be explicitly tracked
+        #   when determining if a value is "dirty". Important for collection
+        #   types which are often primarily modified by mutation of a single
+        #   object reference. By default, is false.
+        # @option opts [Boolean] :persist_nil Optional attribute used to
+        #   indicate whether nil values should be persisted. If true, explicitly
+        #   set nil values will be saved to DynamoDB as a "null" type. If false,
+        #   nil values will be ignored and not persisted. By default, is false.
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
@@ -118,9 +130,21 @@ module Aws
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
+        # @option opts [Boolean] :persist_nil Optional attribute used to
+        #   indicate whether nil values should be persisted. If true, explicitly
+        #   set nil values will be saved to DynamoDB as a "null" type. If false,
+        #   nil values will be ignored and not persisted. By default, is false.
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         def string_attr(name, opts = {})
           opts[:dynamodb_type] = "S"
-          attr(name, Attributes::StringMarshaler, opts)
+          attr(name, Marshalers::StringMarshaler.new(opts), opts)
         end
 
         # Define a boolean-type attribute for your model.
@@ -132,9 +156,21 @@ module Aws
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
+        # @option opts [Boolean] :persist_nil Optional attribute used to
+        #   indicate whether nil values should be persisted. If true, explicitly
+        #   set nil values will be saved to DynamoDB as a "null" type. If false,
+        #   nil values will be ignored and not persisted. By default, is false.
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         def boolean_attr(name, opts = {})
           opts[:dynamodb_type] = "BOOL"
-          attr(name, Attributes::BooleanMarshaler, opts)
+          attr(name, Marshalers::BooleanMarshaler.new(opts), opts)
         end
 
         # Define a integer-type attribute for your model.
@@ -146,9 +182,21 @@ module Aws
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
+        # @option opts [Boolean] :persist_nil Optional attribute used to
+        #   indicate whether nil values should be persisted. If true, explicitly
+        #   set nil values will be saved to DynamoDB as a "null" type. If false,
+        #   nil values will be ignored and not persisted. By default, is false.
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         def integer_attr(name, opts = {})
           opts[:dynamodb_type] = "N"
-          attr(name, Attributes::IntegerMarshaler, opts)
+          attr(name, Marshalers::IntegerMarshaler.new(opts), opts)
         end
 
         # Define a float-type attribute for your model.
@@ -160,9 +208,21 @@ module Aws
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
+        # @option opts [Boolean] :persist_nil Optional attribute used to
+        #   indicate whether nil values should be persisted. If true, explicitly
+        #   set nil values will be saved to DynamoDB as a "null" type. If false,
+        #   nil values will be ignored and not persisted. By default, is false.
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         def float_attr(name, opts = {})
           opts[:dynamodb_type] = "N"
-          attr(name, Attributes::FloatMarshaler, opts)
+          attr(name, Marshalers::FloatMarshaler.new(opts), opts)
         end
 
         # Define a date-type attribute for your model.
@@ -174,9 +234,21 @@ module Aws
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
+        # @option opts [Boolean] :persist_nil Optional attribute used to
+        #   indicate whether nil values should be persisted. If true, explicitly
+        #   set nil values will be saved to DynamoDB as a "null" type. If false,
+        #   nil values will be ignored and not persisted. By default, is false.
+        # @option options [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         def date_attr(name, opts = {})
           opts[:dynamodb_type] = "S"
-          attr(name, Attributes::DateMarshaler, opts)
+          attr(name, Marshalers::DateMarshaler.new(opts), opts)
         end
 
         # Define a datetime-type attribute for your model.
@@ -188,9 +260,21 @@ module Aws
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
+        # @option opts [Boolean] :persist_nil Optional attribute used to
+        #   indicate whether nil values should be persisted. If true, explicitly
+        #   set nil values will be saved to DynamoDB as a "null" type. If false,
+        #   nil values will be ignored and not persisted. By default, is false.
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         def datetime_attr(name, opts = {})
           opts[:dynamodb_type] = "S"
-          attr(name, Attributes::DateTimeMarshaler, opts)
+          attr(name, Marshalers::DateTimeMarshaler.new(opts), opts)
         end
 
         # Define a list-type attribute for your model.
@@ -216,16 +300,22 @@ module Aws
         # @param [Symbol] name Name of this attribute.  It should be a name that
         #   is safe to use as a method.
         # @param [Hash] opts
-        # @option opts [Boolean] :nil_as_empty_list Set to true if this
-        #   attribute should interpret nil values as an empty list. If false,
-        #   nil values will remain nil.
         # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is true.
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         def list_attr(name, opts = {})
           opts[:dynamodb_type] = "L"
-          attr(name, Attributes::ListMarshaler, opts)
+          opts[:mutation_tracking] = true if opts[:mutation_tracking].nil?
+          attr(name, Marshalers::ListMarshaler.new(opts), opts)
         end
 
         # Define a map-type attribute for your model.
@@ -251,16 +341,22 @@ module Aws
         # @param [Symbol] name Name of this attribute.  It should be a name that
         #   is safe to use as a method.
         # @param [Hash] opts
-        # @option opts [Boolean] :nil_as_empty_map Set to true if this
-        #   attribute should interpret nil values as an empty hash. If false,
-        #   nil values will remain nil.
         # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is true.
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         def map_attr(name, opts = {})
           opts[:dynamodb_type] = "M"
-          attr(name, Attributes::MapMarshaler, opts)
+          opts[:mutation_tracking] = true if opts[:mutation_tracking].nil?
+          attr(name, Marshalers::MapMarshaler.new(opts), opts)
         end
 
         # Define a string set attribute for your model.
@@ -280,9 +376,18 @@ module Aws
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is true.
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         def string_set_attr(name, opts = {})
           opts[:dynamodb_type] = "SS"
-          attr(name, Attributes::StringSetMarshaler, opts)
+          opts[:mutation_tracking] = true if opts[:mutation_tracking].nil?
+          attr(name, Marshalers::StringSetMarshaler.new(opts), opts)
         end
 
         # Define a numeric set attribute for your model.
@@ -302,9 +407,18 @@ module Aws
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option opts [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is true.
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time.
         def numeric_set_attr(name, opts = {})
           opts[:dynamodb_type] = "NS"
-          attr(name, Attributes::NumericSetMarshaler, opts)
+          opts[:mutation_tracking] = true if opts[:mutation_tracking].nil?
+          attr(name, Marshalers::NumericSetMarshaler.new(opts), opts)
         end
 
         # @return [Hash] hash of symbolized attribute names to attribute objects
@@ -333,6 +447,13 @@ module Aws
           @keys
         end
 
+        # @param [Symbol] attr_sym The symbolized name of the attribute.
+        # @return [Boolean] true if object mutations are tracked for dirty
+        #   checking of that attribute, false if mutations are not tracked.
+        def track_mutations?(attr_sym)
+          mutation_tracking_enabled? && attributes[attr_sym].track_mutations?
+        end
+
         private
         def define_attr_methods(name, attribute)
           define_method(name) do

data/lib/aws-record/record/dirty_tracking.rb

@@ -24,6 +24,7 @@ module Aws
       # @override initialize(*)
       def initialize(*)
         @dirty_data = {}
+        @mutation_copies = {}
         super
       end
 
@@ -44,7 +45,7 @@ module Aws
       # @param [String, Symbol] name The name of the attribute to to check for dirty changes.
       # @return [Boolean] +true+ if the specified attribute has any dirty changes, +false+ otherwise.
       def attribute_dirty?(name)
-        @dirty_data.has_key?(name)
+        @dirty_data.has_key?(name) || _mutated?(name)
       end 
 
       # Returns the original value of the specified attribute.
@@ -63,7 +64,11 @@ module Aws
       # @param [String, Symbol] name The name of the attribute to retrieve the original value of.
       # @return [Object] The original value of the specified attribute.
       def attribute_was(name)
-        attribute_dirty?(name) ? @dirty_data[name] : @data[name]
+        if @mutation_copies.has_key?(name)
+          @mutation_copies[name]
+        else
+          attribute_dirty?(name) ? @dirty_data[name] : @data[name]
+        end
       end
 
       # Mark that an attribute is changing. This is useful in situations where it is necessary to track that the value of an 
@@ -107,7 +112,7 @@ module Aws
 
         @dirty_data[name] = 
           begin
-            current_value.clone
+            _deep_copy(current_value)
           rescue TypeError
             current_value
           end
@@ -132,6 +137,13 @@ module Aws
       #
       def clean!
         @dirty_data.clear
+        self.class.attributes.each do |name, attribute|
+          if self.class.track_mutations?(name)
+            if @data[name]
+              @mutation_copies[name] = _deep_copy(@data[name])
+            end
+          end
+        end
       end
 
       # Returns an array with the name of the attributes with dirty changes.
@@ -150,7 +162,13 @@ module Aws
       #
       # @return [Array] The names of attributes with dirty changes.
       def dirty
-        @dirty_data.keys
+        ret = @dirty_data.keys.dup
+        @mutation_copies.each do |key, value|
+          if @data[key] != value
+            ret << key unless ret.include?(key)
+          end
+        end
+        ret
       end
 
       # Returns +true+ if any attributes have dirty changes, +false+ otherwise.
@@ -170,7 +188,10 @@ module Aws
       # @return [Boolean] +true+ if any attributes have dirty changes, +false+ 
       #  otherwise.
       def dirty?
-        @dirty_data.size > 0
+        return true if @dirty_data.size > 0
+        @mutation_copies.any? do |name, value|
+          @mutation_copies[name] != @data[name]
+        end
       end
 
       # Fetches attributes for this instance of an item from Amazon DynamoDB 
@@ -188,7 +209,7 @@ module Aws
 
         record = self.class.find(primary_key)
 
-        unless record.nil? 
+        unless record.nil?
           @data = record.instance_variable_get("@data")
         else
           raise Errors::NotFound.new("No record found")
@@ -217,7 +238,12 @@ module Aws
       def rollback_attribute!(name)
         return unless attribute_dirty?(name)
 
-        @data[name] = @dirty_data.delete(name)
+        if @mutation_copies.has_key?(name)
+          @data[name] = @mutation_copies[name]
+          @dirty_data.delete(name) if @dirty_data.has_key?(name)
+        else
+          @data[name] = @dirty_data.delete(name)
+        end
       end
 
       # Restores all attributes to their original values.
@@ -252,15 +278,29 @@ module Aws
       #
       # @override write_attribute(*)
       def write_attribute(name, attribute, value)
+        _dirty_write_attribute(name, attribute, value)
+        super
+      end
+
+      def _dirty_write_attribute(name, attribute, value)
         if value == attribute_was(name)
           @dirty_data.delete(name)
         else
           attribute_dirty!(name)
         end
+      end
 
-        super
+      def _mutated?(name)
+        if @mutation_copies.has_key?(name)
+          @data[name] != @mutation_copies[name]
+        else
+          false
+        end
       end
 
+      def _deep_copy(obj)
+        Marshal.load(Marshal.dump(obj))
+      end
 
       module DirtyTrackingClassMethods