association_observers 0.0.5 → 0.0.6

data/.gitignore

@@ -15,6 +15,7 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+log/
 
 .rvmrc
 .idea

data/.travis.yml

@@ -7,6 +7,7 @@ rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
+  - 2.0.0
   - jruby
   - rbx
 script: bundle exec rake spec

data/Gemfile

@@ -5,6 +5,12 @@ group :development do
   gem "yard",       "0.8.2.1", :require => false
 end
 
+group :test do
+  gem "delayed_job_active_record", :require => false
+  gem "resque",                    :require => false
+  gem "sidekiq",                   :require => false unless RUBY_VERSION == "1.8.7"
+end
+
 gem 'activerecord'
 gem 'datamapper'
 gem 'dm-mysql-adapter'

data/README.md

@@ -169,7 +169,7 @@ The #observes method for the models accepts as argument the association being ob
 
 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:
+Second, how. Your notifier must inherit from Notifier::Base. This class provides you with hook methods you should/could redefine your way:
 
 Methods to overwrite:
 * action(observable, observer) : where you should define the behaviour which results of the observation of an event
@@ -190,10 +190,63 @@ Purpose of the Notifier is to abstract the behaviour from the Observer relations
 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.
 
+### Background Queues
+
+This gem supports the 3 most popular background queue implementations around: Delayed Job, Resque and Sidekiq. If you are
+using this gem out of Rails, you can do:
+
+       AssociationObservers::options[:queue][:engine] = :delayed_job # or :sidekiq, or :resque
+
+if in Rails, you can do it in application.rb:
+
+       module YourApp
+         class Application < Rails::Application
+           ...
+           config.association_observers.queue.engine = :delayed_job # or :sidekiq, or :resque
+           ...
+         end
+       end
+
+and that's it. Why is this important? The notification of observer collections, when you don't rewrite the #notify_many hook
+method of the notifier, takes the following approach:
+
+* Queries the collection in batches (of 50, by default)
+* Iterates over each batch
+* Performs the #update hook method on each
+
+It also takes this approach to the propagation. Batch-querying is much better than querying all at once, but you still
+load everything and perform the various iterations synchronously. If you already use one of the aforementioned background
+queues, each batch will generate a job which will be handled asynchronously. You also have the control over the batch size.
+If you want to set a new default batch size, just:
+
+       # standard
+       AssociationObservers::options[:batch_size] = 200 # or 20...
+
+       # rails way
+       module YourApp
+         class Application < Rails::Application
+           ...
+           config.association_observers.batch_size = 200 # or 20...
+           ...
+         end
+       end
+
+You can also set the queue name (default: "observers" and priority (if using delayed job) on the options, they are just another option under queue.
+
+### Ruby Support
+
+This gem is tested against the following rubies:
+
+* 1.8.7
+* 1.9.2
+* 1.9.3
+* 2.0.0
+* rubinius
+* jruby
+
 ### TODOs
 
 * Support for other ORM's (currently supporting ActiveRecord and DataMapper)
-* 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)
 * Overall spec readability
 
@@ -205,6 +258,8 @@ the ObserverMethods and the ObservableMethods, which will be included in the res
 * Support for ActiveRecord
 * Support for DataMapper
 
+* Integration with delayed job, resque and sidekiq
+
 ### Rails
 
 The observer models have to be eager-loaded for the observer/observable behaviour to be extended in the respective associations.

data/Rakefile

@@ -10,6 +10,21 @@ RSpec::Core::RakeTask.new(:active_record_spec) do |t|
   t.pattern   = "spec/activerecord/*_spec.rb"
 end
 
+RSpec::Core::RakeTask.new(:active_record_delayed_job_spec) do |t|
+  t.rspec_opts = ['--options', "\"./.rspec\""]
+  t.pattern   = "spec/activerecord/delayed_job/*_spec.rb"
+end
+
+RSpec::Core::RakeTask.new(:active_record_resque_spec) do |t|
+  t.rspec_opts = ['--options', "\"./.rspec\""]
+  t.pattern   = "spec/activerecord/resque/*_spec.rb"
+end
+
+RSpec::Core::RakeTask.new(:active_record_sidekiq_spec) do |t|
+  t.rspec_opts = ['--options', "\"./.rspec\""]
+  t.pattern   = "spec/activerecord/sidekiq/*_spec.rb"
+end
+
 RSpec::Core::RakeTask.new(:data_mapper_spec) do |t|
   t.rspec_opts = ['--options', "\"./.rspec\""]
   t.pattern   = "spec/datamapper/*_spec.rb"
