rails-observers 0.1.0

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in active_record-observers.gemspec
+gemspec
+
+gem 'activerecord-deprecated_finders', git: 'git://github.com/rails/activerecord-deprecated_finders'
+gem 'journey', git: 'https://github.com/rails/journey.git'
+
+gem 'rails', git: 'git://github.com/rafaelfranca/rails', branch: 'extract_observers'
+
+gem 'mocha', require: false

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Steve Klabnik, Rafael Mendonça França
+
+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,102 @@
+# Rails::Observers
+
+Rails Observers (removed from core in Rails 4.0)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rails-observers'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rails-observers
+
+## Usage
+
+This gem contains two observers:
+
+* Active Record Observer
+* Action Controller Sweeper
+
+### Active Record Observer
+
+Observer classes respond to life cycle callbacks to implement trigger-like
+behavior outside the original class. This is a great way to reduce the
+clutter that normally comes when the model class is burdened with
+functionality that doesn't pertain to the core responsibility of the
+class. Example:
+
+```ruby
+class CommentObserver < ActiveRecord::Observer
+  def after_save(comment)
+    Notifications.comment("admin@do.com", "New comment was posted", comment).deliver
+  end
+end
+```
+
+This Observer sends an email when a Comment#save is finished.
+
+```ruby
+class ContactObserver < ActiveRecord::Observer
+  def after_create(contact)
+    contact.logger.info('New contact added!')
+  end
+
+  def after_destroy(contact)
+    contact.logger.warn("Contact with an id of #{contact.id} was destroyed!")
+  end
+end
+```
+
+This Observer uses logger to log when specific callbacks are triggered.
+
+### Action Controller Sweeper
+
+Sweepers are the terminators of the caching world and responsible for expiring caches when model objects change.
+They do this by being half-observers, half-filters and implementing callbacks for both roles. A Sweeper example:
+
+```ruby
+class ListSweeper < ActionController::Caching::Sweeper
+  observe List, Item
+
+  def after_save(record)
+    list = record.is_a?(List) ? record : record.list
+    expire_page(:controller => "lists", :action => %w( show public feed ), :id => list.id)
+    expire_action(:controller => "lists", :action => "all")
+    list.shares.each { |share| expire_page(:controller => "lists", :action => "show", :id => share.url_key) }
+  end
+end
+```
+
+The sweeper is assigned in the controllers that wish to have its job performed using the `cache_sweeper` class method:
+
+```ruby
+class ListsController < ApplicationController
+  caches_action :index, :show, :public, :feed
+  cache_sweeper :list_sweeper, :only => [ :edit, :destroy, :share ]
+end
+```
+
+In the example above, four actions are cached and three actions are responsible for expiring those caches.
+
+You can also name an explicit class in the declaration of a sweeper, which is needed if the sweeper is in a module:
+
+```ruby
+class ListsController < ApplicationController
+  caches_action :index, :show, :public, :feed
+  cache_sweeper OpenBar::Sweeper, :only => [ :edit, :destroy, :share ]
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,34 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new("test:regular") do |t|
+  t.libs = ["test"]
+  t.pattern = "test/*_test.rb"
+  t.ruby_opts = ['-w']
+end
+
+Rake::TestTask.new("test:generators") do |t|
+  t.libs = ["test"]
+  t.pattern = "test/generators/*_test.rb"
+  t.ruby_opts = ['-w']
+end
+
+task :default => :test
+task :test => ['test:regular', 'test:generators']
+
+specname = "rails-observers.gemspec"
+deps = `git ls-files`.split("\n") - [specname]
+
+file specname => deps do
+  files       = `git ls-files`.split("\n")
+  test_files  = `git ls-files -- {test,spec,features}/*`.split("\n")
+  executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+
+  require 'erb'
+
+  File.open specname, 'w:utf-8' do |f|
+    f.write ERB.new(File.read("#{specname}.erb")).result(binding)
+  end
+end

data/lib/generators/active_record/observer/observer_generator.rb

@@ -0,0 +1,17 @@
+require 'rails/generators/active_record'
+
+module ActiveRecord
+  module Generators
+    class ObserverGenerator < Base
+      check_class_collision :suffix => "Observer"
+
+      source_root File.expand_path("../templates", __FILE__)
+
+      def create_observer_file
+        template 'observer.rb', File.join('app/models', class_path, "#{file_name}_observer.rb")
+      end
+
+      hook_for :test_framework
+    end
+  end
+end

data/lib/generators/active_record/observer/templates/observer.rb

@@ -0,0 +1,4 @@
+<% module_namespacing do -%>
+class <%= class_name %>Observer < ActiveRecord::Observer
+end
+<% end -%>

data/lib/generators/rails/observer/USAGE

@@ -0,0 +1,12 @@
+Description:
+    Stubs out a new observer. Pass the observer name, either CamelCased or
+    under_scored, as an argument.
+
+    This generator only invokes your ORM and test framework generators.
+
+Example:
+    `rails generate observer Account`
+
+    For ActiveRecord and TestUnit it creates:
+        Observer:   app/models/account_observer.rb
+        TestUnit:   test/unit/account_observer_test.rb

data/lib/generators/rails/observer/observer_generator.rb

@@ -0,0 +1,7 @@
+module Rails
+  module Generators
+    class ObserverGenerator < NamedBase #metagenerator
+      hook_for :orm, :required => true
+    end
+  end
+end

data/lib/generators/test_unit/observer/observer_generator.rb

@@ -0,0 +1,15 @@
+require 'rails/generators/test_unit'
+
+module TestUnit
+  module Generators
+    class ObserverGenerator < Base
+      check_class_collision :suffix => "ObserverTest"
+
+      source_root File.expand_path("../templates", __FILE__)
+
+      def create_test_files
+        template 'unit_test.rb', File.join('test/unit', class_path, "#{file_name}_observer_test.rb")
+      end
+    end
+  end
+end

data/lib/generators/test_unit/observer/templates/unit_test.rb

@@ -0,0 +1,9 @@
+require 'test_helper'
+
+<% module_namespacing do -%>
+class <%= class_name %>ObserverTest < ActiveSupport::TestCase
+  # test "the truth" do
+  #   assert true
+  # end
+end
+<% end -%>

data/lib/rails-observers.rb

@@ -0,0 +1,30 @@
+require 'rails'
+require 'rails/observers/version'
+
+module Rails
+  module Observers
+    class Railtie < ::Rails::Railtie
+      initializer "active_record.observer", :before => "active_record.set_configs" do
+        ActiveSupport.on_load(:active_record) do
+          require "rails/observers/activerecord/active_record"
+        end
+      end
+
+      initializer "action_controller.caching.sweppers" do
+        ActiveSupport.on_load(:action_controller) do
+          require "rails/observers/action_controller/caching"
+        end
+      end
+
+      config.after_initialize do |app|
+        ActiveSupport.on_load(:active_record) do
+          ActiveRecord::Base.instantiate_observers
+
+          ActionDispatch::Reloader.to_prepare do
+            ActiveRecord::Base.instantiate_observers
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/observers/action_controller/caching.rb

@@ -0,0 +1,12 @@
+module ActionController #:nodoc:
+  module Caching
+    extend ActiveSupport::Autoload
+
+    eager_autoload do
+      autoload :Sweeper,  'rails/observers/action_controller/caching/sweeping'
+      autoload :Sweeping, 'rails/observers/action_controller/caching/sweeping'
+    end
+
+    include Sweeping if defined?(ActiveRecord)
+  end
+end

data/lib/rails/observers/action_controller/caching/sweeping.rb

@@ -0,0 +1,113 @@
+module ActionController #:nodoc:
+  module Caching
+    # Sweepers are the terminators of the caching world and responsible for expiring caches when model objects change.
+    # They do this by being half-observers, half-filters and implementing callbacks for both roles. A Sweeper example:
+    #
+    #   class ListSweeper < ActionController::Caching::Sweeper
+    #     observe List, Item
+    #
+    #     def after_save(record)
+    #       list = record.is_a?(List) ? record : record.list
+    #       expire_page(:controller => "lists", :action => %w( show public feed ), :id => list.id)
+    #       expire_action(:controller => "lists", :action => "all")
+    #       list.shares.each { |share| expire_page(:controller => "lists", :action => "show", :id => share.url_key) }
+    #     end
+    #   end
+    #
+    # The sweeper is assigned in the controllers that wish to have its job performed using the <tt>cache_sweeper</tt> class method:
+    #
+    #   class ListsController < ApplicationController
+    #     caches_action :index, :show, :public, :feed
+    #     cache_sweeper :list_sweeper, :only => [ :edit, :destroy, :share ]
+    #   end
+    #
+    # In the example above, four actions are cached and three actions are responsible for expiring those caches.
+    #
+    # You can also name an explicit class in the declaration of a sweeper, which is needed if the sweeper is in a module:
+    #
+    #   class ListsController < ApplicationController
+    #     caches_action :index, :show, :public, :feed
+    #     cache_sweeper OpenBar::Sweeper, :only => [ :edit, :destroy, :share ]
+    #   end
+    module Sweeping
+      extend ActiveSupport::Concern
+
+      module ClassMethods #:nodoc:
+        def cache_sweeper(*sweepers)
+          configuration = sweepers.extract_options!
+
+          sweepers.each do |sweeper|
+            ActiveRecord::Base.observers << sweeper if defined?(ActiveRecord) and defined?(ActiveRecord::Base)
+            sweeper_instance = (sweeper.is_a?(Symbol) ? Object.const_get(sweeper.to_s.classify) : sweeper).instance
+
+            if sweeper_instance.is_a?(Sweeper)
+              around_filter(sweeper_instance, :only => configuration[:only])
+            else
+              after_filter(sweeper_instance, :only => configuration[:only])
+            end
+          end
+        end
+      end
+    end
+
+    if defined?(ActiveRecord) and defined?(ActiveRecord::Observer)
+      class Sweeper < ActiveRecord::Observer #:nodoc:
+        attr_accessor :controller
+
+        def initialize(*args)
+          super
+          @controller = nil
+        end
+
+        def before(controller)
+          self.controller = controller
+          callback(:before) if controller.perform_caching
+          true # before method from sweeper should always return true
+        end
+
+        def after(controller)
+          self.controller = controller
+          callback(:after) if controller.perform_caching
+        end
+
+        def around(controller)
+          before(controller)
+          yield
+          after(controller)
+        ensure
+          clean_up
+        end
+
+        protected
+        # gets the action cache path for the given options.
+        def action_path_for(options)
+          Actions::ActionCachePath.new(controller, options).path
+        end
+
+        # Retrieve instance variables set in the controller.
+        def assigns(key)
+          controller.instance_variable_get("@#{key}")
+        end
+
+        private
+        def clean_up
+          # Clean up, so that the controller can be collected after this request
+          self.controller = nil
+        end
+
+        def callback(timing)
+          controller_callback_method_name = "#{timing}_#{controller.controller_name.underscore}"
+          action_callback_method_name     = "#{controller_callback_method_name}_#{controller.action_name}"
+
+          __send__(controller_callback_method_name) if respond_to?(controller_callback_method_name, true)
+          __send__(action_callback_method_name)     if respond_to?(action_callback_method_name, true)
+        end
+
+        def method_missing(method, *arguments, &block)
+          return super unless @controller
+          @controller.__send__(method, *arguments, &block)
+        end
+      end
+    end
+  end
+end

data/lib/rails/observers/active_model/active_model.rb

@@ -0,0 +1,4 @@
+module ActiveModel
+  autoload :Observer, 'rails/observers/active_model/observing'
+  autoload :Observing, 'rails/observers/active_model/observing'
+end

data/lib/rails/observers/active_model/observer_array.rb

@@ -0,0 +1,152 @@
+require 'set'
+
+module ActiveModel
+  # Stores the enabled/disabled state of individual observers for
+  # a particular model class.
+  class ObserverArray < Array
+    attr_reader :model_class
+    def initialize(model_class, *args) #:nodoc:
+      @model_class = model_class
+      super(*args)
+    end
+
+    # Returns +true+ if the given observer is disabled for the model class,
+    # +false+ otherwise.
+    def disabled_for?(observer) #:nodoc:
+      disabled_observers.include?(observer.class)
+    end
+
+    # Disables one or more observers. This supports multiple forms:
+    #
+    #   ORM.observers.disable :all
+    #     # => disables all observers for all models subclassed from
+    #     #    an ORM base class that includes ActiveModel::Observing
+    #     #    e.g. ActiveRecord::Base
+    #
+    #   ORM.observers.disable :user_observer
+    #     # => disables the UserObserver
+    #
+    #   User.observers.disable AuditTrail
+    #     # => disables the AuditTrail observer for User notifications.
+    #     #    Other models will still notify the AuditTrail observer.
+    #
+    #   ORM.observers.disable :observer_1, :observer_2
+    #     # => disables Observer1 and Observer2 for all models.
+    #
+    #   User.observers.disable :all do
+    #     # all user observers are disabled for
+    #     # just the duration of the block
+    #   end
+    def disable(*observers, &block)
+      set_enablement(false, observers, &block)
+    end
+
+    # Enables one or more observers. This supports multiple forms:
+    #
+    #   ORM.observers.enable :all
+    #     # => enables all observers for all models subclassed from
+    #     #    an ORM base class that includes ActiveModel::Observing
+    #     #    e.g. ActiveRecord::Base
+    #
+    #   ORM.observers.enable :user_observer
+    #     # => enables the UserObserver
+    #
+    #   User.observers.enable AuditTrail
+    #     # => enables the AuditTrail observer for User notifications.
+    #     #    Other models will not be affected (i.e. they will not
+    #     #    trigger notifications to AuditTrail if previously disabled)
+    #
+    #   ORM.observers.enable :observer_1, :observer_2
+    #     # => enables Observer1 and Observer2 for all models.
+    #
+    #   User.observers.enable :all do
+    #     # all user observers are enabled for
+    #     # just the duration of the block
+    #   end
+    #
+    # Note: all observers are enabled by default. This method is only
+    # useful when you have previously disabled one or more observers.
+    def enable(*observers, &block)
+      set_enablement(true, observers, &block)
+    end
+
+    protected
+
+      def disabled_observers #:nodoc:
+        @disabled_observers ||= Set.new
+      end
+
+      def observer_class_for(observer) #:nodoc:
+        return observer if observer.is_a?(Class)
+
+        if observer.respond_to?(:to_sym) # string/symbol
+          observer.to_s.camelize.constantize
+        else
+          raise ArgumentError, "#{observer} was not a class or a " +
+            "lowercase, underscored class name as expected."
+        end
+      end
+
+      def start_transaction #:nodoc:
+        disabled_observer_stack.push(disabled_observers.dup)
+        each_subclass_array do |array|
+          array.start_transaction
+        end
+      end
+
+      def disabled_observer_stack #:nodoc:
+        @disabled_observer_stack ||= []
+      end
+
+      def end_transaction #:nodoc:
+        @disabled_observers = disabled_observer_stack.pop
+        each_subclass_array do |array|
+          array.end_transaction
+        end
+      end
+
+      def transaction #:nodoc:
+        start_transaction
+
+        begin
+          yield
+        ensure
+          end_transaction
+        end
+      end
+
+      def each_subclass_array #:nodoc:
+        model_class.descendants.each do |subclass|
+          yield subclass.observers
+        end
+      end
+
+      def set_enablement(enabled, observers) #:nodoc:
+        if block_given?
+          transaction do
+            set_enablement(enabled, observers)
+            yield
+          end
+        else
+          observers = ActiveModel::Observer.descendants if observers == [:all]
+          observers.each do |obs|
+            klass = observer_class_for(obs)
+
+            unless klass < ActiveModel::Observer
+              raise ArgumentError.new("#{obs} does not refer to a valid observer")
+            end
+
+            if enabled
+              disabled_observers.delete(klass)
+            else
+              disabled_observers << klass
+            end
+          end
+
+          each_subclass_array do |array|
+            array.set_enablement(enabled, observers)
+          end
+        end
+      end
+  end
+end