association_observers 0.0.5 → 0.0.6

data/lib/association_observers/extensions/resque.rb

@@ -0,0 +1,30 @@
+# -*- encoding : utf-8 -*-
+
+module AssociationObservers
+  module Workers
+    class ManyDelayedNotification
+      @queue = AssociationObservers::options[:queue][:name].to_sym
+
+      alias :standard_initialize :initialize
+      def initialize(*args)
+        standard_initialize(*args)
+        # notifier has been dumped two times, reset it here
+        @notifier = args.last
+      end
+
+      def self.perform(*args)
+        self.new(*args).perform
+      end
+    end
+  end
+
+  class Queue
+    private
+
+    # overwriting of the enqueue method, using the Resque enqueue method already
+    def enqueue(task, *args)
+      Resque.enqueue(task, *args[0..-2] << Marshal.dump(args.last))
+    end
+  end
+end
+

data/lib/association_observers/extensions/sidekiq.rb

@@ -0,0 +1,32 @@
+# -*- encoding : utf-8 -*-
+module AssociationObservers
+  module Workers
+    class ManyDelayedNotification
+      include Sidekiq::Worker
+
+      sidekiq_options :queue => AssociationObservers::options[:queue][:name].to_sym
+
+      alias :perform_action! :perform
+      alias :standard_initialize :initialize
+
+      def initialize ; ; end
+
+      def perform(*args)
+        standard_initialize(*args)
+        # notifier has been dumped two times, reset it here
+        @notifier = args.last
+        perform_action!
+      end
+    end
+  end
+
+  class Queue
+    private
+
+    # overwriting of the method. Sidekiq workers use a method called perform_async
+    def enqueue(task, *args)
+      task.perform_async(*args[0..-2] << Marshal.dump(args.last))
+    end
+  end
+end
+

data/lib/association_observers/notifiers/base.rb

@@ -2,14 +2,19 @@
 module Notifier
   class Base
     attr_reader :callback, :observers, :options
-    # @param [Symbol] callback callback key to which this observer will respond (:create, :update, :save, :destroy)
-    # @param [Array] observers list of observers asssociations in the symbolized-underscored form (SimpleAssociation => :simple_association)
-    # @param [Hash] options additional options for the notifier
-    # @option options [Class] :observer_class the class of the observer (important when the observer association is polymorphic)
-    def initialize(callback, observers, options = {})
-      @callback = callback
-      @observers = Array(observers)
-      @options = options
+    # @overload initialize(callback, observers, options)
+    #   Initializes a usable notifier
+    #   @param [Symbol] callback callback key to which this observer will respond (:create, :update, :save, :destroy)
+    #   @param [Array] observers list of observers asssociations in the symbolized-underscored form (SimpleAssociation => :simple_association)
+    #   @param [Hash] options additional options for the notifier
+    #   @option options [Class] :observer_class the class of the observer (important when the observer association is polymorphic)
+    # @overload initialize
+    #   Initializes a ghost notifier for idempotent method extraction purposes
+    def initialize(*args)
+      @options = args.extract_options!
+      raise "something is wrong, the notifiers was wrongly initialized" unless args.size == 0 or args.size == 2
+      @callback, @observers = args
+      @observers = Array(@observers)
     end
 
 
@@ -17,11 +22,14 @@ module Notifier
     # implemented as a filter where it is seen if the triggered callback corresponds to the callback this observer
     # responds to
     #
-    # @param [Symbol] callback key from the callback that has just been triggered
+    # @param [Array] args [callback: key from the callback that has just been triggered, to_exclude: list of associations to exclude from the notifying chain]
     # @param [Object] observable the object which triggered the callback
-    def update(callback, observable)
-      return unless callback == @callback
-      observers = @options.has_key?(:observer_class) ? self.observers.select{|assoc| observable.association(assoc).klass == @options[:observer_class] } : self.observers
+    def update(args, observable)
+      callback, to_exclude = args
+      return unless accepted_callback?(callback)
+      observers = self.observers
+      observers = observers.reject{|assoc| to_exclude.include?(assoc) }
+      observers = observers.select{|assoc| observable.association(assoc).klass == @options[:observer_class] } if @options.has_key?(:observer_class)
       notify(observable, observers.map{|assoc| observable.send(assoc)}.compact)
     end
 
@@ -39,14 +47,24 @@ module Notifier
 
     private
 
