vidibus-inheritance 0.3.6 → 0.3.9

data/README.rdoc

@@ -2,7 +2,7 @@
 
 This gem is part of the open source SOA framework Vidibus: http://www.vidibus.org
 
-It allows inheritance of objects for Rails 3 with Mongoid. It will update all attributes and embedded documents of inheritors when ancestor gets changed. Custom attributes (mutations) of inheritors will not be overridden, unless a :reset option is set.
+It allows inheritance of objects and is depends on Rails 3 and Mongoid. It will update all attributes and embedded documents of inheritors when ancestor gets changed. Custom attributes (mutations) of inheritors will not be overridden, unless a :reset option is set.
 
 
 == Installation
@@ -25,7 +25,7 @@ Include the Vidibus::Uuid::Inheritance module in your Mongoid model:
     field :name
   end
   
-To establish a inheritance relationship, add ancestor to a model of same class:
+To establish an inheritance relationship, add ancestor to a model of same class:
   
   ancestor = Model.create(:name => "Anna")
   
@@ -49,6 +49,7 @@ When inheriting, the attribute :_reference_id will be set on embedded documents
 All attributes will be inherited, except these ACQUIRED_ATTRIBUTES:
 
   _id
+  _type
   uuid
   ancestor_uuid
   mutated_attributes

data/TODO

@@ -1,5 +1,4 @@
-Use delayed_job
-
-Use uuid for children to ensure portability across the network?
-
-Get ACQUIRED_ATTRIBUTES as class variable from each document, if available
+* Removed items will be re-added when inheritance is performed again. Introduce paranoid behaviour for embedded collection items? Or add a list of deleted associations like _destroyed_children?
+* Use delayed_job for inheritance across a huge pedigree.
+* Maybe use UUID for children to ensure portability across the network?
+* Get ACQUIRED_ATTRIBUTES as class variable from each document, if available.

data/VERSION

@@ -1 +1 @@
-0.3.6
+0.3.9

data/lib/vidibus/inheritance.rb

@@ -1,8 +1,2 @@
 require "inheritance/mongoid"
-require "inheritance/validators"
-
-module Vidibus
-  module Inheritance
-    class SomeError < StandardError; end
-  end
-end
+require "inheritance/validators"

data/lib/vidibus/inheritance/mongoid.rb

@@ -3,7 +3,7 @@ module Vidibus
     module Mongoid
       extend ActiveSupport::Concern
 
-      ACQUIRED_ATTRIBUTES = %w[_id uuid ancestor_uuid mutated_attributes mutated created_at updated_at version versions]
+      ACQUIRED_ATTRIBUTES = %w[_id _type uuid ancestor_uuid mutated_attributes mutated created_at updated_at version versions]
       
       included do
         attr_accessor :inherited_attributes, :_inherited
@@ -16,223 +16,272 @@ module Vidibus
         validates :ancestor_uuid, :uuid => { :allow_blank => true }
         validates :ancestor, :ancestor => true, :if => :ancestor_uuid?
 
-        before_validation :preprocess 
-        after_save :postprocess
-      
-        # Callback of Mongoid when deleting a collection item on a parent object.
-        def remove(*args)
-          super(*args)
-        end
-
-        # Setter for ancestor.
-        def ancestor=(obj)
-          self.ancestor_uuid = obj.uuid
-          @ancestor = obj
+        set_callback :validate, :before, :inherit_attributes, :if => :inherit?
+        set_callback :save, :before, :track_mutations
+        set_callback :save, :after, :postprocess
+        set_callback :destroy, :after, :destroy_inheritors
+        
+        # Returns true if attributes have been mutated.
+        # This method must be included directly so that it will not be
+        # overwritten by Mongoid's accessor #mutated?
+        def mutated?
+          @is_mutated ||= mutated || mutated_attributes.any?
         end
+      end
       
-        # Returns ancestor object by uuid.
-        def ancestor
-          @ancestor ||= begin
-            self.class.where(:uuid => ancestor_uuid).first if ancestor_uuid
+      module ClassMethods
+        
+        # Returns embedded documents of given document.
+        # Provide :keys option if you want to return a list of document types instead
+        # of a hash of documents grouped by their type.
+        #
+        # Example:
+        #
+        #   inheritable_documents(model)
+        #   # => { :children => [ <embeds_many collection> ], :location => <embeds_one object> }
+        #
+        #   inheritable_documents(model, :keys => true)
+        #   # => [:children, :location ]
+        #
+        def inheritable_documents(object, options = {})
+          keys = options[:keys]
+          collection = keys ? [] : {}
+          for name, association in object.associations
+            next unless association.embedded?
+            if keys
+              collection << name
+            else
+              collection[name] = object.send(name)
+            end
           end
