api_resource 0.6.18 → 0.6.19

data/lib/api_resource/attributes.rb

@@ -1,35 +1,54 @@
 module ApiResource
 
+  #
+  # Error raised when accessing an attribute in an invalid
+  # way such as trying to write to a protected attribute
+  #
+  # @author [ejlangev]
+  #
+  class AttributeAccessError < NoMethodError
+  end
+
   module Attributes
-  
+
     extend ActiveSupport::Concern
+
     include ActiveModel::AttributeMethods
     include ActiveModel::Dirty
-    
+
     included do
 
       # include ApiResource::Typecast if it isn't already
       include ApiResource::Typecast
-      
+
       alias_method_chain :save, :dirty_tracking
-      
+
+      # Set up some class attributes for managing all of
+      # this
       class_attribute(
-        :attribute_names, 
-        :public_attribute_names, 
-        :protected_attribute_names, 
-        :attribute_types
+        :attribute_names,
+        :public_attribute_names,
+        :protected_attribute_names,
+        :attribute_types,
+        :primary_key,
+        :attribute_method_module
       )
-
+      # Initialize those class attributes
       self.attribute_names = []
       self.public_attribute_names = []
       self.protected_attribute_names = []
       self.attribute_types = {}.with_indifferent_access
-      
 
+      self.primary_key = :id
+      self.attribute_method_module = Module.new
+
+      include self.attribute_method_module
       # This method is important for reloading an object. If the
       # object has already been loaded, its associations will trip
       # up the load method unless we pass in the internal objects.
-
+      #
+      # TODO: This seems like kind of a hack that shouldn't be
+      # necessary.  Remove it at some point during the refactoring
       define_method(:attributes_without_proxies) do
         attributes = @attributes
 
@@ -56,160 +75,460 @@ module ApiResource
 
         attributes
       end
-      
+
     end
-    
+
     module ClassMethods
-      
-      def define_attributes(*args)
-        args.each do |arg|
-          self.store_attribute_data(arg, :public)
+      #
+      # Wrapper method to define all of the attributes (public and protected)
+      # for this Class.  This should be called with a locked mutex to
+      # prevent multiple threads from defining attributes at the same time
+      #
+      # @return [Boolean] true
+      def define_all_attributes
+        if self.resource_definition["attributes"]
+          # First we need to clear out the old values and clone them
+          self.attribute_names = []
+          self.public_attribute_names = []
+          self.protected_attribute_names = []
+          self.attribute_types = {}.with_indifferent_access
+          # First define all public attributes
+          define_attributes(
+            *self.resource_definition['attributes']['public'],
+            access_level: :public
+          )
+          # Then define all private attributes
+          define_attributes(
+            *self.resource_definition['attributes']['protected'],
+            access_level: :protected
+          )
         end
-        self.attribute_names.uniq!
-        self.public_attribute_names.uniq!
+        true
       end
-      
-      def define_protected_attributes(*args)
+
+      #
+      # Sets up the attributes for this class, can be called multiple
+      # times to add more attributes.  Again meant to be called with a locked
+      # mutex for thread safety
+      #
+      # @param  *args [Array] List of attributes to define and optional
+      # hash as a last parameter
+      #
+      # @return [Boolean] Always true
+      def define_attributes(*args)
+        options = args.extract_options!
+        options[:access_level] ||= :public
+        # Initialize each attribute
         args.each do |arg|
-          self.store_attribute_data(arg, :protected)
+          self.initialize_attribute(
+            Array.wrap(arg),
+            options[:access_level]
+          )
         end
-        self.attribute_names.uniq!
-        self.protected_attribute_names.uniq!
+
+        self.define_attribute_methods(
+          args,
+          options[:access_level]
+        )
       end
 
