association_observers 0.0.3

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+.rvmrc
+.idea
+vendor/bundler_gems

data/.pryrc

@@ -0,0 +1,24 @@
+Pry.config.prompt = proc do |obj, level, _|
+  prompt = ""
+  prompt << "#{Rails.version}@" if defined?(Rails)
+  prompt << "sinatra@" if defined?(Sinatra)
+  prompt << "#{RUBY_VERSION}"
+  "#{prompt} (#{obj})> "
+end
+
+Pry.config.exception_handler = proc do |output, exception, _|
+  output.puts "\e[31m#{exception.class}: #{exception.message}"
+  output.puts "from #{exception.backtrace.first}\e[0m"
+end
+
+
+
+begin
+  require "awesome_print"
+  Pry.config.print = proc {|output, value| Pry::Helpers::BaseHelpers.stagger_output("=> #{value.ai}", output)}
+rescue LoadError => err
+   warn "=> Unable to load awesome_print"
+end
+
+
+require "./lib/association_observers.rb"

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--profile

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+notifications:
+  disabled: true
+only:
+  - master
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby
+  - rbx
+script: bundle exec rspec spec
+before_script:
+  - mysql -e 'create database association_observers;'

data/Gemfile

@@ -0,0 +1,20 @@
+source 'https://rubygems.org'
+gemspec
+
+group :development do
+  gem "yard",       "0.8.2.1", :require => false
+end
+
+gem 'activerecord'
+
+platforms :ruby do
+  gem 'mysql2'
+end
+
+
+platforms :jruby do
+  gem 'jruby-openssl'
+  gem 'activerecord-jdbc-adapter'
+  gem 'activerecord-jdbcsqlite3-adapter'
+  gem 'jdbc-mysql'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Tiago Cardoso
+
+MIT License
+
+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.md