+          collection
         end
-      
-        # Performs inheritance and saves instance with force.
-        # Accepts :reset option to overwrite mutated attributes.
-        # 
-        # Usage:
-        #
-        #   inherit!(:reset => true)          => # Overwrites all mutated attributes
-        #   inherit!(:reset => :name)         => # Overwrites name only
-        #   inherit!(:reset => [:name, :age]) => # Overwrites name and age
+        
+        # Returns all objects that have no ancestor.
+        # Accepts Mongoid criteria to reduce and sort matching set.
+        # Criteria API: http://mongoid.org/docs/querying/
         #
-        def inherit!(options = {})
-          self.inherit_attributes(options)
-          self.save!
+        # Examples:
+        #   
+        #   Model.root                          # => All models without ancestor
+        #   Model.root.where(:name => "Laura")  # => Only models named Laura
+        #   Model.root.asc(:created_at)         # => All models, ordered by date of creation
+        # 
+        def roots
+          where(:ancestor_uuid => nil)
         end
-      
-        # Performs inheritance from given object.
-        # Accepts :reset option to overwrite mutated attributes.
-        def inherit_from!(obj, options = {})
-          self.ancestor = obj
-          self.inherit!(options)
+      end
+    
+      # Setter for ancestor.
+      def ancestor=(obj)
+        self.ancestor_uuid = obj.uuid
+        @ancestor = obj
+      end
+    
+      # Returns ancestor object by uuid.
+      def ancestor
+        @ancestor ||= begin
+          self.class.where(:uuid => ancestor_uuid).first if ancestor_uuid
         end
+      end
       
-        # Returns list of objects that inherit from this ancestor.
-        def inheritors
-          self.class.where(:ancestor_uuid => uuid).to_a
+      # Returns a list of all ancestors ordered by inheritance distance.
+      def ancestors
+        @ancestors ||= [].tap do |bloodline|
+          obj = self
+          while true do
+            break unless obj = obj.ancestor
+            bloodline << obj
+          end
         end
+      end
       
-        # Returns embedded documents.
-        def inheritable_documents
-          self.class.inheritable_documents(self)
-        end
-        
-        # Returns true if attributes have been mutated.
-        def mutated?
-          @is_mutated ||= mutated || mutated_attributes.any?
-        end
-
-        protected
+      # Performs inheritance and saves instance with force.
+      # Accepts :reset option to overwrite mutated attributes.
+      # 
+      # Examples:
+      #
+      #   inherit!(:reset => true)          => # Overwrites all mutated attributes
+      #   inherit!(:reset => :name)         => # Overwrites name only
+      #   inherit!(:reset => [:name, :age]) => # Overwrites name and age
+      #
+      def inherit!(options = {})
+        inherit_attributes(options)
+        self.save!
+      end
+    
+      # Performs inheritance from given object.
+      # It sets the ancestor and then calls #inherit! with given options.
+      def inherit_from!(obj, options = {})
+        self.ancestor = obj
+        self.inherit!(options)
+      end
+    
+      # Returns inheritors of this ancestor.
+      def inheritors
+        self.class.where(:ancestor_uuid => uuid)
+      end
+    
+      # Returns embedded documents.
+      # See ClassMethods.inheritable_documents for options.
+      def inheritable_documents(options = {})
+        self.class.inheritable_documents(self, options)
+      end
       
-        # Performs inheritance of attributes while excluding acquired and mutated ones.
-        # Accepts :reset option to overwrite mutated attributes.
-        def inherit_attributes(options = {})
-          self._inherited = true
-          exceptions = ACQUIRED_ATTRIBUTES
-          reset = options[:reset]
-          if !reset
-            exceptions += mutated_attributes
-          elsif reset != true
-            reset_attributes = reset.is_a?(Array) ? reset.map { |a| a.to_s } : [reset.to_s]
-            exceptions += mutated_attributes - reset_attributes
-          end
-          exceptions += ancestor.inheritable_documents.keys
-          self.attributes = self.inherited_attributes = ancestor.attributes.except(*exceptions)
+      # Creates a sibling with identical inheritable attributes.
+      # Applies inheritance on new object.
+      def clone!
+        exceptions = ACQUIRED_ATTRIBUTES - ["ancestor_uuid"]
+        attrs = attributes.except(*exceptions)
+        self.class.create!(attrs)
+      end
+
+      private
+    
+      # Performs inheritance of attributes while excluding acquired and mutated ones.
+      # Accepts :reset option to overwrite mutated attributes.
+      def inherit_attributes(options = {})
+        track_mutations
+        self._inherited = true
+        exceptions = ACQUIRED_ATTRIBUTES
+        reset = options[:reset]
+        if !reset
+          exceptions += mutated_attributes
+        elsif reset != true
+          reset_attributes = reset.is_a?(Array) ? reset.map { |a| a.to_s } : [reset.to_s]
+          exceptions += mutated_attributes - reset_attributes
         end
