cardiac 0.2.0.pre2

data/lib/cardiac/model/callbacks.rb

@@ -0,0 +1,47 @@
+module Cardiac
+  module Model
+    
+    # Cardiac::Model callback methods.
+    # Most of this has been "borrowed" from ActiveRecord.
+    module Callbacks
+      extend ActiveSupport::Concern
+        
+      CALLBACKS = [
+        :after_initialize, :after_find, :before_validation, :after_validation,
+        :before_save, :around_save, :after_save, :before_create, :around_create,
+        :after_create, :before_update, :around_update, :after_update,
+        :before_destroy, :around_destroy, :after_destroy
+      ]
+  
+      module ClassMethods
+        include ActiveModel::Callbacks
+      end
+  
+      included do
+        include ActiveModel::Validations::Callbacks
+  
+        define_model_callbacks :initialize, :find, :only => :after
+        define_model_callbacks :save, :create, :update, :destroy
+      end
+  
+      def destroy #:nodoc:
+        run_callbacks(:destroy) { super }
+      end
+  
+    private
+  
+      def create_or_update #:nodoc:
+        run_callbacks(:save) { super }
+      end
+  
+      def create_record #:nodoc:
+        run_callbacks(:create) { super }
+      end
+  
+      def update_record(*) #:nodoc:
+        run_callbacks(:update) { super }
+      end
+      
+    end
+  end
+end

data/lib/cardiac/model/declarations.rb

@@ -0,0 +1,106 @@
+module Cardiac
+  module Model
+    
+    # Cardiac::Model declaration methods and resource extensions.
+    module Declarations
+      extend ActiveSupport::Concern
+        
+      # This extension block is used to build the base resource's extension module.
+      RESOURCE_EXTENSION_BLOCK = Proc.new do
+        
+        ##
+        # :method: find_instances
+        # This member performs a GET, after merging any arguments into the query string.
+        # This member is used by find(:all) and find_all
+        operation :find_instances,     lambda{|*query|  query.any? ? query(*query).get : get }
+          
+        ##
+        # :method: create_instance
+        # This member performs a POST, using the given argument as the payload.
+        # This member is used by create_record.
+        operation :create_instance,    lambda{|payload| post(payload)     }
+        
+        ##
+        # :method: identify
+        # This member identifies a singular subresource by converting the given argument
+        # to a parameter and appending it to the path.
+        # This member is used by all query/persistence methods that operate on existing records.
+        subresource :identify,         lambda{|id_or_model|   path(id_or_model.to_param) } do
+          
+          ##
+          # :method: update_instance
+          # This member performs a PUT, using the given argument as the payload.
+          # This member is used by update_record.
+          operation :update_instance,  lambda{|payload|       put(payload)      }
+            
+          ##
+          # :method: delete_instance
+          # This member performs a DELETE, after merging any arguments into the query string.
+          # This member is used by delete and destroy.
+          operation :delete_instance,  lambda{|*query|  query.any? ? query(*query).delete : delete }
+            
+          ##
+          # :method: find_instance
+          # This member performs a GET, after merging any arguments into the query string.
+          # This member is used by find(:one), find(:some), find_one, find_some, and find_with_ids
+          operation :find_instance,    lambda{|*query|  query.any? ? query(*query).get : get }
+        end
+      end
+
+			include ::Cardiac::Declarations
+			
+			included do
+			  singleton_class.alias_method_chain :base_resource=, :extensions
+			  singleton_class.alias_method_chain :resource, :extensions
+			end
+    
+			# Implement an instance's base resource as a subresource of the class base resource.
+			# This prevents modifications to the subresource from persisting in the system.
+			#
+			# Persisted instances will use the +identify+ subresource, otherwise the base resource is used.
+			def base_resource
+			  Subresource.new persisted? ? self.class.identify(self) : self.class.base_resource
+			end
+      
+      module ClassMethods
+        
+        # Overridden to extend the base resource with persistence operations.
+        def base_resource_with_extensions=(base)
+          case base
+          when ::URI, ::String, ::Cardiac::Resource
+            # Extend the resource with additional declarations before assigning it.
+            base = DeclarationBuilder.new(base).extension_eval(&RESOURCE_EXTENSION_BLOCK)
+          end    
+          self.base_resource_without_extensions = base
+        end
+        
+        # Overridden to ensure that the resource is first extended with persistence operations.
+        def resource_with_extensions base=nil, &declaration
+          self.base_resource = base if base.present?
+          resource_without_extensions base_resource, &declaration
+        end
+      
+      private
+      
+        # Internal method that checks for the presence of an extension method on the resource.
+        def resource_has_extension_method?(name,base=base_resource)
+          base && base.__extension_module__.method_defined?(name)
+        end
+        
+        # FIXME: use a more optimized approach that falls back on method_missing.
+        def respond_to_missing?(name,include_private=false)
+          resource_has_extension_method?(name) || super 
+        end
+        
+        # FIXME: use a more optimized approach that falls back on method_missing.
+        def method_missing(name,*args,&block)
+          if resource_has_extension_method? name
+            perform_operation name, *args, &block
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cardiac/model/dirty.rb