+    # helper method which checks whether the given callback is compatible with the notifier callback.
+    # Example: if the notifier is marked for :save, then :create is a valid callback.
+    #          if the notifier is marked for :update, then :create is not a valid callback.
+    def accepted_callback?(callback)
+      case @callback
+        when :save then [:create, :update, :save].include?(callback)
+        when :update then [:update, :save].include?(callback)
+        else callback == @callback
+      end
+    end
+
     # Notifies all observers; filters the observers into two groups: one-to-many and one-to-one collections
     # @param [Object] observable the object which is notifying
     # @param [Array] observers the associated observers which will be notified
-    def notify(observable, observers, &block)
+    def notify(observable, observers)
       many, ones = observers.partition{|obs| obs.respond_to?(:size) }
-      action = block_given? ? block : method(:action)
-      notify_many(observable, many, &action)
-      notify_ones(observable, ones, &action)
+      notify_many(observable, many)
+      notify_ones(observable, ones)
     end
 
     # TODO: make this notify private as soon as possible again
@@ -58,9 +76,7 @@ module Notifier
     # @param [Array[ActiveRecord::Relation]] many_observers the observers which will be notified; each element represents a one-to-many relation
     def notify_many(observable, many_observers)
       many_observers.each do |observers|
-        AssociationObservers::batched_each(observers, 10) do |observer|
-          yield(observable, observer) if conditions(observable, observer)
-        end if conditions_many(observable, observers)
+        AssociationObservers::queue.enqueue_notifications(observers, observable, self) if conditions_many(observable, observers)
       end
     end
 
@@ -69,9 +85,18 @@ module Notifier
     # @param [Object] observable the object which is notifying
     # @param [Array[Object]] observers the observers which will be notified; each element represents a one-to-one association
     def notify_ones(observable, observers)
-      observers.each do |observer|
-        yield(observable, observer) if conditions(observable, observer)
+      observers.each do |uniq_observer|
+        AssociationObservers::queue.enqueue_notifications([uniq_observer], observable, self,
+                                                          :batch_size => 1, :klass => uniq_observer.class)
       end
     end
+
+    # conditionally executes the notifier action. This is explicitly here so that its call can be queued and
+    # the background worker can call it. I don't like it, but it was decided this way because we can't marshal
+    # procs, therefore we can't pass procs to the workers. It is a necessary evil.
+    def conditional_action(observable, observer)
+      action(observable, observer) if conditions(observable, observer)
+    end
+
   end
 end

data/lib/association_observers/notifiers/propagation_notifier.rb

@@ -5,12 +5,12 @@
 class PropagationNotifier < Notifier::Base
 
   def conditions(observable, observer) ; observer.observable? ; end
-  def conditions_many(observable, observers) ; observers.send(AssociationObservers::fetch_model_from_collection).observable? ; end
+  def conditions_many(observable, observers) ; AssociationObservers::orm_adapter.collection_class(observers).observable? ; end
 
   # propagates the message to the observer's observer if the
   # observer is indeed observed by any entity
   def action(observable, observer, callback=@callback)
-    (observer.send(AssociationObservers::check_new_record_method) or not observer.respond_to?(:delay)) ? observer.send(:notify_observers, callback) : observer.delay.notify_observers(callback)
+    observer.send(:notify_observers, [callback, [@options[:observable_association_name] ] ])
   end
 
 end

data/lib/association_observers/orm/active_record.rb

@@ -0,0 +1,48 @@
+# -*- encoding : utf-8 -*-
+require "association_observers/orm/base"
+
+module AssociationObservers
+  module Orm
+    class ActiveRecord < Base
+      def self.find(klass, primary_key)
+        klass.find_by_id(primary_key)
+      end
+
+      # @see AssociationObservers::Orm::Base.find_all
+      def self.find_all(klass, attributes)
+        klass.send("find_all_by_#{attributes.keys.join('_and_')}", *attributes.values)
+      end
+
+      # @see AssociationObservers::Orm::Base.get_field
+      def self.get_field(collection, attrs={})
+        collection.is_a?(::ActiveRecord::Relation) or collection.respond_to?(:proxy_association) ?
+        collection.limit(attrs[:limit]).offset(attrs[:offset]).pluck(*attrs[:fields].map{|attr| "#{collection_class(collection).arel_table.name}.#{attr}" }) :
+        super
+      end
+
+      # @see AssociationObservers::Orm::Base.collection_class
+      def self.collection_class(collection)
+        collection.klass
+      end
+
+      # @see AssociationObservers::Orm::Base.class_variable_set
+      def self.class_variable_set(klass, name)
+        klass.cattr_accessor name
+      end
+
+      # @see AssociationObservers::Orm::Base.batched_each
+      def self.batched_each(collection, batch, &block)
+        if collection.is_a?(::ActiveRecord::Relation) ?
+           collection.find_each(:batch_size => batch, &block) :
+           super
+        end
+      end
+
+    # @see AssociationObservers::Orm::Base.validate_parameters
+      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)}
+      end
+    end
+  end
+end
+