-      def define_accessor_methods(meth)
-        # Override the setter for dirty tracking
-        self.class_eval <<-EOE, __FILE__, __LINE__ + 1
-          def #{meth}
-            read_attribute(:#{meth})
-          end
-        
-          def #{meth}=(new_val)
-            write_attribute(:#{meth}, new_val)
+      #
+      # Adds the attribute into some internal data structures but does
+      # not define any methods for it
+      #
+      # @param  arg [Array] A 1 or 2 element array holding an attribute name and
+      # optionally a type for that attribute
+      # @param  access_level [Symbol] Either :protected or :public based on
+      # the access level for this attribute
+      #
+      # @return [Boolean] Always true
+      def initialize_attribute(attr, access_level)
+        attr_name = attr[0].to_sym
+        attr_type = (attr[1] || :unknown).to_sym
+
+        # Look for the typecaster, raise an error if one is not found
+        typecaster = self.typecasters[attr_type]
+        if typecaster.nil?
+          raise TypecasterNotFound, "#{attr_type} is an unknown type"
+        end
+        # Map the attribute name to the typecaster
+        self.attribute_types[attr_name] = typecaster
+        # Add the attribute to the proper list
+        if access_level == :public
+          if self.protected_attribute?(attr_name)
+            raise ArgumentError, "Illegal change of attribute access level for #{attr_name}"
           end
-          
-          def #{meth}?
-            read_attribute(:#{meth}).present?
+
+          self.public_attribute_names << attr_name
+        else
+          if self.public_attribute?(attr_name)
+            raise ArgumentError, "Illegal change of attribute access level for #{attr_name}"
           end
-        EOE
-        # sets up dirty tracking
-        define_attribute_method(meth)
+
+          self.protected_attribute_names << attr_name
+        end
+        self.attribute_names << attr_name
+        true
       end
 
-      def define_attribute_type(field, type)
-        unless self.typecasters.keys.include?(type.to_sym)
-          raise "#{type} is not a valid type" 
+      #
+      # Defines the attribute methods in a new module which
+      # is then included in this class.  Meant to be called with
+      # a locked mutex
+      #
+      # @param  args [Array] List of attributes to define
+      # @param  access_level [Symbol] :protected or :public
+      #
+      # @return [Boolean] Always true
+      def define_attribute_methods(attrs, access_level)
+        self.attribute_method_module.module_eval do
+          attrs.each do |attr|
+            # Normalize for attributes without types
+            attr_name = Array.wrap(attr).first
+            # Define reader and huh methods
+            self.module_eval <<-EOE, __FILE__, __LINE__ + 1
+              def #{attr_name}
+                read_attribute(:#{attr_name})
+              end
+
+              def #{attr_name}?
+                read_attribute(:#{attr_name}).present?
+              end
+            EOE
+            # Define a writer if this is public
+            if access_level == :public
+              self.module_eval <<-EOE, __FILE__, __LINE__ + 1
+                def #{attr_name}=(new_val)
+                  write_attribute(:#{attr_name}, new_val)
+                end
+              EOE
+            end
+          end
         end
-        self.attribute_types = self.attribute_types.merge(field => type.to_sym)
+
+        # Now we get all the attribute names as symbols
+        # and define_attribute_methods for dirty tracking
+        attrs = attrs.collect do |a|
+          Array.wrap(a).first.to_sym
+        end
+
+        super(attrs)
+        true
       end
-      
-      
+
+      #
+      # Returns true if the provided name is an attribute
+      # of this class
+      #
+      # @param  name [Symbol] The name of the potential attribute
+      #
+      # @return [Boolean] True if an attribute with the given name exists
       def attribute?(name)
         self.attribute_names.include?(name.to_sym)
       end
-      
+
+      #
+      # Returns true if the provided name is a protected attribute
+      # @param  name [Symbol] Name of the potential attribute
+      #
+      # @return [Boolean] True if a protected attribute with the given name exists
       def protected_attribute?(name)
         self.protected_attribute_names.include?(name.to_sym)
       end
-      
+
+      #
+      # Returns true if the provided name is a public attribute
+      # @param  name [Symbol] Name of the potential attribute
+      #
+      # @return [Boolean] True if a public attribute with the given name exists
+      def public_attribute?(name)
+        self.public_attribute_names.include?(name.to_sym)
+      end
+
+      #
+      # Removes all attributes from this class but does _NOT_
+      # undefine their methods
+      #
+      # @return [Boolean] Always true
       def clear_attributes
         self.attribute_names.clear
         self.public_attribute_names.clear
         self.protected_attribute_names.clear
-      end
 
-      # stores the attribute type data and the name of the 
-      # attributes we are creating
-      def store_attribute_data(arg, type)
-        if arg.is_a?(Array)
-          self.define_attribute_type(arg.first, arg.second)
-          arg = arg.first
-        end
-        self.attribute_names += [arg.to_sym]
-        self.send(
-          "#{type}_attribute_names=",
-          self.send("#{type}_attribute_names") + [arg.to_sym]
-        )
-        self.define_accessor_methods(arg)
+        true
       end
 
     end
 
-    # override the initializer to set up some default values
+    #
+    # Override for initialize to set up attribute and
+    # attributes cache
+    #
+    # @param  *args [Array] Arguments to initialize,
+    # ignored in this case
+    #
+    # @return [Object] The object in question
     def initialize(*args)
-      @attributes = @attributes_cache = HashWithIndifferentAccess.new
+      @attributes = HashWithIndifferentAccess[ self.class.attribute_names.zip([]) ]
+      @attributes_cache = HashWithIndifferentAccess.new
+      @previously_changed = HashWithIndifferentAccess.new
+      @changed_attributes = HashWithIndifferentAccess.new
+      super()
     end
 
-    def attributes
-      attrs = {}
-      self.attribute_names.each{|name| attrs[name] = read_attribute(name)}
-      attrs
-    end
+    #
+    # Reads an attribute typecasting if necessary
+    # and setting the cache so as to only typecast
+    # the one time.  Takes a block which is called if the
+    # attribute is not found
+    #
+    # @param  attr_name [Symbol] The name of the attribute to read
+    #
+    # @return [Object] The value of the attribute or nil if it
+    # is not found
+    def read_attribute(attr_name)
+      attr_name = attr_name.to_sym
 
-    # set new attributes
-    def attributes=(new_attrs)
-      new_attrs.each_pair do |k,v|
-        if self.protected_attribute?(k)
-          raise Exception.new(
-            "#{k} is a protected attribute and cannot be mass-assigned"
-          )
+      @attributes_cache[attr_name] || @attributes_cache.fetch(attr_name) do
+        data = @attributes.fetch(attr_name) do
+          # This statement overrides id to return the primary key
+          # if it is set to something other than :id
+          if attr_name == :id && self.class.primary_key != attr_name
+            return read_attribute(self.class.primary_key)
+          end
+
+          # For some reason hashes return false for key? if the value
+          # at that key is nil.  It also executes this block for fetch
+          # when it really shouldn't.  Detect that error here and give
+          # back nil for data
+          if @attributes.keys.include?(attr_name)
+            nil
+          else
+            # In this case the attribute was truly not found, if we're
+            # given a block execute that otherwise return nil
+            return block_given? ? yield(attr_name) : nil
+          end
         end
-        self.send("#{k}=",v) unless k.to_sym == :id
+        # This sets and returns the typecasted value
+        @attributes_cache[attr_name] = self.typecast_attribute_for_read(
+          attr_name,
+          data
+        )
       end
-      new_attrs
     end
 
-    def save_with_dirty_tracking(*args)
-      if save_without_dirty_tracking(*args)
-        @previously_changed = self.changes
-        @changed_attributes.clear
-        return true
+    #
+    # Reads the attribute directly out of the attributes hash
+    # without applying any typecasting
+    # @param  attr_name [Symbol] The name of the attribute to be read
+    #
+    # @return [Object] The untypecasted value of the attribute or nil
+    # if that attribute is not found
+    def read_attribute_before_type_cast(attr_name)
+      return @attributes[attr_name.to_sym]
+    end
+
+    #
+    # Writes an attribute, first typecasting it to the proper type with
+    # typecast_attribute_for_write and then setting it in the attributes
+    # hash.  Raises MissingAttributeError if no such attribute exists
+    #
+    # @param  attr_name [Symbol] The name of the attribute to set
+    # @param  value [Object] The value to write
+    #
+    # @return [Object] The value parameter is always returned
+    def write_attribute(attr_name, value)
+      attr_name = attr_name.to_sym
+      # Change a write attribute for id to the primary key
+      attr_name = self.class.primary_key if attr_name == :id && self.class.primary_key
+      # The value we expect here should be typecasted for going to
+      # the api
+      typed_value = self.typecast_attribute_for_write(attr_name, value)
+
+      if attribute_changed?(attr_name)
+        old = changed_attributes[attr_name]
+        changed_attributes.delete(attr_name) if old == typed_value
       else
-        return false
+        old = clone_attribute_value(:read_attribute, attr_name)
+        changed_attributes[attr_name] = old if old != typed_value
       end
-    end
-    
-    def set_attributes_as_current(*attrs)
-      @changed_attributes.clear and return if attrs.blank?
-      attrs.each do |attr|
-        @changed_attributes.delete(attr.to_s)
+
+      # Remove this attribute from the attributes cache
+      @attributes_cache.delete(attr_name)
+      # Raise an error if this is not an attribute
+      if !self.attribute?(attr_name)
+        raise ActiveModel::MissingAttributeError.new(
+          "can't write unknown attribute #{attr_name}",
+          caller(0)
+        )
       end
+      # Raise another error if this is a protected attribute
+      # if self.protected_attribute?(attr_name)
+      #   raise ApiResource::AttributeAccessError.new(
+      #     "cannot write to protected attribute #{attr_name}",
+      #     caller(0)
+      #   )
+      # end
+      @attributes[attr_name] = typed_value
+      value
     end
-    
-    def reset_attribute_changes(*attrs)
-      attrs = self.class.public_attribute_names if attrs.blank?
-      attrs.each do |attr|
-        self.send("reset_#{attr}!")
-      end
-      
-      set_attributes_as_current(*attrs)
+
+    #
+    # Returns the typecasted value of an attribute for being
+    # read (calls from_api on the typecaster).  Raises
+    # TypecasterNotFound if no typecaster exists for this attribute
+    #
+    # @param  attr_name [Symbol] The name of the attribute
+    # @param  value [Object] The value to be typecasted
+    #
+    # @return [Object] The typecasted value
+    def typecast_attribute_for_read(attr_name, value)
+      self
+        .find_typecaster(attr_name)
+        .from_api(value)
+    end
+
+    #
+    # Returns the typecasted value of the attribute for being
+    # written (calls to_api on the typecaster).  Raises
+    # TypecasterNotFound if no typecaster exists for this attribute
+    #
+    # @param  attr_name [Symbol] The attribute in question
+    # @param  value [Object] The value to be typecasted
+    #
+    # @return [Object] The typecasted value
+    def typecast_attribute_for_write(attr_name, value)
+      self
+        .find_typecaster(attr_name)
+        .to_api(value)
     end
 
-    def read_attribute(name)
-      self.typecasted_attribute(name.to_sym)
+    #
+    # Returns a hash of attribute names as keys and typecasted values
+    # as hash values
+    #
+    # @return [HashWithIndifferentAccess] Map from attr name to value
+    def attributes
+      hash = HashWithIndifferentAccess.new
+
+      self.class.attribute_names.each_with_object(hash) do |name, attrs|
+        attrs[name] = read_attribute(name)
+      end
     end
 
-    def write_attribute(name, val)
-      old_val = read_attribute(name)
-      new_val = val.nil? ? nil : self.typecast_attribute(name, val)
+    #
+    # Handles mass assignment of attributes, including sanitizing them
+    # for mass assignment. Which by default does nothing but would if you
+    # were to use this in rails 4 or with strong_parameters
+    #
+    # @param  attrs [Hash] Hash of attributes to mass assign
+    #
+    # @return [Hash] The passed in attrs param (with keys symbolized)
+    def attributes=(attrs)
+      unless attrs.respond_to?(:symbolize_keys)
+        raise ArgumentError, 'You must pass a hash when assigning attributes'
+      end
 
-      unless old_val == new_val
-        self.send("#{name}_will_change!")
+      return if attrs.blank?
+
+      attrs = attrs.symbolize_keys
+      # First deal with sanitizing for mass assignment
+      # this raises an error if attrs violates mass assignment rules
+      attrs = self.sanitize_for_mass_assignment(attrs)
+
+      attrs.each do |name, value|
+        self._assign_attribute(name, value)
       end
-      # delete the old cached value and assign new val to both
-      # @attributes and @attributes_cache
-      @attributes_cache.delete(name.to_sym)
-      @attributes[name.to_sym] = @attributes_cache[name.to_sym] = new_val
+
+      attrs
     end
-    
+
+    #
+    # Reads an attribute and raises MissingAttributeError
+    #
+    # @param  attr_name [Symbol] The attribute to read
+    #
+    # @return [Object] The value of the attribute
+    def [](attr_name)
+      read_attribute(attr_name) do |n|
+        self.missing_attribute(attr_name, caller(0))
+      end
+    end
+
+    #
+    # Write the value to the given attribute
+    # @param  attr_name [Symbol] The attribute to write
+    # @param  value [Object] The value to be written
+    #
+    # @return [Object] Returns the value parameter
+    def []=(attr_name, value)
+      write_attribute(attr_name, value)
+    end
+
+    #
+    # Wrapper for the class method attribute? that
+    # returns true if the name parameter is the name of
+    # any attribute
+    #
+    # @param  name [Symbol] The name to query
+    #
+    # @return [Boolean] True if the name param is the name
+    # of an attribute
     def attribute?(name)
       self.class.attribute?(name)
     end
-    
+
+    #
+    # Wrapper for the class method protected_attribute?
+    #
+    # @param  name [Symbol] The name to query
+    #
+    # @return [Boolean] True if name is a protected attribute
     def protected_attribute?(name)
       self.class.protected_attribute?(name)
     end
-    
+
+    #
+    # Wrapper for the class method public_attribute?
+    #
+    # @param  name [Symbol] The name to query
+    #
+    # @return [Boolean] True if name is a public attribute
+    def public_attribute?(name)
+      self.class.public_attribute?(name)
+    end
+
+    #
+    # Override for the save method to update our dirty tracking
+    # of attributes
+    #
+    # @param  *args [Array] Used to clear changes on any associations
+    # embedded in this save provided it succeeds
+    #
+    # @return [Boolean] True if the save succeeded, false otherwise
+    def save_with_dirty_tracking(*args)
+      if save_without_dirty_tracking(*args)
+        self.make_changes_current
+        if args.first.is_a?(Hash) && args.first[:include_associations]
+          args.first[:include_associations].each do |assoc|
+            Array.wrap(self.send(assoc).internal_object).each(&:make_changes_current)
+          end
+        end
+        return true
+      else
+        return false
+      end
+    end
+
+    #
+    # Override to respond_to? for finding attribute methods even
+    # if they are not defined
+    #
+    # @param  sym [Symbol] The method that we may respond to
+    # @param  include_private_methods = false [Boolean] Whether or not
+    # we should consider private methods
+    #
+    # @return [Boolean] True if we respond to sym
     def respond_to?(sym, include_private_methods = false)
       if sym =~ /\?$/
         return true if self.attribute?($`)
@@ -220,65 +539,145 @@ module ApiResource
       end
       super
     end
-    
-    protected
-    
-    def default_value_for_field(field)
-      case self.class.attribute_types[field.to_sym]
-        when :array
-          return []
-        else
-          return nil
+
+    def method_missing(sym, *args, &block)
+      sym = sym.to_sym
+      if @attributes.keys.symbolize_array.include?(sym)
+        return @attributes[sym]
       end
+      super
     end
 
-    def typecasted_attribute(field)
+    def make_changes_current
+      @previously_changed = self.changes
+      @changed_attributes.clear
+    end
 
-      @attributes ||= HashWithIndifferentAccess.new
-      @attributes_cache ||= HashWithIndifferentAccess.new
+    def clear_changes(*attrs)
+      @previously_changed = {}
+      @changed_attributes = {}
+      true
+    end
 
-      if @attributes_cache.has_key?(field.to_sym)
-        return @attributes_cache[field.to_sym]
-      else
-        # pull out of the raw attributes
-        if @attributes.has_key?(field.to_sym)
-          val = @attributes[field.to_sym]
-        else
-          val = self.default_value_for_field(field)
-        end
-        # now we typecast
-        val = val.nil? ? nil : self.typecast_attribute(field, val)
-        return @attributes_cache[field.to_sym] = val
+    def reset_changes
+      self.class.attribute_names.each do |attr_name|
+        attr_name = attr_name.to_sym
+
+        reset_attribute!(attr_name)
       end
+      true
     end
 
-    def typecast_attribute(field, val)
-      # if we have a valid value and we are planning to typecast go 
-      # into this case statement
-      if self.class.attribute_types.include?(field.to_sym)
-        caster = self.class.typecasters[self.class.attribute_types[field.to_sym]]
-        if caster.present?
-          val = caster.from_api(val)
+    protected
+      #
+      # Default implementation that would be overridden by including
+      # the behavior from strong parameters
+      #
+      # @param  attrs [Hash] Attributes to sanitize (by default do nothing)
+      #
+      # @return [Hash] Unmodified attrs
+      def sanitize_for_mass_assignment(attrs)
+        return attrs
+      end
+
+      #
+      # Writes an attribute by proxying to the writer methods.
+      # Raises MissingAttributeError if #{name}= does not exist
+      #
+      # @param  name [Symbol] The attribute to write
+      # @param  value [Object] The value to write
+      #
+      # @return [Boolean] Always true
+      def _assign_attribute(name, value)
+        # special case if we are assigning a protected attribute
+        # since it has no writer method
+        if self.protected_attribute?(name)
+          return self.write_attribute(name, value)
+        end
+
+        begin
+          # Call the method only if it is public
+          self.public_send("#{name}=", value)
+        rescue NoMethodError
+          # If we get a no method error we should re-raise it
+          # if it wasn't because #{name}= is not defined
+          if self.respond_to?("#{name}=")
+            raise
+          else
+            # Otherwise we raise MissingAttributeError
+            self.missing_attribute(name, caller(0))
+          end
         end
       end
 
-      return val
-    end
+      #
+      # Searches for the typecaster for the given attribute name
+      # raising ApiResource::TypecasterNotFound if it
+      # cannot find one
+      #
+      # @param  attr_name [Symbol] The attribute whose typecaster you're after
+      #
+      # @return [ApiResource::Typecaster] An object for typecasting attribute
+      # values
+      def find_typecaster(attr_name)
+        attr_name = attr_name.to_sym
+
+        typecaster = self.class.attribute_types[attr_name]
+
+        if typecaster.nil?
+          typecaster = ApiResource::Typecast::UnknownTypecaster
+        end
+
+        return typecaster
+      end
+
+      #
+      # Helper for raising a MissingAttributeError
+      #
+      # @param  name [Symbol] The missing attribute's name
+      # @param  backtrace [Object] The backtrace of where the
+      # error occurred
+      #
+      # @return [type] [description]
+      def missing_attribute(name, backtrace)
+        raise ActiveModel::MissingAttributeError.new(
+          "could not find attribute #{name}",
+          backtrace
+        )
+      end
+
+      def clone_attribute_value(meth, attr_name)
+        attr_name = attr_name.to_sym
+
+        result = self.send(meth, attr_name)
+
+        return result.duplicable? ? result.clone : result
+      end
+
 
     private
 
-    # this is here for compatibility with ActiveModel::AttributeMethods
-    # it is the fallback called in method_missing
-    def attribute(name)
-      read_attribute(name)      
-    end
+      # this is here for compatibility with ActiveModel::AttributeMethods
+      # it is the fallback called in method_missing
+      #
+      # @param  name [Symbol] The attribute to read
+      #
+      # @return [Object] The value read
+      def attribute(name)
+        read_attribute(name)
+      end
+
+      # this is here for compatibility with ActiveModel::AttributeMethods
+      # it is the fallback called in method_missing
+      #
+      # @param  name [Symbol] The attribute to
+      # @param  val [Object] The value to assign
+      #
+      # @return [Object] val
+      def attribute=(name, val)
+        write_attribute(name, val)
+      end
 
-    # this is here for compatibility with ActiveModel::AttributeMethods
-    # it is the fallback called in method_missing
-    def attribute=(name, val)
-      write_attribute(name, val)      
-    end
-    
   end
-  
+
 end