@@ -0,0 +1,117 @@
+module Cardiac
+  module Model
+    # Cardiac::Model dirty attribute methods.
+    # Some of this has been "borrowed" from ActiveRecord.
+    module Dirty
+      extend ActiveSupport::Concern
+
+      include ActiveModel::Dirty
+
+      included do
+        class_attribute :partial_updates
+        self.partial_updates = false     # Off by default, unlike ActiveRecord.
+      end
+
+      # Attempts to +save+ the record and clears changed attributes if successful.
+      #
+      # @see ActiveRecord::Dirty#save
+      def save(*) #:nodoc:
+        if status = super
+          @previously_changed = changes
+          @changed_attributes.clear
+        #elsif IdentityMap.enabled?
+        #  IdentityMap.remove(self)
+        end
+        status
+      end
+
+      # Attempts to <tt>save!</tt> the record and clears changed attributes if successful.
+      #
+      # @see ActiveRecord::Dirty#save!
+      def save!(*) #:nodoc:
+        super.tap do
+          @previously_changed = changes
+          @changed_attributes.clear
+        end
+      #rescue
+      #  IdentityMap.remove(self) if IdentityMap.enabled?
+      #  raise
+      end
+
+      # <tt>reload</tt> the record and clears changed attributes.
+      #
+      # @see ActiveRecord::Dirty#reload
+      def reload(*) #:nodoc:
+        super.tap do
+          @previously_changed.clear
+          @changed_attributes.clear
+        end
+      end
+      
+      private
+
+      # Wrap write_attribute to remember original attribute value.
+      #
+      # Very similar to ActiveRecord::Dirty, except that we are not dealing with timezones.
+      # The semantics of ActiveModel::Dirty#attribute_will_change! does not handle attributes
+      # changing _back_ to their original value.  Thus, like ActiveRecord, we won't use it.
+      #
+      # @see ActiveRecord::Dirty#write_attribute
+      def attribute=(attr, value)
+        attr = attr.to_s
+
+        # The attribute already had an unsaved change, so check if it is changing back to the original.
+        if attribute_changed?(attr)
+          old = @changed_attributes[attr]
+          @changed_attributes.delete(attr) unless _field_changed?(attr, old, value)
+
+          # No existing unsaved change, so simply remember this value if it differs from the original.
+        else
+          old = clone_attribute_value(:read_attribute, attr)
+          @changed_attributes[attr] = old if _field_changed?(attr, old, value)
+        end
+
+        super(attr, value)
+      end
+
+      # Wrap update_record to perform partial updates when configured to do so.
+      #
+      # @see ActiveRecord::Dirty#update
+      def update_record(*)
+        if partial_updates?
+          super(changed)
+        else
+          super
+        end
+      end
+
+      # Very similar to ActiveRecord::Dirty, except that we use ActiveAttr::Typecasting instead of columns.
+      # If no type is available, then just compare the values directly.
+      #
+      # @see ActiveRecord::Dirty#_field_changed?
+      def _field_changed?(attr, old, value)
+        if type = _attribute_type(attr)
+          if Numeric === type && (changes_from_nil_to_empty_string?(old, value) || changes_from_zero_to_string?(old, value))
+            value = nil
+          else
+            value = typecast_attribute(_attribute_typecaster(attr), value)
+          end
+        end
+        old != value
+      end
+
+      # @see ActiveRecord::Dirty#changes_from_nil_to_empty_string?
+      def changes_from_nil_to_empty_string?(old, value)
+        # If an old value of 0 is set to '' we want this to get changed to nil as otherwise it'll
+        # be typecast back to 0 (''.to_i => 0)
+        (old.nil? || old == 0) && value.blank?
+      end
+
+      # @see ActiveRecord::Dirty#changes_from_zero_to_string?
+      def changes_from_zero_to_string?(old, value)
+        # For fields with old 0 and value non-empty string
+        old == 0 && value.is_a?(String) && value.present? && value != '0'
+      end
+    end
+  end
+end