@@ -17,6 +32,9 @@ end
 
 task :spec do |t|
   Rake::Task["active_record_spec"].invoke rescue (failed = true)
+  Rake::Task["active_record_delayed_job_spec"].invoke rescue (failed = true)
+  Rake::Task["active_record_resque_spec"].invoke rescue (failed = true)
+  Rake::Task["active_record_sidekiq_spec"].invoke rescue (failed = true) unless RUBY_VERSION == "1.8.7"
   Rake::Task["data_mapper_spec"].invoke rescue (failed = true)
   raise "failed" if failed
 end

data/association_observers.gemspec

@@ -25,10 +25,10 @@ Gem::Specification.new do |gem|
   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("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("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")

data/lib/association_observers.rb

@@ -7,6 +7,7 @@ require "association_observers/ruby18" if RUBY_VERSION < "1.9"
 require "active_support/core_ext/array/extract_options"
 require "active_support/core_ext/string/inflections"
 
+
 # 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
@@ -24,34 +25,30 @@ require "active_support/core_ext/string/inflections"
 #
 # @author Tiago Cardoso
 module AssociationObservers
-
-  # @abstract
-  # @return [Symbol] ORM instance method name which checks whether the record is a new instance
-  def self.check_new_record_method
-    raise "should be defined in an adapter for the used ORM"
+  autoload :Queue, "association_observers/queue"
+  module Workers
+    autoload :ManyDelayedNotification, "association_observers/workers/many_delayed_notification"
   end
 
-  # @abstract
-  # @return [Symbol] ORM collection method name to get the model of its children
-  def self.fetch_model_from_collection
-    raise "should be defined in an adapter for the used ORM"
+  def self.orm_adapter
+    raise "no adapter for your ORM"
   end
 
-  # @abstract
-  # implementation of an ORM-specifc batched each enumerator on a collection
-  def self.batched_each(collection, batch, &block)
-    raise "should be defined in an adapter for the used ORM"
+  def self.queue
+    @queue ||= Queue.instance
   end
 
-  # @abstract
-  # checks the parameters received by the observer DSL call, handles unexpected input according by triggering exceptions,
-  # warnings, deprecation messages
-  # @param [Class] observer the observer class
-  # @param [Array] observable_associations collection of the names of associations on the observer which will be observed
-  # @param [Array] notifier_classes collection of the notifiers for the observation
-  # @param [Array] observer_callbacks collection of the callbacks/methods to be observed
-  def self.validate_parameters(observer, observable_associations, notifier_classes, observer_callbacks)
-    raise "should be defined in an adapter for the used ORM"
+  @default_options = {
+      :batch_size => 50,
+      :queue => {
+        :engine => nil,
+        :name => "observers",
+        :priority => nil
+      }
+  }
+
+  def self.options
+    @options ||= @default_options.dup
   end
 
 
@@ -62,11 +59,24 @@ module AssociationObservers
 
   # Methods to be added to observer associations
   module IsObserverMethods
-    def self.included(base) ; base.extend(ClassMethods) ; end
+    def self.included(base)
+      base.extend(ClassMethods)
+      AssociationObservers::orm_adapter.class_variable_set(base, :observable_options)
+      if RUBY_VERSION < "1.9"
+        base.observable_options = AssociationObservers::Backports.hash_select(AssociationObservers::options){|k, v| [:batch_size].include?(k) }
+      else
+        base.observable_options = AssociationObservers::options.select{|k, v| [:batch_size].include?(k) }
+      end
+    end
 
     module ClassMethods
       def observer? ; true ; end
 
+      def batch_size=(val)
+        raise "AssociationObservers: it must be an integer value" unless val.is_a?(Fixnum)
+        self.observable_options[:batch_size] = val
+      end
+
       private
 
       # @abstract
@@ -139,7 +149,9 @@ module AssociationObservers
       end
     end
 
+    # blocks the observable behaviour
     def unobservable! ; @unobservable = true ; end
+    # unblocks the observable behaviour
     def observable! ; @unobservable = false ; end
 
     private
@@ -147,7 +159,7 @@ module AssociationObservers
     # 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
+      notify_observers([callback, []]) unless @unobservable
     end
   end
 
@@ -185,9 +197,7 @@ module AssociationObservers
       observer_callbacks = Array(opts[:on] || [:save, :destroy])
 
       # no observer, how are you supposed to observe?
-      AssociationObservers::validate_parameters(self, args, notifier_classes, observer_callbacks)
-
-
+      AssociationObservers::orm_adapter.validate_parameters(self, args, notifier_classes, observer_callbacks)
 
 
       notifier_classes.map!{|notifier_class|notifier_class.to_s.classify.constantize} << PropagationNotifier
@@ -198,7 +208,7 @@ module AssociationObservers
       end
 
       # 1: for each observed association, define behaviour
-      get_association_options_pairs(args).each do |klass, options|
+      get_association_options_pairs(args).each do |name, klass, options|
         klass.instance_eval do
 
           include IsObservableMethods
@@ -208,7 +218,7 @@ module AssociationObservers
           attr_reader :unobservable
 
           # load observers from this observable association
-          set_observers(notifier_classes, observer_callbacks, observer_class, (options[:as] || association_name).to_s)
+          set_observers(notifier_classes, observer_callbacks, observer_class, (options[:as] || association_name).to_s, name)
 
           # sets the callbacks to inform observers
           set_notification_on_callbacks(observer_callbacks)
@@ -229,6 +239,8 @@ end
 if defined?(Rails::Railtie) # RAILS
   require 'association_observers/railtie'
 else
-  require 'association_observers/activerecord' if defined?(ActiveRecord)
-  require 'association_observers/datamapper' if defined?(DataMapper)
+  # ORM Adapters
+  require 'association_observers/active_record' if defined?(ActiveRecord)
+  require 'association_observers/data_mapper' if defined?(DataMapper)
+
 end

data/lib/association_observers/{activerecord.rb → active_record.rb}

@@ -2,20 +2,12 @@
 if defined?(ActiveRecord)
 
   module AssociationObservers
-    def self.check_new_record_method
-      :new_record?
+    module Orm
+      autoload :ActiveRecord, "association_observers/orm/active_record"
     end
 
-    def self.fetch_model_from_collection
-      :klass
-    end
-
-    def self.batched_each(collection, batch, &block)
-      collection.find_each(:batch_size => batch, &block)
-    end
-
-    def self.validate_parameters(observer, observable_associations, notifier_names, callbacks)
-      raise "Invalid callback; possible options: :create, :update, :save, :destroy" unless callbacks.all?{|o|[:create,:update,:save,:destroy].include?(o.to_sym)}
+    def self.orm_adapter
+      @orm_adapter ||= Orm::ActiveRecord
     end
 
     # translation of AR callbacks to collection callbacks; we want to ignore the update on collections because neither
@@ -36,7 +28,12 @@ if defined?(ActiveRecord)
 
         private
 
-        def set_observers(notifiers, callbacks, observer_class, association_name)
+        # given the fetched information, it initializes the notifiers
+        # @param [Array] notifiers notifiers for the current class
+        # @param [Array] callbacks valid callbacks for the notifiers
+        # @param [Class] observer_class the class of the observer
+        # @param [Symbol] association_name the observer identifier on the observable
+        def set_observers(notifiers, callbacks, observer_class, association_name, observable_association_name)
           notifiers.each do |notifier|
             callbacks.each do |callback|
               options = {}
@@ -44,6 +41,8 @@ if defined?(ActiveRecord)
                                      self.reflect_on_association(association_name.pluralize.to_sym)
               options[:observer_class] = observer_class.base_class if observer_association.options[:polymorphic]
 
+              options[:observable_association_name] = observable_association_name
+
               self.add_observer notifier.new(callback, observer_association.name, options)
               include "#{notifier.name}::ObservableMethods".constantize if notifier.constants.map(&:to_sym).include?(:ObservableMethods)
             end
@@ -74,7 +73,7 @@ if defined?(ActiveRecord)
         private
 
         def get_association_options_pairs(association_names)
-          reflect_on_all_associations.select{ |r| association_names.include?(r.name) }.map{|r| [r.klass, r.options] }
+          reflect_on_all_associations.select{ |r| association_names.include?(r.name) }.map{|r| [r.name, r.klass, r.options] }
         end
 
         def filter_collection_associations(associations)
@@ -113,8 +112,8 @@ if defined?(ActiveRecord)
 
             # bullshit ruby 1.8 can't stringify hashes, arrays, symbols nor strings correctly
             if RUBY_VERSION < "1.9"
-              assoc_options = AssociationObservers::extended_to_s(a.options)
-              callback_options = AssociationObservers::extended_to_s(callbacks)
+              assoc_options = AssociationObservers::Backports::extended_to_s(a.options)
+              callback_options = AssociationObservers::Backports::extended_to_s(callbacks)
             else
               assoc_options = a.options.to_s
               callback_options = callbacks

data/lib/association_observers/{datamapper.rb → data_mapper.rb}

@@ -1,24 +1,12 @@
 # -*- encoding : utf-8 -*-
 if defined?(DataMapper)
   module AssociationObservers
-    def self.check_new_record_method
-      :new?
+    module Orm
+      autoload :DataMapper, "association_observers/orm/data_mapper"
     end
 
-    def self.fetch_model_from_collection
-      :model
-    end
-
-    def self.batched_each(collection, batch, &block)
-      collection.each(&block) # datamapper batches already by 500 https://groups.google.com/forum/?fromgroups=#!searchin/datamapper/batches/datamapper/lAZWFN4TWAA/G1Gu-ams_QMJ
-    end
-
-    def self.validate_parameters(observer, observable_associations, notifier_names, callbacks)
-      observable_associations.each do |o|
-        if observer.relationships[o].is_a?(DataMapper::Associations::ManyToMany::Relationship)
-          warn "this gem does not currently support observation behaviour for many to many relationships"
-        end
-      end
+    def self.orm_adapter
+      @orm_adapter ||= Orm::DataMapper
     end
 
     module IsObservableMethods
@@ -33,12 +21,15 @@ if defined?(DataMapper)
         end
         private
 
-        def set_observers(ntfs, callbacks, observer_class, association_name)
+        def set_observers(ntfs, callbacks, observer_class, association_name, observable_association_name)
           ntfs.each do |notifier|
             callbacks.each do |callback|
               options = {} # todo: use this for polymorphics
               observer_association = self.relationships[association_name]||
                                      self.relationships[association_name.pluralize]
+
+              options[:observable_association_name] = observable_association_name
+
               notifiers << notifier.new(callback, observer_association.name, options)
               include "#{notifier.name}::ObservableMethods".constantize if notifier.constants.map(&:to_sym).include?(:ObservableMethods)
             end
@@ -61,8 +52,8 @@ if defined?(DataMapper)
         private
 
 
-        def notify_observers(callback)
-          self.class.notifiers.each{|notifier| notifier.update(callback, self)}
+        def notify_observers(args)
+          self.class.notifiers.each{|notifier| notifier.update(args, self)}
         end
       end
     end
@@ -79,7 +70,7 @@ if defined?(DataMapper)
 
         def get_association_options_pairs(association_names)
           # TODO: find better way to figure out the class of the relationship entity
-          relationships.select{|r|association_names.include?(r.name)}.map{|r| [(r.is_a?(DataMapper::Associations::ManyToOne::Relationship) ? r.parent_model : r.child_model), r.options] }
+          relationships.select{|r|association_names.include?(r.name)}.map{|r| [r.name, (r.is_a?(DataMapper::Associations::ManyToOne::Relationship) ? r.parent_model : r.child_model), r.options] }
         end
 
         def filter_collection_associations(associations)

data/lib/association_observers/extensions/delayed_job.rb

@@ -0,0 +1,13 @@
+# -*- encoding : utf-8 -*-
+
+module AssociationObservers
+  class Queue
+    private
+
+    # overwriting the enqueue method. Delayed Job enqueues the jobs already itself
+    def enqueue(task, *args)
+      job = task.new(*args)
+      Delayed::Job.enqueue job, :queue => AssociationObservers::options[:queue][:name], :priority => AssociationObservers::options[:queue][:priority] || Delayed::Worker.default_priority
+    end
+  end
+end