vidibus-inheritance 0.3.6

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Andre Pankratz
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,93 @@
+= vidibus-inheritance
+
+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.
+
+
+== Installation
+
+Add the dependency to the Gemfile of your application:
+
+  gem "vidibus-inheritance"
+
+Then call bundle install on your console.
+
+
+== Usage
+
+Include the Vidibus::Uuid::Inheritance module in your Mongoid model:
+
+  class Model
+    include Mongoid::Document
+    include Vidibus::Uuid::Mongoid
+    include Vidibus::Inheritance::Mongoid
+    field :name
+  end
+  
+To establish a inheritance relationship, add ancestor to a model of same class:
+  
+  ancestor = Model.create(:name => "Anna")
+  
+  # To establish a relation, call #inherit_from!
+  inheritor = Model.new
+  inheritor.inherit_from!(ancestor)
+  
+  # ...or set :ancestor attribute
+  inheritor = Model.create(:ancestor => ancestor)
+
+
+=== Mongoid configuration
+
+When inheriting, the attribute :_reference_id will be set on embedded documents of inherited objects. So make sure this field is available or Mongoid is configured to allow dynamic fields. Add to config/mongoid.yml:
+
+  allow_dynamic_fields: true
+
+
+=== Acquired attributes
+
+All attributes will be inherited, except these ACQUIRED_ATTRIBUTES:
+
+  _id
+  uuid
+  ancestor_uuid
+  mutated_attributes
+  mutated
+  created_at
+  updated_at
+  version
+  versions
+
+
+=== Manage mutations of embedded documents
+
+All custom changes on inherited objects will be stored in #mutated_attributes. On embedded documents of inherited objects, however, mutations of attributes will not be tracked. But you may flag a document as mutated when applying custom values:
+
+  class Job
+    include Mongoid::Document
+    field :salary
+    field :mutated, :type => Boolean
+    embedded_in :model, :inverse_of => :jobs
+  
+    def set_custom_salary(amount)
+      self.salary = amount
+      self.mutated = true
+    end
+  end
+
+To control how inherited data will be updated, you may define a callback method and check #mutated:
+
+  def update_inherited_attributes(attrs)
+    attrs.delete("salary") if mutated? # preserve custom salary
+    update_attributes(attrs)
+  end
+
+
+== Copyright
+
+Copyright (c) 2010 Andre Pankratz. See LICENSE for details.
+
+
+== Thank you!
+
+The development of this gem was sponsored by Käuferportal: http://www.kaeuferportal.de

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "vidibus-inheritance"
+    gem.summary = %Q{Provides inheritance for models.}
+    gem.description = %Q{This gem allows inheritance of objects for Rails 3 with Mongoid. It will update all attributes and embedded documents of inheritors when ancestor gets changed.}
+    gem.email = "andre@vidibus.com"
+    gem.homepage = "http://github.com/vidibus/vidibus-inheritance"
+    gem.authors = ["Andre Pankratz"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "relevance-rcov"
+    gem.add_development_dependency "mongoid", "= 2.0.0.beta.15"
+    gem.add_development_dependency "rr"
+    gem.add_dependency "vidibus-core_extensions"
+    gem.add_dependency "vidibus-uuid"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |t|
+  t.spec_files = FileList['spec/vidibus/**/*_spec.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', '^spec,/gems/']
+end
+
+task :spec => :check_dependencies
+task :default => :spec
+
+require "rake/rdoctask"
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?("VERSION") ? File.read("VERSION") : ""
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "vidibus-uuid #{version}"
+  rdoc.rdoc_files.include("README*")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+  rdoc.options << "--charset=utf-8"
+end

data/TODO

@@ -0,0 +1,5 @@
+Use delayed_job
+
+Use uuid for children to ensure portability across the network?
+
+Get ACQUIRED_ATTRIBUTES as class variable from each document, if available

data/VERSION

@@ -0,0 +1 @@
+0.3.6

data/lib/vidibus/inheritance/mongoid.rb

@@ -0,0 +1,239 @@
+module Vidibus
+  module Inheritance
+    module Mongoid
+      extend ActiveSupport::Concern
+
+      ACQUIRED_ATTRIBUTES = %w[_id uuid ancestor_uuid mutated_attributes mutated created_at updated_at version versions]
+      
+      included do
+        attr_accessor :inherited_attributes, :_inherited
+        attr_protected :mutated_attributes, :mutated
+        
+        field :ancestor_uuid
+        field :mutated_attributes, :type => Array, :default => []
+        field :mutated, :type => Boolean
+
+        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
+        end
+      
+        # Returns ancestor object by uuid.
+        def ancestor
+          @ancestor ||= begin
+            self.class.where(:uuid => ancestor_uuid).first if ancestor_uuid
+          end
+        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
+        #
+        def inherit!(options = {})
+          self.inherit_attributes(options)
+          self.save!
+        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
+      
+        # Returns list of objects that inherit from this ancestor.
+        def inheritors
+          self.class.where(:ancestor_uuid => uuid).to_a
+        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 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)
+        end
+        
+        # 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)
+              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
+        end
+
+        # Performs actions before saving.
+        def preprocess
+          track_mutations
+          inherit_attributes if inherit?
+        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
+      
+        # 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
+          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
+        
+        class << self
+      
+          # 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
+        end
+      end
+    end
+  end
+end

data/lib/vidibus/inheritance/validators/ancestor_validator.rb

@@ -0,0 +1,13 @@
+module Vidibus
+  module Inheritance
+    module Validators
+      class AncestorValidator < ActiveModel::EachValidator      
+        def validate_each(record, attribute, value)
+          unless value.is_a?(record.class)
+            record.errors[attribute] << "must be a #{record.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vidibus/inheritance/validators.rb

@@ -0,0 +1,4 @@
+require "inheritance/validators/ancestor_validator"
+
+# Add AncestorValidator
+ActiveModel::Validations.send(:include, Vidibus::Inheritance::Validators)

data/lib/vidibus/inheritance.rb

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

data/lib/vidibus-inheritance.rb

@@ -0,0 +1,3 @@
+$:.unshift(File.join(File.dirname(__FILE__), "..", "lib", "vidibus"))
+require "vidibus-core_extensions"
+require "inheritance"

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--color
+--format nested

data/spec/spec_helper.rb

@@ -0,0 +1,32 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
+
+require "rubygems"
+require "active_support/core_ext"
+require "spec"
+require "mongoid"
+require "vidibus-uuid"
+require "vidibus-inheritance"
+require "rr"
+
+Mongoid.configure do |config|
+  name = "vidibus-inheritance_test"
+  host = "localhost"
+  config.master = Mongo::Connection.new.db(name)
+end
+
+Spec::Runner.configure do |config|  
+  config.mock_with RR::Adapters::Rspec
+  config.before(:each) do
+    Mongoid.master.collections.select { |c| c.name != "system.indexes" }.each(&:drop)  
+  end
+end
+
+# Helper for stubbing time. Define String to be set as Time.now.
+# example: stub_time!('01.01.2010 14:00')
+# example: stub_time!(2.days.ago)
+def stub_time!(string = nil)
+  now = string ? Time.parse(string.to_s) : Time.now
+  stub(Time).now { now }
+  now
+end