morpheus 0.4.0 → 0.5.0

data/lib/morpheus/mixins/associations/association.rb

@@ -0,0 +1,112 @@
+# The Association class serves as the basis for associating resources.
+# Resources have an association DSL that follows that of ActiveRecord:
+#
+# has_many :automobiles
+#
+# has_one :car
+#
+# belongs_to :car_club
+#
+# This class acts as a proxy that will allow for lazy evaluation of an
+# association. The proxy waits to make the request for the object until
+# a method on the association is called. When this happens, because the
+# method does not exist on the proxy object, method_missing will be
+# called, the target object will be loaded, and then the method will be
+# called on the loaded target.
+module Morpheus
+  module Mixins
+    module Associations
+      class Association < ActiveSupport::BasicObject
+
+        # Associations can be loaded with several options.
+        def initialize(owner, association, settings = {})
+          # @owner stores the class that the association exists on.
+          @owner = owner
+
+          # @association stores the associated class, as named in the association
+          # method (i.e. :automobile, :car, :car_club)
+          @association = association
+
+          # @target stores the loaded object. It is not typically accessed directly,
+          # but instead should be accessed through the loaded_target method.
+          @target = settings[:target]
+
+          @filters = settings[:filters] || []
+
+          @includes = []
+
+          # @options holds the chosen options for the association. Several of these
+          # options are set in the subclass' initializer.
+          @options = settings[:options] || {}
+
+          # In some cases, the association name will not match that of the class
+          # that should be instantiated when it is invoked. Here, we can specify
+          # that this association uses a specified class as its target. When the
+          # request is made for the association, this class will be used to
+          # instantiate this object or collection.
+          @options[:class_name] = settings[:options][:class_name] || @association.to_s.classify
+        end
+
+        # The proxy implements a few methods that need to be delegated to the target
+        # so that they will work as expected.
+        def id
+          loaded_target.id
+        end
+
+        def nil?
+          loaded_target.nil?
+        end
+
+        def to_param
+          loaded_target.to_param
+        end
+
+        def try(method, *args, &block)
+          loaded_target.try(method, *args, &block)
+        end
+
+        def includes(*associations)
+          associations.each do |association|
+            @includes << association unless @includes.include?(association)
+          end
+          self
+        end
+
+        # This is left to be implemented by the subclasses as it will operate
+        # differently in each case.
+        def load_target!
+        end
+
+        private
+
+        # The loaded_target method holds a cached version of the loaded target.
+        # This method is used to access the proxied object. Since a request will
+        # be made when a method is invoked on the object, and this can happen
+        # very often, we are caching the target here, so that only a single
+        # request will be made.
+        def loaded_target
+          @target ||= load_target!
+          if ::Array === @target && !@filters.empty?
+            @filters.uniq.inject(@target.dup) do |target, filter|
+              filter.call(target)
+            end
+          else
+            @target
+          end
+        end
+
+        # The method_missing hook will be called when methods that do not exist
+        # on the proxy object are invoked. This is the point at which the proxied
+        # object is loaded, if it has not been loaded already.
+        def method_missing(m, *args, &block)
+          if filter = @association_class.find_filter(m)
+            with_filter(filter)
+          else
+            loaded_target.send(m, *args, &block)
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/morpheus/mixins/associations/belongs_to_association.rb