+        exceptions += ancestor.inheritable_documents.keys
+        self.attributes = self.inherited_attributes = ancestor.attributes.except(*exceptions)
+      end
+
+      # Performs inheritance of documents.
+      def inherit_documents
+        return unless ancestor
+        return unless list = ancestor.inheritable_documents
+        for association, inheritable in list
         
-        # Performs inheritance of documents.
-        def inherit_documents
-          return unless ancestor
-          return unless list = ancestor.inheritable_documents
-          for association, inheritable in list
-          
-            # embeds_many
-            if inheritable.is_a?(Array)
-              collection = new_record? ? self.send(association) : self.reload.send(association)
-              existing_ids = collection.map do |a| 
-                begin
-                  a._reference_id
-                rescue
-                end
-              end
-              
-              for obj in inheritable
-                attrs = inheritable_document_attributes(obj)
-                if existing_ids.include?(obj._id)
-                  doc = collection.where(:_reference_id => obj._id).first
-                  update_inheritable_document(doc, attrs)
-                else
-                  doc = collection.create!(attrs)
-                end
-              end
-              
-              obsolete = existing_ids - inheritable.map { |i| i._id }
-              if obsolete.any?
-                collection.destroy_all(:_reference_id => obsolete)
+          # embeds_many
+          if inheritable.is_a?(Array)
+            collection = new_record? ? self.send(association) : self.reload.send(association)
+            existing_ids = collection.map do |a| 
+              begin
+                a._reference_id
+              rescue
               end
+            end
             
-            # embeds_one
-            else
-              if inheritable
-                attrs = inheritable_document_attributes(inheritable)
-                if doc = self.send("#{association}")
-                  update_inheritable_document(doc, attrs)
-                else
-                  self.send("create_#{association}", attrs)
-                end
-              elsif existing = self.send("#{association}")
-                existing.destroy
+            for obj in inheritable
+              attrs = inheritable_document_attributes(obj)
+              if existing_ids.include?(obj._id)
+                doc = collection.where(:_reference_id => obj._id).first
+                update_inheritable_document(doc, attrs)
+              else
+                doc = collection.create!(attrs)
+              end
+            end
+            obsolete = (existing_ids - inheritable.map { |i| i._id }).compact
+            if obsolete.any?
+              collection.delete_all(:conditions => { :_reference_id.in => obsolete })
+            end
+          
+          # embeds_one
+          else
+            if inheritable
+              attrs = inheritable_document_attributes(inheritable)
+              if doc = self.send("#{association}")
+                update_inheritable_document(doc, attrs)
+              else
+                self.send("create_#{association}", attrs)
               end
+            elsif existing = self.send("#{association}")
+              existing.destroy
             end
           end
         end
-
-        # Performs actions before saving.
-        def preprocess
-          track_mutations
-          inherit_attributes if inherit?
-        end
+      end
       
-        # Performs actions after saving.
-        def postprocess
-          inherit_documents if embed?
-          update_inheritors
-        end
-
-        # Returns true if inheritance should be applied on inheritor.
-        def inherit?
-          !_inherited and ancestor and (new_record? or ancestor_uuid_changed?)
-        end
+      # Performs actions after saving.
+      def postprocess
+        inherit_documents if inheritor? and embed?
+        update_inheritors
+      end
       
-        # Returns true if this documents has any inheritable documents.
-        def embed?
-          inheritable_documents.any?
-        end
+      # Returns true if object is an inheritor.
+      def inheritor?
+        ancestor
+      end
+      
+      # Returns true if inheritance should be applied on inheritor.
+      def inherit?
+        !_inherited and ancestor and (new_record? or ancestor_uuid_changed?)
+      end
+    
+      # Returns true if this documents has any inheritable documents.
+      def embed?
+        inheritable_documents.any?
+      end
 