data/lib/cardiac/model/locale/en.yml

@@ -0,0 +1,7 @@
+en:
+
+  # Cardiac models configuration
+  cardiac_model:
+    errors:
+      messages:
+        record_invalid: "Validation failed: %{errors}%{remote_errors}"

data/lib/cardiac/model/operations.rb

@@ -0,0 +1,49 @@
+module Cardiac
+  module Model
+    # Cardiac::Model operational methods.
+    module Operations
+      extend ActiveSupport::Concern
+      
+      # Extensions that are applied to the OperationHandler. 
+      module HandlerExtensions
+        def transmit!(*args)
+          super
+        end
+      end
+      
+      # Extensions that are applied to the ResourceAdapter.
+      module AdapterExtensions
+        def __codecs__
+          @__codecs__ ||= Module.new{ include ::Cardiac::Representation::Codecs }
+        end
+      
+        def __handler__
+          @__handler__ ||= Class.new(::Cardiac::OperationHandler){ include HandlerExtensions; self }
+        end
+      end
+      
+      # Extensions that are applied to the OperationProxy.
+      module ProxyExtensions
+        def __adapter__
+          @__adapter__ ||= Class.new(::Cardiac::ResourceAdapter){ include AdapterExtensions ; self }
+        end
+      end
+      
+      module ClassMethods
+        
+      private
+        
+        # All remote operations go through this method.
+        def perform_operation(name, *args, &block)
+          proxy = __operation_proxy__.new(base_resource)
+          proxy.klass = self
+          proxy.__send__(name,*args,&block)
+        end
+
+        def __operation_proxy__
+          @__operation_proxy__ ||= Class.new(OperationProxy){ include ProxyExtensions ; self }
+        end
+      end
+    end
+  end
+end

data/lib/cardiac/model/persistence.rb