@@ -0,0 +1,47 @@
+module Morpheus
+  module Mixins
+    module Associations
+      class BelongsToAssociation < Association
+
+        # The initializer calls out to the superclass' initializer, then will set the
+        # options particular to itself.
+        def initialize(owner, association, settings = {})
+          super
+
+          # The foreign key is used to generate the url for a request. The default uses
+          # the association name with an '_id' suffix as the generated key. For example,
+          # belongs_to :school, will have the foreign key :school_id.
+          @options[:foreign_key] ||= "#{@association.to_s}_id".to_sym
+
+          # The primary key defaults to :id.
+          @options[:primary_key] ||= :id
+
+          # Associations can be marked as polymorphic. These associations will use
+          # the returned type to instantiate the associated object.
+          @options[:polymorphic] = settings[:options][:polymorphic] || false
+
+          # @association_class stores the class of the association, constantized
+          # from the named association (i.e. Automobile, Car, CarClub)
+          @association_class = @options[:class_name].constantize
+        end
+
+        def with_filter(filter)
+          BelongsToAssociation.new(@owner, @association, :target => @target, :filters => @filters.dup.push(filter), :options => @options)
+        end
+
+        # When loading the target, the association will only be loaded if the foreign_key
+        # has been set. Additionally, the class used to find the record will be inferred
+        # by calling the method which is the name of the association with a '_type' suffix.
+        # Alternatively, the class name can be set by using the :class_name option.
+        def load_target!
+          if association_id = @owner.send(@options[:foreign_key])
+            polymorphic_class = @options[:polymorphic] ? @owner.send("#{@association}_type".to_sym).constantize : @options[:class_name].constantize
+            attributes = [UrlBuilder.belongs_to(polymorphic_class, association_id), nil, { :id => association_id }]
+            polymorphic_class.find(association_id)
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/morpheus/mixins/associations/has_many_association.rb

@@ -0,0 +1,72 @@
+module Morpheus
+  module Mixins
+    module Associations
+      class HasManyAssociation < Association
+
+        # The initializer calls out to the superclass' initializer and then
+        # sets the options particular to itself.
+        def initialize(owner, association, settings = {})
+          super
+
+          # The foreign key is used to generate the url for the association
+          # request when the association is transformed into a relation.
+          # The default is to use the class of the owner object with an '_id'
+          # suffix.
+          @options[:foreign_key] ||= "#{@owner.class.to_s.underscore}_id".to_sym
+
+          # The primary key is used in the generated url for the target. It
+          # defaults to :id.
+          @options[:primary_key] ||= :id
+
+          # @association_class stores the class of the association, constantized
+          # from the named association (i.e. Automobile, Car, CarClub)
+          @association_class = @options[:class_name].constantize
+        end
+
+        def with_filter(filter)
+          HasManyAssociation.new(@owner, @association, :target => @target, :filters => @filters.dup.push(filter), :options => @options)
+        end
+
+        # When loading the target, the primary key is first checked. If the
+        # key is nil, then an empty array is returned. Otherwise, the target
+        # is requested at the generated url. For a has_many :meetings
+        # association on a class called Course, the generated url might look
+        # like this: /meetings?course_id=1, where the 1 is the primary key.
+        def load_target!
+          if primary_key = @owner.send(@options[:primary_key])
+            Relation.new(@association.to_s.classify.constantize).where(@options[:foreign_key] => primary_key).all
+          else
+            []
+          end
+        end
+
+        # The where, limit, and page methods delegate to a Relation object.
+        # The association generates a relation, and then calls the very
+        # same where, limit, or page method on that relation object.
+        def where(query_attributes)
+          transform_association_into_relation.where(query_attributes)
+        end
+
+        def limit(amount)
+          transform_association_into_relation.limit(amount)
+        end
+
+        def page(page_number)
+          transform_association_into_relation.page(page_number)
+        end
+
+        def transform_association_into_relation
+          Relation.new(@association.to_s.classify.constantize).where(@options[:foreign_key] => @owner.send(@options[:primary_key]))
+        end
+        private :transform_association_into_relation
+
+        # The append operator is used to append new resources to the association.
+        def <<(one_of_many)
+          @target ||= []
+          @target << one_of_many
+        end
+
+      end
+    end
+  end
+end

data/lib/morpheus/mixins/associations/has_one_association.rb