@@ -0,0 +1,214 @@
+# AssociationObservers
+
+This is an alternative implementation of the observer pattern. As you may know, Ruby (and Rails/ActiveRecord) already have an
+implementation of it. This implementation is a variation of the pattern, so it is not supposed to supersede the existing
+implementations, but "complete" them for the specific use-cases addressed.
+
+[![Build Status](https://travis-ci.org/TiagoCardoso1983/association_observers.png?branch=master)](https://travis-ci.org/TiagoCardoso1983/association_observers)
+
+
+## Comparison with the Observer Pattern
+
+The Observer Pattern clearly defines two roles: the observer and the observed. The observer registers itself by the
+observed. The observed decides when (for which "actions") to notify the observer. The observer knows what to do when notified.
+
+What's the limitation? The observed has to know when and whom to notify. The observer has to know what to do. For this
+logic to be implemented for two other separate entities, behaviour has to be copied from one place to the other. So, why
+not delegate this information (to whom, when, behaviour) to a third role, the notifier?
+
+## Comparison with Ruby Observable library
+
+Great library, which works great for POROs, but not for models (specifically ActiveRecord, which overwrites a lot of its
+functionality)
+
+## Comparison with ActiveRecord Observers
+
+Observers there are external entities which observe models. They don't exactly work as links between two models, just
+extract functionality (callbacks) which would otherwise flood the model. For that, they're great. For the rest, not really.
+
+
+### Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'association_observers'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install association_observers
+
+### Usage
+
+Here is a functional example:
+
+       require 'logger'
+
+       LOGGER = Logger.new(STDOUT)
+
+       # Notifiers
+       class HaveSliceNotifier < Notifier::Base
+
+         def action(cake, kid)
+           cake.update_column(:slices, cake.slices - 1)
+           cake.destroy if cake.slices == 0
+           kid.increment(:slices).save
+         end
+
+       end
+
+       class BustKidsAssNotifier < Notifier::Base
+
+         module ObserverMethods
+           def bust_kids_ass!
+             LOGGER.info("Slam!!")
+           end
+         end
+
+         module ObservableMethods
+           def is_for_grandpa?
+             true # it is always for grandpa
+           end
+         end
+
+         def conditions(cake, mom)
+           cake.is_for_grandpa?
+         end
+
+         def action(cake, mom)
+           mom.bust_kids_ass!
+         end
+
+       end
+
+       class TellKidHesFatNotifier < Notifier::Base
+
+         module ObservableMethods
+
+           def cry!
+             LOGGER.info(":'(")
+           end
+
+           def throw_slices_away!
+             update_column(:slices, 0)
+           end
+         end
+
+         def conditions(kid, mom)
+           kid.slices > 20
+         end
+
+         def action(kid, mom)
+           LOGGER.info("Hey Fatty, BEEFCAKE!!!!!")
+           kid.cry!
+           kid.throw_slices_away!
+         end
+
+       end
+
+
+       # TABLES
+
+       ActiveRecord::Schema.define do
+         create_table :cakes, :force => true do |t|
+           t.integer :slices
+           t.integer :mom_id
+         end
+         create_table :kids, :force => true do |t|
+           t.integer :mom_id
+           t.integer :slices, :default => 0
+         end
+         create_table :moms, :force => true do |t|
+         end
+       end
+
+       # ENTITIES
+
+       class Cake < ActiveRecord::Base
+
+         def self.default_slices ; 8 ; end
+         belongs_to :mom
+         has_one :kid, :through => :mom
+         before_create do |record|
+           record.slices ||= record.class.default_slices
+         end
+       end
+
+       class Mom < ActiveRecord::Base
+         has_one :kid
+         has_many :cakes
+       end
+
+       class Kid < ActiveRecord::Base
+         belongs_to :mom
+         has_many :cakes, :through => :mom
+
+         observes :cakes, :notifier => :have_slice, :on => :create
+       end
+
+       class Mom < ActiveRecord::Base
+         observes :cakes, :on => :destroy, :notifier => :bust_kids_ass
+         observes :kid, :on => :update, :notifier => :tell_kid_hes_fat
+       end
+
+You can find this under the examples.
+
+The #observes method for the models accepts as argument the association being observed and a set of options:
+
+* as : if the association is polymorphic, then this parameter has to be filled with the name by which the observer is recognized by the observed
+* on : accepts one event or a set of events to observe (:create, :update, :save, :destroy) for the observed association (default: :save)
+* notifier(s?): accepts one notifier or a set of notifiers that will handle the events; notifier name has to match the name of the notifier being defined by yourself;
+  if you don't set any notifier, then the events on the observed will only propagate to the observers of the observer (if it is being observed)
+
+
+The other important task is to define your own notifiers. First, where. For Rails, the gem expects a "notifiers" folder to exist under the "app" folder.
+Everywhere else, it's entirely up to you where you should define them.
+Second, how. Your notifier must inherit from Notifier::Base. This class provides you with an API you should define your way:
+
+Methods to overwrite:
+* action(observable, observer) : where you should define the behaviour which results of the observation of an event
+* conditions(observable, observer) : checks whether the action should be run (defaults to true if not overwritten)
+
+Additionally, you can optimize the behaviour for collection associations. Let's say a brand has many products which know
+its owner, and when the brand changes from owner, you want to update a certain flag on products. Per default, the action
+ will be run individually for every product. If we are talking about DB statements and 100 products, it will be 100 sequential
+ statements... That's a drag if you can accomplish that in one DB statement. for that, you can overwrite these two methods:
+
+ * notify_many(observable, observers)
+ * conditions_many(observable, observers)
+
+ the observers parameters is a container of not-yet loaded collection associations. Check your ORM's documentation to know what you can
+ do with it and whether you can achieve your result without populating it (there is such a use under the examples).
+
+Purpose of the Notifier is to abstract the behaviour from the Observer relationship between associations. But if you still
+need to complement/overwrite behaviour from your observer/observable models, you can write it in notifier-specific modules,
+the ObserverMethods and the ObservableMethods, which will be included in the respective models.
+
+### TODOs
+
+* Support for other ORM's (currently only supporting ActiveRecord)
+* Support for other Message Queue libraries (only supporting DelayedJob, rescue, everything that "#delay"s)
+* Action routine definition on the "#observes" declaration (sometimes one does not need the overhead of writing a notifier)
+* Observe method calls (currently only observing model callbacks)
+* Overall spec readability
+
+### Rails
+
+The observer models have to be eager-loaded for the observer/observable behaviour to be extended in the respective associations.
+It is kind of a drag, but a drag the Rails Observers already suffer from (these have to be declared in the application configuration).
+
+### Non-Rails
+
+If you are auto-loading your models, the same logic from the paragraph above applies. If you are requiring your models,
+ just proceed, this is not your concern :)
+
+### Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/gem_tasks"
+
+task :default do ;; end

data/association_observers.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'association_observers/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "association_observers"
+  gem.version       = AssociationObservers::VERSION
+  gem.authors       = ["Tiago Cardoso"]
+  gem.email         = ["tiago@restorm.com"]
+  gem.description   = %q{This is an alternative implementation of the observer pattern. As you may know, Ruby (and Rails/ActiveRecord) already have an
+  implementation of it. This implementation is a variation of the pattern, so it is not supposed to supersede the existing
+  implementations, but "complete" them for the specific use-cases addressed.}
+  gem.summary       = %q{The Observer Pattern clearly defines two roles: the observer and the observed. The observer registers itself by the
+  observed. The observed decides when (for which "actions") to notify the observer. The observer knows what to do when notified.
+
+  What's the limitation? The observed has to know when and whom to notify. The observer has to know what to do. For this
+  logic to be implemented for two other separate entities, behaviour has to be copied from one place to the other. So, why
+  not delegate this information (to whom, when, behaviour) to a third role, the notifier?}
+  gem.homepage      = "https://github.com/TiagoCardoso1983/association_observers"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_development_dependency("rake",["~> 0.9.2.2"])
+  gem.add_development_dependency("rack-test",["=0.6.2"])
+  gem.add_development_dependency("rspec",["~> 2.11.0"])
+  gem.add_development_dependency("database_cleaner",["=0.8.0"])
+  gem.add_development_dependency("colorize",["=0.5.8"])
+  gem.add_development_dependency("pry")
+  gem.add_development_dependency("pry-doc")
+  gem.add_development_dependency("awesome_print")
+end

data/database.yml

@@ -0,0 +1,5 @@
+activerecord:
+  adapter: mysql2
+  encoding: utf8
+  username: root
+  database: association_observers

data/lib/association_observers.rb

@@ -0,0 +1,199 @@
+# -*- encoding : utf-8 -*-
+require "association_observers/version"
+require "association_observers/notifiers/base"
+require "association_observers/notifiers/propagation_notifier"
+
+require "association_observers/ruby18" if RUBY_VERSION < "1.9"
+
+# Here it is defined the basic behaviour of how observer/observable model associations are set. There are here three
+# main roles defined: The observer associations, the observable associations, and the notifiers (the real observers).
+# Observer Associations: those are the associations of an observable which will be "listening/observing" to updates
+#
+# Observable Associations: those are the associations of an observer which will trigger "listening/observing" events on these
+#
+# Notifiers: These are the handlers which will implement the behaviour desired, knowing who observes and who is observed
+#
+# Purpose of these role definitions is to separate the listening/observing behaviour from the implementation of the logic
+# associated to it. Examples of these: model A has many Bs. The Bs from A are so many that you'd like to want to store
+# a count of the Bs on A. For that you would like A to be informed each time a B is added/deleted, so you could update
+# the counter accordingly. So in this case, A observes B, and B is observed by A. But The CounterNotifier, which is an
+# entity independent from A and B, will implement the logic of updating the counter from Bs on A. This way we can achieve
+# multiple behaviour implementation.
+#
+# @author Tiago Cardoso
+module AssociationObservers
+  # translation of AR callbacks to collection callbacks; we want to ignore the update on collections because neither
+  # add nor remove shall be considered an update event in the observables
+  # @example
+  #   class RichMan < ActiveRecord::Base
+  #     has_many :cars
+  #     observes :cars, :on => :update
+  #     ...
+  #   end
+  #
+  #   in this example, for instance, the rich man wants only to be notified when the cars are update, not when he
+  #   gets a new one or when one of them goes to the dumpster
+  COLLECTION_CALLBACKS_MAPPER = {:create => :add, :save => :add, :destroy => :remove}
+
+  # Methods to be added to observer associations
+  module IsObserverMethods
+    def self.included(base) ; base.extend(ClassMethods) ; end
+
+    module ClassMethods
+      def observer? ; true ; end
+    end
+  end
+
+  # Methods to be added to observable associations
+  module IsObservableMethods
+    def self.included(base) ; base.extend(ClassMethods) ; end
+
+    module ClassMethods
+      def observable? ; true ; end
+    end
+
+    def unobservable! ; @unobservable = true ; end
+    def observable! ; @unobservable = false ; end
+
+    private
+
+    # informs the observers that something happened on this observable, passing all the observers to it
+    # @param [Symbol] callback key of the callback being notified; only the observers for this callback will be run
+    def notify! callback
+      notify_observers(callback) unless @unobservable
+    end
+  end
+
+  module InstanceMethods
+    def observer? ; self.class.observer? ; end
+    def observable? ; self.class.observable? ; end
+  end
+
+  module ClassMethods
+    def observer? ; false ; end
+    def observable? ; false ; end
+
+    # DSL method which triggers all the behaviour. It sets self as an observer association from defined observable
+    # associations in it (these have to be defined in the model).
+    #
+    # @param [Symbol [, Symbol...]] args the self associations which will be observed
+    # @param [Hash] opts additional options
+    # @option opts [Symbol] :as name of the polymorphic association on the observables if it is defined like that
+    # @option opts [Symbol, Array] :observers name of the observers to be applied (in underscore notation: EmailNotifier would be :email_notifier)
+    # @option opts [Symbol, Array] :on which callbacks should the observers be aware of (options are :create, :save and :destroy; callback triggered will always be an after_)
+    def observes(*args)
+      opts = args.extract_options!
+      observer_class = self
+
+      plural_associations = args.select{ |arg| self.reflections[arg].collection? }
+
+      association_name = (opts[:as] || self.name.demodulize.underscore).to_s
+      notifier_classes = Array(opts[:notifiers] || opts[:notifier]).map{|notifier| notifier.to_s.end_with?("_notifier") ? notifier : "#{notifier}_notifier".to_s }
+      observer_callbacks = Array(opts[:on] || [:save, :destroy])
+
+      # no observer, how are you supposed to observe?
+      raise "Invalid callback; possible options: :create, :update, :save, :destroy" unless observer_callbacks.all?{|o|[:create,:update,:save,:destroy].include?(o.to_sym)}
+
+      # standard observer association methods
+      include IsObserverMethods
+
+      notifier_classes.map!{|notifier_class|notifier_class.to_s.classify.constantize} << PropagationNotifier
+
+      # observer association methods per observer
+      notifier_classes.each do |notifier_class|
+        include "#{notifier_class.name}::ObserverMethods".constantize if notifier_class.constants.map(&:to_sym).include?(:ObserverMethods)
+      end
+
+      # 1: for each observed association, define behaviour
+      self.reflect_on_all_associations.select{ |r| args.include?(r.name) }.map{|r| [r.klass, r.options] }.each do |klass, options|
+        klass.instance_eval do
+
+          include ActiveModel::Observing
+
+          # load observers from this observable association
+          observer_association_name = (options[:as] || association_name).to_s
+          notifier_classes.each do |notifier_class|
+            observer_callbacks.each do |callback|
+              options = {}
+              observer_association = self.reflect_on_association(observer_association_name.to_sym) ||
+                                     self.reflect_on_association(observer_association_name.pluralize.to_sym)
+              options[:observer_class] = observer_class.base_class if observer_association.options[:polymorphic]
+
+              self.add_observer notifier_class.new(callback, observer_association.name, options)
+              include "#{notifier_class.name}::ObservableMethods".constantize if notifier_class.constants.map(&:to_sym).include?(:ObservableMethods)
+            end
+          end
+
+          # sets the callbacks to inform observers
+          observer_callbacks.each do |callback|
+            if [:create, :update].include?(callback)
+              real_callback = :save
+              callback_opts = {:on => callback}
+            else
+              real_callback = callback
+              callback_opts = {}
+            end
+            send("after_#{real_callback}", callback_opts) do
+              notify! callback
+            end
+          end
+
+          attr_reader :unobservable
+
+          include IsObservableMethods
+        end
+
+      end
+
+      # 2. for each collection association, insert after add and after remove callbacks
+
+      # first step is defining the methods which will be called by the collection callbacks.
+      callback_procs = observer_callbacks.map do |callback|
+        notifier_classes.map do |notifier_class|
+          routine_name = :"__observer_#{callback}_callback_for_#{notifier_class.name.demodulize.underscore}__"
+          class_eval <<-END
+            def #{routine_name}(element)
+              callback = element.class.observer_instances.detect do |notifier|
+                notifier.class.name == '#{notifier_class}' and notifier.callback == :#{callback}
+              end
+              callback.notify(element, [self]) unless callback.nil?
+            end
+            private :#{routine_name}
+          END
+          [callback, routine_name]
+        end
+      end.flatten(1)
+
+      # second step is redefining the associations with the proper callbacks to be triggered
+      plural_associations.each do |assoc|
+        a = self.reflect_on_association(assoc)
+        callbacks = Hash[callback_procs.group_by{|code, proc| COLLECTION_CALLBACKS_MAPPER[code] }.reject{|k, v| k.nil? }.map{ |code, val| [:"after_#{code}", val.map(&:last)] }]
+        next if callbacks.empty?
+        # this snippet takes care that the array of callbacks which will get inserted in the association will not
+        # overwrite whatever callbacks you may have already defined
+        callbacks.each do |callback, procs|
+          callbacks[callback] += Array(a.options[callback])
+        end
+
+        if RUBY_VERSION < "1.9"
+          assoc_options = AssociationObservers::extended_to_s(a.options)
+          callback_options = AssociationObservers::extended_to_s(callbacks)
+        else
+          assoc_options = a.options.to_s
+          callback_options = callbacks
+        end
+
+        class_eval <<-END
+          #{a.macro} :#{assoc}, #{assoc_options}.merge(#{callback_options})
+        END
+      end
+
+    end
+  end
+end
+
+if defined?(Rails::Railtie) # RAILS
+  require 'association_observers/railtie'
+else
+  require 'association_observers/activerecord'
+end