@@ -0,0 +1,171 @@
+module Cardiac
+  module Model
+    
+    # Cardiac::Model persistence methods.
+    # Most of this has been "borrowed" from ActiveRecord.
+    module Persistence
+      extend ActiveSupport::Concern
+        
+      module ClassMethods
+        # See ActiveRecord::Base.create
+        def create(attributes = nil, &block)
+          if attributes.is_a?(Array)
+            attributes.collect { |attr| create(attr, &block) }
+          else
+            object = new(attributes, &block)
+            object.save
+            object
+          end
+        end
+        
+      end
+      
+      # Returns true if this object hasn't been saved yet -- that is, a record
+      # for the object doesn't exist in the data store yet; otherwise, returns false.
+      def new_record?
+        @new_record
+      end
+  
+      # Returns true if this object has been destroyed, otherwise returns false.
+      def destroyed?
+        @destroyed
+      end
+  
+      # Returns true if the record is persisted, i.e. it's not a new record and it was
+      # not destroyed, otherwise returns false.
+      def persisted?
+        !(new_record? || destroyed?)
+      end
+      
+      # Performs a DELETE on the remote resource if the record is not new, marks it
+      # as destroyed, then freezes the attributes.
+      def delete
+        delete_record
+        freeze
+      end
+      
+      # Delegates to delete, except it raises a +ReadOnlyRecord+ error if the record is read-only.
+      def destroy
+        raise ReadOnlyRecord if readonly?
+        delete
+      end
+      
+      # Delegates to destroy, but raises +RecordNotDestroyed+ if checks fail.
+      def destroy!
+        destroy || raise(RecordNotDestroyed)
+      end      
+      
+      # Delegates to create_or_update, but rescues validation exceptions to return false.
+      def save(*)
+        create_or_update
+      rescue RecordInvalid
+        false
+      end
+
+      # Delegates to create_or_update, but raises +RecordNotSaved+ if validations fail.
+      def save!(*)
+        create_or_update || raise(RecordNotSaved)
+      end
+  
+      # Reloads the attributes of this object from the remote.
+      # Any (optional) arguments are passed to find when reloading.
+      def reload(*args)
+        #IdentityMap.without do
+          fresh_object = self.class.find(self.id, *args)
+          @attributes.update(fresh_object.instance_variable_get('@attributes'))
+        #end
+        self
+      end
+      
+      # Updates a single attribute and saves the record.
+      # This is especially useful for boolean flags on existing records. Also note that
+      #
+      # * Validation is skipped.
+      # * Callbacks are invoked.
+      # * updated_at/updated_on column is updated if that column is available.
+      # * Updates all the attributes that are dirty in this object.
+      #
+      # This method raises an +OperationFailError+ if the attribute is marked as readonly.
+      def update_attribute(name, value)
+        name = name.to_s
+        verify_readonly_attribute(name)
+        send("#{name}=", value)
+        save(validate: false)
+      end
+  
+      # Updates the attributes of the model from the passed-in hash and saves the
+      # record. If the object is invalid, the saving will fail and false will be returned.
+      def update(attributes)
+        assign_attributes(attributes)
+        save
+      end
+  
+      alias update_attributes update
+  
+      # Updates its receiver just like +update+ but calls <tt>save!</tt> instead
+      # of +save+, so an exception is raised if the record is invalid.
+      def update!(attributes)
+        assign_attributes(attributes)
+        save!
+      end
+  
+      alias update_attributes! update!
+  
+    private
+    
+      # Internal method that deletes an existing record, then marks this record as destroyed.
+      def delete_record
+        self.remote_attributes = self.class.identify(self).delete_instance if persisted?
+        @destroyed = true
+      end
+
+      # Internal method that either creates a new record, or updates an existing one.
+      # Raises a ReadOnlyRecord error if the record is read-only.
+      def create_or_update
+        raise ReadOnlyRecord if readonly?
+        result = new_record? ? create_record : update_record
+        result != false
+      end
+      
+      # Internal method that updates an existing record.
+      def update_record(attribute_names = attributes.keys)
+        
+        # Build a payload hash, but silently skip this operation if they are empty.
+        payload_hash = attributes_for_update(attribute_names)
+        return unless payload_hash.present?
+        
+        # Perform the operation and save the attributes returned by the remote.
+        self.remote_attributes = self.class.identify(self).update_instance(payload_hash)
+        
+        # Return success.
+        true
+      end
+  
+      # Internal method that creates an existing record.
+      def create_record(attribute_names = @attributes.keys)
+        
+        # Build a payload hash.
+        payload_hash = attributes_for_create(attribute_names)
+        
+        # Perform the operation and save the attributes returned by the remote.
+        self.remote_attributes = self.class.create_instance(payload_hash)
+        
+        # Write back any key attributes returned by the remote.
+        self.class.key_attributes.each do |key| key = key.to_s
+          write_attribute key, @remote_attributes[key] if @remote_attributes.has_key? key
+        end
+ 
+        # No longer a new record, if we at least have all key attributes defined.
+        @new_record = ! self.class.key_attributes.all?{|key| query_attribute key }
+          
+        # Return success, if we are no longer a new record.
+        ! @new_record
+      end
+
+      # @see ActiveRecord::Persistence#verify_readonly_attribute
+      def verify_readonly_attribute(name)
+        raise OperationFailError, "#{name} is marked as readonly" if self.class.readonly_attributes.include?(name)
+      end
+    end
+  end
+end

data/lib/cardiac/model/querying.rb