data/lib/association_observers/orm/base.rb

@@ -0,0 +1,61 @@
+# -*- encoding : utf-8 -*-
+module AssociationObservers
+  module Orm
+    class Base
+      # finds record by primary key
+      # @abstract
+      #
+      # @param [Class] klass the class of the record to look for
+      # @param [Object] primary_key primary key of the record to look for
+      # @return [Symbol] ORM class method that fetches records from the DB
+      def self.find(klass, primary_key)
+        raise "should be defined in an adapter for the used ORM"
+      end
+
+      # finds all records which match the given attributes
+      # @abstract
+      #
+      # @param [Class] klass the class of the records to look for
+      # @param [Hash] attributes list of key/value associations which have to be matched by the found records
+      # @return [Symbol] ORM class method that fetches records from the DB
+      def self.find_all(klass, attributes)
+        raise "should be defined in an adapter for the used ORM"
+      end
+
+      # @param [Array] collection records to iterate through
+      # @param [Array] attrs attributes to fetch for
+      # @return [Array] a collection of the corresponding values to the given keys for each record
+      def self.get_field(collection, attrs)
+        attrs[:offset] == 0 ? collection.map{|elem| elem.send(*attrs[:fields])} : []
+      end
+
+      # @abstract
+      # @param [Array] collection objects container
+      # @return [Symbol] ORM collection method name to get the model of its children
+      def self.collection_class(collection)
+        raise "should be defined in an adapter for the used ORM"
+      end
+
+      # implementation of a batched each enumerator on a collection
+      #
+      # @param [Array] collection records to batch through
+      def self.batched_each(collection, batch=1, &block)
+        batch > 1 ?
+        collection.each_slice(batch) { |batch| batch.each(&block) } :
+        collection.each(&block)
+      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"
+      end
+
+    end
+  end
+end

data/lib/association_observers/orm/data_mapper.rb

@@ -0,0 +1,61 @@
+# -*- encoding : utf-8 -*-
+require "association_observers/orm/base"
+
+module AssociationObservers
+  module Orm
+    class DataMapper < Base
+      def self.find(klass, primary_key)
+        klass.get(primary_key)
+      end
+
+      # @see AssociationObservers::Orm::Base.find_all
+      def self.find_all(klass, attributes)
+        klass.all(attributes)
+      end
+
+      # @see AssociationObservers::Orm::Base.get_field
+      def self.get_field(collection, attrs={})
+        collection.is_a?(::DataMapper::Collection) ?
+        collection.all(attrs) :
+        super
+      end
+
+      # @see AssociationObservers::Orm::Base.collection_class
+      def self.collection_class(collection)
+        collection.model
+      end
+
+      # @see AssociationObservers::Orm::Base.class_variable_set
+      def self.class_variable_set(klass, name)
+        klass.instance_eval <<-END
+          @@#{name}=nil
+          def #{name}
+            @@#{name}
+          end
+
+          def #{name}=(value)
+            @@#{name} = value
+          end
+        END
+
+      end
+
+      # @see AssociationObservers::Orm::Base.batched_each
+      def self.batched_each(collection, batch, &block)
+        collection.is_a?(::DataMapper::Collection) ?
+        collection.each(&block) : # datamapper batches already by 500 https://groups.google.com/forum/?fromgroups=#!searchin/datamapper/batches/datamapper/lAZWFN4TWAA/G1Gu-ams_QMJ
+        super
+      end
+
+      # @see AssociationObservers::Orm::Base.validate_parameters
+      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
+      end
+    end
+  end
+end
+

data/lib/association_observers/queue.rb