@@ -0,0 +1,48 @@
+module Morpheus
+  module Mixins
+    module Associations
+      class HasOneAssociation < Association
+
+        # The initializer calls out to the superclass' initializer and then
+        # sets the options particular to itself.
+        def initialize(owner, association, settings = {})
+          super
+
+          # The foreign key is used to generate the url for the association
+          # request when the association is transformed into a relation.
+          # The default is to use the class of the owner object with an '_id'
+          # suffix.
+          @options[:foreign_key] ||= "#{@owner.class.to_s.underscore}_id".to_sym
+
+          # The primary key is used in the generated url for the target. It
+          # defaults to :id.
+          @options[:primary_key] ||= :id
+
+          # @association_class stores the class of the association, constantized
+          # from the named association (i.e. Automobile, Car, CarClub)
+          if @options[:class_name]
+            @association_class = @options[:class_name].constantize
+          else
+            @association_class = @association
+          end
+        end
+
+        def with_filter(filter)
+          HasOneAssociation.new(@owner, @association, :target => @target, :filters => @filters.dup.push(filter), :options => @options)
+        end
+
+        # When loading the target, the primary key is first checked. If the
+        # key is nil, then an nil is returned. Otherwise, the target
+        # is requested at the generated url. For a has_one :meeting
+        # association on a class called Course, the generated url might look
+        # like this: /meetings?course_id=1, where the 1 is the primary key.
+        def load_target!
+          if primary_key = @owner.send(@options[:primary_key])
+            Relation.new(@association_class.to_s.classify.constantize).where(@options[:foreign_key] => primary_key).limit(1).first
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/morpheus/mixins/attributes.rb

@@ -1,132 +1,134 @@
 module Morpheus
-  module Attributes
+  module Mixins
+    module Attributes
 
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
-
-    module ClassMethods
-
-      def property(name, typecast_class = nil)
-        typecast_attributes.store(name.to_sym, typecast_class)
-        default_attributes.store(name.to_sym, nil)
-
-        define_attribute_accessor(name)
+      def self.included(base)
+        base.extend(ClassMethods)
       end
 
-      def default_attributes
-        @attributes ||= HashWithIndifferentAccess.new(superclass.respond_to?(:default_attributes) ? superclass.default_attributes : {})
-      end
+      module ClassMethods
 
-      def typecast_attributes
-        @typecast_attributes ||= HashWithIndifferentAccess.new(superclass.respond_to?(:default_attributes) ? superclass.default_attributes : {})
-      end
+        def property(name, typecast_class = nil)
+          typecast_attributes.store(name.to_sym, typecast_class)
+          default_attributes.store(name.to_sym, nil)
 
-      def attribute_defined?(attribute)
-        default_attributes.keys.include?(attribute.to_s)
-      end
+          define_attribute_accessor(name)
+        end
 
-      def define_attribute_accessor(method)
-        method = method.to_s.delete('=')
-        define_method("#{method}=") do |value|
-          send("#{method}_will_change!")
-          update_attribute(method, value)
+        def default_attributes
+          @attributes ||= HashWithIndifferentAccess.new(superclass.respond_to?(:default_attributes) ? superclass.default_attributes : {})
         end
 
-        define_method(method) do
-          attributes[method]
+        def typecast_attributes
+          @typecast_attributes ||= HashWithIndifferentAccess.new(superclass.respond_to?(:default_attributes) ? superclass.default_attributes : {})
         end
 
-        define_attribute_methods [method]
-      end
-      private :define_attribute_accessor
+        def attribute_defined?(attribute)
+          default_attributes.keys.include?(attribute.to_s)
+        end
 
-    end
+        def define_attribute_accessor(method)
+          method = method.to_s.delete('=')
+          define_method("#{method}=") do |value|
+            send("#{method}_will_change!")
+            update_attribute(method, value)
+          end
 
-    def attributes
-      @attributes ||= self.class.default_attributes.dup
-    end
+          define_method(method) do
+            attributes[method]
+          end
 
-    def read_attribute_for_validation(key)
-      attributes[key]
-    end
+          define_attribute_methods [method]
+        end
+        private :define_attribute_accessor
 
-    def typecast(attribute, value)
-      TypeCaster.cast(value, self.class.typecast_attributes[attribute.to_sym])
-    end
+      end
 