@@ -0,0 +1,129 @@
+module Cardiac
+  module Model
+    
+    # Cardiac::Model finder methods.
+    # Some of this has been "borrowed" from ActiveRecord.
+    module Querying
+      extend ActiveSupport::Concern
+        
+      module ClassMethods
+        
+        # This is a basic implementation that just delegates to find_all.
+        def all
+          find_all
+        end
+        
+        # Simple pattern for delegating find operations to the resource.
+        # This is pretty similar to earlier AR versions that did not proxy to Relation.
+        #
+        # The biggest difference is that all finder methods accept an evaluator block
+        # allowing bulk operations to be performed on returned results.
+        def find(criteria=:all,*args,&evaluator)
+          case criteria
+          when :all, :first, :some, :one
+            send(:"find_#{criteria}", *args, &evaluator)
+          when Hash
+            find_all(*args.unshift(criteria), &evaluator)
+          when Array
+            find_with_ids(criteria, &evaluator)
+          when self, Numeric, String
+            find_one(criteria, &evaluator)
+          when Model::Base
+            find_one(criteria.id, &evaluator)
+          else
+            raise ArgumentError, "unsupported finder criteria: #{criteria}:#{criteria.class}"
+          end
+        end
+        
+      protected
+      
+        # Simple pattern for delegating find :first operations to the resource.
+        # Unlike the other finders, this one will return +nil+ instead of raising an error if it is not found.
+        def find_first(criteria,*args,&evaluator)
+          case criteria
+          when Array
+            criteria = criteria.first
+          when self, Numeric, String
+            # PASS-THROUGH
+          when Model::Base
+            criteria = criteria.id
+          else
+            raise ArgumentError, "unsupported find_first criteria: #{criteria}:#{criteria.class}"
+          end 
+          find_by_identity(criteria,&evaluator)
+        end
+        
+        # Delegates to the find_instances operation on the resource.
+        def find_all(*args, &evaluator)
+          result = unwrap_remote_collection(find_instances(*args)) || []
+          raise InvalidRepresentationError, 'expected Array, but got '+result.class.name unless Array===result
+          result.map! do |record|
+            instantiate(record, remote: true, &evaluator)
+          end
+        end
+
+        # See ActiveRecord::Relation::FinderMethods#find_with_ids        
+        def find_with_ids(*ids, &evaluator)
+          expects_array = ids.first.kind_of?(Array)
+          return ids.first if expects_array && ids.first.empty?
+          ids = ids.flatten.compact.uniq
+          case ids.size
+          when 0
+            raise RecordNotFound, "Couldn't find #{name} without an ID"
+          when 1
+            result = find_one(ids.first, &evaluator)
+            expects_array ? [ result ] : result
+          else
+            find_some(ids, &evaluator)
+          end
+        end
+        
+        # See ActiveRecord::Relation::FinderMethods#find_one
+        def find_one(id, &evaluator)
+          record = find_by_identity(id,&evaluator)
+          raise_record_not_found_exception!(id, 0, 1) unless record
+          record
+        end
+        
+        # See ActiveRecord::Relation::FinderMethods#find_some
+        def find_some(ids, &evaluator)
+          results = ids.map{|id| find_by_identity(id,&evaluator) }
+          results.compact!
+          raise_record_not_found_exception!(ids, results.size, expected_size) unless results.size == ids.size
+          results
+        end
+      
+        # @see ActiveRecord::Persistence#instantiate
+        def instantiate(record, options = {})
+          allocate.init_with options.merge('attributes'=>record).stringify_keys
+        end
+        
+        # See ActiveRecord::Relation::FinderMethods#raise_record_not_found_exception
+        def raise_record_not_found_exception!(ids, result_size, expected_size) #:nodoc:
+          if Array(ids).size == 1
+            error = "Couldn't find #{name} with #{key_attributes.first}=#{ids}"
+          else
+            error = "Couldn't find all #{name.pluralize} with IDs "
+            error << "(#{ids.join(", ")}) (found #{result_size} results, but was looking for #{expected_size})"
+          end
+          raise RecordNotFound, error
+        end
+
+        # Unwraps a collection payload returned by the remote.
+        def unwrap_remote_collection(data,options={})
+          unwrap_remote_data data, options
+        end
+        
+      private
+      
+        # Delegates to the resource to find a single instance of a record and return the remote payload.
+        def find_by_identity(id, &evaluator)
+          record = unwrap_remote_data identify(id).find_instance
+          instantiate(record, remote: true, &evaluator) if record
+        rescue Cardiac::RequestFailedError => e
+          raise e unless e.status == 404  # Ignores 404 Not Found
+        end
+      end
+    end
+  end
+end