@@ -0,0 +1,71 @@
+# -*- encoding : utf-8 -*-
+require 'singleton'
+
+# the queue handles the notification distributions which the notifiers trigger. The Notifier usually knows what to notify
+# and whom to notify. It passes this information to the queue, which strategizes the dispatching. It is more than a singleton;
+# it is designed as a single inter-process object. Why? Because one cannot marshall procedures, and this unique inter-process
+# object acts as a container for the procedures which will be handled assynchronously by the message queue solution. It is also
+# a proxy to the used background queue solution: the queueing basically proxies the queueing somewhere else (Delayed Job, Resque...)
+module AssociationObservers
+  class Queue
+    include Singleton
+
+
+    # encapsulates enqueuing strategy. if the callback is to a destroy action, one cannot afford to enqueue, because the
+    # observable will be deleted by then. So, perform destroy notifications synchronously right away. If not, the strategy
+    # for now is get the object ids and enqueue them with the notifier.
+    #
+    # @param [ActiveRecord:Relation, DataMapper::Relationship] observers to be notified
+    # @param [Notifier::Base] notifier encapsulates the notification logic
+    # @param [Hash] opts other possible options that can't be inferred from the given arguments
+    def enqueue_notifications(observers, observable, notifier, opts={})
+      klass       = opts[:klass]      || AssociationObservers::orm_adapter.collection_class(observers)
+      batch_size  = opts[:batch_size] || klass.observable_options[:batch_size]
+
+      if notifier.callback.eql?(:destroy)
+        method = RUBY_VERSION < "1.9" ?
+            AssociationObservers::Backports::Proc.fake_curry(notifier.method(:conditional_action).to_proc, observable) :
+            notifier.method(:conditional_action).to_proc.curry[observable]
+        AssociationObservers::orm_adapter.batched_each(observers, batch_size, &method)
+      else
+        # create workers
+        i = 0
+        loop do
+          ids = AssociationObservers::orm_adapter.get_field(observers, :fields => [:id], :limit => batch_size, :offset => i*batch_size).compact
+          break if ids.empty?
+          enqueue(Workers::ManyDelayedNotification, ids, klass.name, observable.id, observable.class.name, notifier)
+          i += 1
+        end
+      end
+    end
+
+    def engine=(engine)
+      AssociationObservers::options[:queue][:engine] = engine
+      initialize_queue_engine
+    end
+
+    def initialize_queue_engine
+      engine = AssociationObservers::options[:queue][:engine]
+      return if engine.nil?
+      raise "#{engine}: unsupported engine" unless %w(delayed_job resque sidekiq).include?(engine.to_s)
+      # first, remove stuff from previous engine
+      # TODO: can une exclude modules???
+      #if AssociationObservers::options[:queue_engine]
+      #
+      #end
+      require "association_observers/extensions/#{engine}"
+    end
+
+    private
+
+    # enqueues the task with the given arguments to be processed asynchronously
+    # this method implements the fallback, which is: execute synchronously
+    # @note this method is overwritten by the message queue adapters. If your background queue engine is not supported,
+    #       overwrite this method and delegate to your background queue.
+    def enqueue(task, *args)
+      t = task.new(*args)
+      t.perform
+    end
+
+  end
+end

data/lib/association_observers/railtie.rb

@@ -2,18 +2,25 @@
 module AssociationObservers
   def self.initialize_railtie
     ActiveSupport.on_load :active_record do
-      require 'association_observers/activerecord'
-    end
-    ActiveSupport.on_load :data_mapper do
-      require 'association_observers/datamapper'
+      require 'association_observers/active_record'
     end
+    # ORM Adapters
+    require 'association_observers/data_mapper' if defined?(DataMapper)
+
   end
   class Railtie < Rails::Railtie
+    config.association_observers = ActiveSupport::OrderedOptions.new.merge(AssociationObservers::options)
+    config.association_observers.queue = ActiveSupport::OrderedOptions.new.merge(config.association_observers.queue)
+
     initializer 'association_observers.insert_into_orm' do
       AssociationObservers.initialize_railtie
     end
     initializer 'association_observers.autoload', :before => :set_autoload_paths do |app|
       app.config.autoload_paths << Rails.root.join("app", "notifiers")
     end
+    initializer 'association_observers.rails_configuration_options' do
+      AssociationObservers::options.merge!(config.association_observers)
+      AssociationObservers::queue.initialize_queue_engine
+    end
   end
 end