-    def attributes_without_basic_attributes
-      attributes_to_reject = %w( id errors valid )
-      self.class.reflections.keys.each do |key|
-        attributes_to_reject.push(key.to_s)
+      def attributes
+        @attributes ||= self.class.default_attributes.dup
       end
-      attributes.reject do |key, value|
-        attributes_to_reject.include?(key)
+
+      def read_attribute_for_validation(key)
+        attributes[key]
       end
-    end
 
-    def update_attribute(attribute, value)
-      reflection = self.class.reflect_on_association(attribute)
-      if reflection
-        update_reflection(reflection, attribute, value)
-      else
-        attributes[attribute.to_sym] = typecast(attribute, value)
+      def typecast(attribute, value)
+        TypeCaster.cast(value, self.class.typecast_attributes[attribute.to_sym])
+      end
+
+      def attributes_without_basic_attributes
+        attributes_to_reject = %w( id errors valid )
+        self.class.reflections.keys.each do |key|
+          attributes_to_reject.push(key.to_s)
+        end
+        attributes.reject do |key, value|
+          attributes_to_reject.include?(key)
+        end
       end
-    end
 
-    def update_reflection(reflection, attribute, value)
-      return unless value
-      if reflection.macro == :has_many # need to construct each member of array one-by-one
-        association_object = send(attribute)
-        value.each do |a_value|
-          if a_value.instance_of? reflection.klass
-            target = a_value
+      def update_attribute(attribute, value)
+        reflection = self.class.reflect_on_association(attribute)
+        if reflection
+          update_reflection(reflection, attribute, value)
+        else
+          attributes[attribute.to_sym] = typecast(attribute, value)
+        end
+      end
+
+      def update_reflection(reflection, attribute, value)
+        return unless value
+        if reflection.macro == :has_many # need to construct each member of array one-by-one
+          association_object = send(attribute)
+          value.each do |a_value|
+            if a_value.instance_of? reflection.klass
+              target = a_value
+            else
+              target = reflection.build_association(a_value)
+            end
+            association_object << target
+          end
+        elsif reflection.macro == :belongs_to
+          if value.instance_of? reflection.klass
+            target = value
           else
-            target = reflection.build_association(a_value)
+            if reflection.options[:polymorphic]
+              polymorphic_class = send("#{reflection.name}_type".to_sym)
+              polymorphic_class = value['type'] if value.include?('type')
+              target = polymorphic_class.constantize.new(value)
+            else
+              target = reflection.build_association(value)
+            end
           end
-          association_object << target
-        end
-      elsif reflection.macro == :belongs_to
-        if value.instance_of? reflection.klass
-          target = value
+          send("#{attribute}=", target)
         else
-          if reflection.options[:polymorphic]
-            polymorphic_class = send("#{reflection.name}_type".to_sym)
-            polymorphic_class = value['type'] if value.include?('type')
-            target = polymorphic_class.constantize.new(value)
+          if value.instance_of? reflection.klass
+            target = value
           else
             target = reflection.build_association(value)
           end
+          send("#{attribute}=", target)
         end
-        send("#{attribute}=", target)
-      else
-        if value.instance_of? reflection.klass
-          target = value
-        else
-          target = reflection.build_association(value)
-        end
-        send("#{attribute}=", target)
       end
-    end
 
-    def merge_attributes(new_attributes)
-      new_attributes.each do |key, value|
-        case key.to_sym
-        when :errors
-          value.each do |k, v|
-            v.each do |message|
-              errors.add(k, message)
+      def merge_attributes(new_attributes)
+        new_attributes.each do |key, value|
+          case key.to_sym
+          when :errors
+            value.each do |k, v|
+              v.each do |message|
+                errors.add(k, message)
+              end
             end
+          when :valid
+            @valid = value
+          else
+            update_attribute(key, value)
           end
-        when :valid
-          @valid = value
-        else
-          update_attribute(key, value)
         end
+        self
       end
-      self
-    end
-    private :merge_attributes
+      private :merge_attributes
 
+    end
   end
 end