-        # Stores changed attributes as #mutated_attributes unless they have been inherited recently.
-        def track_mutations
-          changed_items = new_record? ? attributes.keys : changes.keys
-          changed_items -= ACQUIRED_ATTRIBUTES
-          if inherited_attributes
-            for key, value in inherited_attributes
-              changed_items.delete(key) if value == attributes[key]
-            end
-            self.inherited_attributes = nil
-          end
-          self.mutated_attributes += changed_items
-          self.mutated_attributes.uniq!
-        end
-        
-        # Updates an given document with given attributes.
-        def update_inheritable_document(doc, attrs)
-          update_inheritable_document_attributes(doc, attrs)
-          update_inheritable_document_children(doc, attrs)
-        end
-        
-        # Updates an given document with given attributes.
-        # This will perform #update_inherited_attributes on document, if this callback method is available.
-        def update_inheritable_document_attributes(doc, attrs)
-          if doc.respond_to?(:update_inherited_attributes)
-            doc.send(:update_inherited_attributes, attrs)
-          else
-            doc.update_attributes(attrs)
-          end
-        end
-        
-        # Updates children of given embedded document.
-        # Because update_attributes won't modify the hash of children, a custom database update is needed.
-        def update_inheritable_document_children(doc, attrs)
-          inheritable_documents = self.class.inheritable_documents(doc, :keys => true)
-          idocs = attrs.only(*inheritable_documents)
-          query = {}
-          for k,v in idocs
-            query["#{doc._position}.#{k}"] = v
+      # Stores changed attributes as #mutated_attributes unless they have been inherited recently.
+      def track_mutations
+        changed_items = new_record? ? attributes.keys : changes.keys
+        changed_items -= ACQUIRED_ATTRIBUTES
+        if inherited_attributes
+          for key, value in inherited_attributes
+            changed_items.delete(key) if value == attributes[key]
           end
-          _collection.update(_selector, { "$set" => query })
-        end
-        
-        # Returns list of inheritable attributes of a given document.
-        # The list will include the _id as reference.
-        def inheritable_document_attributes(doc)
-          attrs = doc.attributes.except(*ACQUIRED_ATTRIBUTES)
-          attrs[:_reference_id] = doc._id
-          attrs
+          self.inherited_attributes = nil
         end
+        self.mutated_attributes += changed_items
+        self.mutated_attributes.uniq!
+      end
+      
+      # Updates an given document with given attributes.
+      def update_inheritable_document(doc, attrs)
+        update_inheritable_document_attributes(doc, attrs)
+        update_inheritable_document_children(doc, attrs)
+      end
       
-        # Applies changes to inheritors.
-        def update_inheritors
-          return unless inheritors.any?
-          inheritors.each(&:inherit!)
+      # Updates an given document with given attributes.
+      # This will perform #update_inherited_attributes on document, if this callback method is available.
+      def update_inheritable_document_attributes(doc, attrs)
+        if doc.respond_to?(:update_inherited_attributes)
+          doc.send(:update_inherited_attributes, attrs)
+        else
+          doc.update_attributes(attrs)
         end
-        
-        class << self
+      end
       
-          # Returns embedded documents of given document.
-          def inheritable_documents(doc, options = {})
-            keys = options[:keys]
-            collection = keys ? [] : {}
-            for name, association in doc.associations
-              next unless association.embedded?
-              if keys
-                collection << name
-              else
-                collection[name] = doc.send(name)
-              end
-            end
-            collection
-          end
+      # Updates children of given embedded document.
+      # Because update_attributes won't modify the hash of children, a custom database update is needed.
+      def update_inheritable_document_children(doc, attrs)
+        inheritable_documents = self.class.inheritable_documents(doc, :keys => true)
+        idocs = attrs.only(*inheritable_documents)
+        query = {}
+        for k,v in idocs
+          query["#{doc._position}.#{k}"] = v
         end
+        _collection.update(_selector, { "$set" => query })
+      end
+      
+      # Returns list of inheritable attributes of a given document.
+      # The list will include the _id as reference.
+      def inheritable_document_attributes(doc)
+        attrs = doc.attributes.except(*ACQUIRED_ATTRIBUTES)
+        attrs[:_reference_id] = doc._id
+        attrs
+      end
+    
+      # Applies changes to inheritors.
+      def update_inheritors
+        return unless inheritors.any?
+        inheritors.each(&:inherit!)
+      end
+      
+      # Destroys inheritors.
+      def destroy_inheritors
+        return unless inheritors.any?
+        inheritors.each(&:destroy)
       end
     end
   end