workflow-orchestrator 1.3.0

data/lib/workflow.rb

@@ -0,0 +1,307 @@
+require 'rubygems'
+
+require 'workflow/specification'
+require 'workflow/adapters/active_record'
+require 'workflow/adapters/remodel'
+
+# See also README.markdown for documentation
+module Workflow
+  module ClassMethods
+    attr_reader :workflow_spec
+
+    def workflow_column(column_name=nil)
+      #I guess we want to preserve the api???
+      @workflow_state_column_name ||= column_name
+      if @workflow_state_column_name.nil? && superclass.respond_to?(:workflow_column)
+        @workflow_state_column_name = superclass.workflow_column
+      end
+      @workflow_state_column_name ||= :workflow_state
+
+    end
+
+    def workflow(column=nil,&specification)
+      column = workflow_column(column)
+      assign_workflow Specification.new(Hash.new, &specification)
+
+      inject_setter_for_state
+    end
+
+    private
+
+    #allow setting of workflow_state by name, and interpolate the value
+    def inject_setter_for_state
+      define_method("#{@workflow_state_column_name}=") do |val|
+        
+        matching_state = spec.states.select{|k,v| v.name.to_s == val.to_s}.values.first
+        val = matching_state.value if matching_state
+        super(val)
+      end
+    end
+
+    # Creates the convinience methods like `my_transition!`
+    def assign_workflow(specification_object)
+
+      # Merging two workflow specifications can **not** be done automically, so
+      # just make the latest specification win. Same for inheritance -
+      # definition in the subclass wins.
+      if respond_to? :inherited_workflow_spec # undefine methods defined by the old workflow_spec
+        inherited_workflow_spec.states.values.each do |state|
+          state_name = state.name
+          module_eval do
+            undef_method "#{state_name}?"
+          end
+
+          state.events.flat.each do |event|
+            event_name = event.name
+            module_eval do
+              undef_method "#{event_name}!".to_sym
+              undef_method "can_#{event_name}?"
+            end
+          end
+        end
+      end
+
+      @workflow_spec = specification_object
+      @workflow_spec.states.values.each do |state|
+        state_name = state.name
+        module_eval do
+          define_method "#{state_name}?" do
+            state_name == current_state.name
+          end
+        end
+
+        state.events.flat.each do |event|
+          event_name = event.name
+          module_eval do
+            define_method "#{event_name}!".to_sym do |*args|
+              process_event!(event_name, *args)
+            end
+
+            define_method "can_#{event_name}?" do
+              return !!current_state.events.first_applicable(event_name, self)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  module InstanceMethods
+
+    def current_state
+      loaded_state_value = load_workflow_state
+      if loaded_state_value
+        loaded_state_name = spec.states.select{|k,v| v.value.to_s == loaded_state_value.to_s}.keys.first
+      end
+
+      res = spec.states[loaded_state_name.to_sym] if loaded_state_name
+      res || spec.initial_state
+    end
+
+    # See the 'Guards' section in the README
+    # @return true if the last transition was halted by one of the transition callbacks.
+    def halted?
+      @halted
+    end
+
+    # @return the reason of the last transition abort as set by the previous
+    # call of `halt` or `halt!` method.
+    def halted_because
+      @halted_because
+    end
+
+    def process_event!(name, *args)
+      event = current_state.events.first_applicable(name, self)
+      if event.nil?
+        return run_on_unavailable_transition(current_state, name, *args)
+      end
+      @halted_because = nil
+      @halted = false
+
+      check_transition(event)
+
+      from = current_state
+      to_state = spec.states[event.transitions_to]
+      to_value = to_state.value
+
+      run_before_transition(from, to_state, name, *args)
+      return false if @halted
+
+      begin
+        return_value = run_action(event.action, *args) || run_action_callback(event.name, *args)
+      rescue StandardError => e
+        run_on_error(e, from, to_state, name, *args)
+      end
+
+      return false if @halted
+
+      run_on_transition(from, to_state, name, *args)
+
+      run_on_exit(from, to_state, name, *args)
+
+      transition_value = persist_workflow_state to_value
+
+      run_on_entry(to_state, from, name, *args)
+
+      run_after_transition(from, to_state, name, *args)
+
+      return_value.nil? ? transition_value : return_value
+    end
+
+    def halt(reason = nil)
+      @halted_because = reason
+      @halted = true
+    end
+
+    def halt!(reason = nil)
+      @halted_because = reason
+      @halted = true
+      raise TransitionHalted.new(reason)
+    end
+
+    def spec
+      # check the singleton class first
+      class << self
+        return workflow_spec if workflow_spec
+      end
+
+      c = self.class
+      # using a simple loop instead of class_inheritable_accessor to avoid
+      # dependency on Rails' ActiveSupport
+      until c.workflow_spec || !(c.include? Workflow)
+        c = c.superclass
+      end
+      c.workflow_spec
+    end
+
+    private
+
+    def check_transition(event)
+      # Create a meaningful error message instead of
+      # "undefined method `on_entry' for nil:NilClass"
+      # Reported by Kyle Burton
+      if !spec.states[event.transitions_to]
+        raise WorkflowError.new("Event[#{event.name}]'s " +
+            "transitions_to[#{event.transitions_to}] is not a declared state.")
+      end
+    end
+
+    def run_before_transition(from, to, event, *args)
+      instance_exec(from.name, to.name, event, *args, &spec.before_transition_proc) if
+        spec.before_transition_proc
+    end
+
+    def run_on_error(error, from, to, event, *args)
+      if spec.on_error_proc
+        instance_exec(error, from.name, ( to.name rescue nil ), event, *args, &spec.on_error_proc)
+        halt(error.message)
+      else
+        raise error
+      end
+    end
+
+    def run_on_unavailable_transition(from, to_name, *args)
+      if !spec.on_unavailable_transition_proc || !instance_exec(from.name, to_name.to_sym, *args, &spec.on_unavailable_transition_proc)
+        run_on_error(NoTransitionAllowed.new(
+          "There is no event #{to_name.to_sym} defined for the #{current_state} state"), 
+          current_state, 
+          nil, to_name, *args)
+        return false
+      end
+    end
+
+    def run_on_transition(from, to, event, *args)
+      instance_exec(from.name, to.name, event, *args, &spec.on_transition_proc) if spec.on_transition_proc
+    end
+
+    def run_after_transition(from, to, event, *args)
+      instance_exec(from.name, to.name, event, *args, &spec.after_transition_proc) if
+        spec.after_transition_proc
+    end
+
+    def run_action(action, *args)
+      instance_exec(*args, &action) if action
+    end
+
+    def has_callback?(action)
+      # 1. public callback method or
+      # 2. protected method somewhere in the class hierarchy or
+      # 3. private in the immediate class (parent classes ignored)
+      action = action.to_sym
+      self.respond_to?(action) or
+        self.class.protected_method_defined?(action) or
+        self.private_methods(false).map(&:to_sym).include?(action)
+    end
+
+    def run_action_callback(action_name, *args)
+      action = action_name.to_sym
+      self.send(action, *args) if has_callback?(action)
+    end
+
+    def run_on_entry(state, prior_state, triggering_event, *args)
+      if state.on_entry
+        instance_exec(prior_state.name, triggering_event, *args, &state.on_entry)
+      else
+        hook_name = "on_#{state}_entry"
+        self.send hook_name, prior_state, triggering_event, *args if has_callback?(hook_name)
+      end
+    end
+
+    def run_on_exit(state, new_state, triggering_event, *args)
+      if state
+        if state.on_exit
+          instance_exec(new_state.name, triggering_event, *args, &state.on_exit)
+        else
+          hook_name = "on_#{state}_exit"
+          self.send hook_name, new_state, triggering_event, *args if has_callback?(hook_name)
+        end
+      end
+    end
+
+    # load_workflow_state and persist_workflow_state
+    # can be overriden to handle the persistence of the workflow state.
+    #
+    # Default (non ActiveRecord) implementation stores the current state
+    # in a variable.
+    #
+    # Default ActiveRecord implementation uses a 'workflow_state' database column.
+    def load_workflow_state
+      @workflow_state if instance_variable_defined? :@workflow_state
+    end
+
+    def persist_workflow_state(new_value)
+
+      @workflow_state = new_value
+    end
+  end
+
+  def self.included(klass)
+    klass.send :include, InstanceMethods
+
+    # backup the parent workflow spec, making accessible through #inherited_workflow_spec
+    if klass.superclass.respond_to?(:workflow_spec, true)
+      klass.module_eval do
+        # see http://stackoverflow.com/a/2495650/111995 for implementation explanation
+        pro = Proc.new { klass.superclass.workflow_spec }
+        singleton_class = class << self; self; end
+        singleton_class.send(:define_method, :inherited_workflow_spec) do
+          pro.call
+        end
+      end
+    end
+
+    klass.extend ClassMethods
+
+    # Look for a hook; otherwise detect based on ancestor class.
+    if klass.respond_to?(:workflow_adapter)
+      klass.send :include, klass.workflow_adapter
+    else
+      if Object.const_defined?(:ActiveRecord) && klass < ActiveRecord::Base
+        klass.send :include, Adapter::ActiveRecord
+      end
+      if Object.const_defined?(:Remodel) && klass < Adapter::Remodel::Entity
+        klass.send :include, Adapter::Remodel::InstanceMethods
+      end
+    end
+  end
+end

data/test/active_record_scopes_test.rb

@@ -0,0 +1,56 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+$VERBOSE = false
+require 'active_record'
+require 'sqlite3'
+require 'workflow'
+
+ActiveRecord::Migration.verbose = false
+
+class Article < ActiveRecord::Base
+  include Workflow
+
+  workflow do
+    state :new
+    state :accepted
+  end
+end
+
+class ActiveRecordScopesTest < ActiveRecordTestCase
+
+  def setup
+    super
+
+    ActiveRecord::Schema.define do
+      create_table :articles do |t|
+        t.string :title
+        t.string :body
+        t.string :blame_reason
+        t.string :reject_reason
+        t.string :workflow_state
+      end
+    end
+  end
+
+  def assert_state(title, expected_state, klass = Order)
+    o = klass.find_by_title(title)
+    assert_equal expected_state, o.read_attribute(klass.workflow_column)
+    o
+  end
+
+  test 'have "with_new_state" scope' do
+    assert_respond_to Article, :with_new_state
+  end
+
+  test 'have "with_accepted_state" scope' do
+    assert_respond_to Article, :with_accepted_state
+  end
+
+  test 'have "without_new_state" scope' do
+    assert_respond_to Article, :without_new_state
+  end
+
+  test 'have "without_accepted_state" scope' do
+    assert_respond_to Article, :without_accepted_state
+  end
+end

data/test/active_record_scopes_with_values_test.rb

@@ -0,0 +1,79 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+$VERBOSE = false
+require 'active_record'
+require 'sqlite3'
+require 'workflow'
+
+ActiveRecord::Migration.verbose = false
+
+class EnumArticle < ActiveRecord::Base
+  include Workflow
+
+  workflow do
+    state :new, 1 do
+      event :accept, transitions_to: :accepted
+    end
+    state :accepted, 3
+  end
+end
+
+class ActiveRecordScopesWithValuesTest < ActiveRecordTestCase
+
+  def setup
+    super
+
+    ActiveRecord::Schema.define do
+      create_table :enum_articles do |t|
+        t.string :title
+        t.string :body
+        t.string :blame_reason
+        t.string :reject_reason
+        t.integer :workflow_state
+      end
+    end
+  end
+
+  test 'have "with_new_state" scope' do
+    assert_respond_to EnumArticle, :with_new_state
+  end
+
+  test '"with_new_state" selects matching value' do
+    article = EnumArticle.create
+    assert_equal(article.workflow_state, 1)
+    assert_equal(EnumArticle.with_new_state.all, [article])
+  end
+
+  test 'have "with_accepted_state" scope' do
+    assert_respond_to EnumArticle, :with_accepted_state
+  end
+
+  test '"with_accepted_state" selects matching values' do
+    article = EnumArticle.create
+    article.accept!
+    assert_equal(EnumArticle.with_accepted_state.all, [article])
+  end
+
+  test 'have "without_new_state" scope' do
+    assert_respond_to EnumArticle, :without_new_state
+  end
+
+  test '"without_new_state" filters matching value' do
+    article = EnumArticle.create
+    article.accept!
+    assert_equal(article.workflow_state, 3)
+    assert_equal(EnumArticle.without_new_state, [article])
+  end
+
+  test 'have "without_accepted_state" scope' do
+    assert_respond_to EnumArticle, :without_accepted_state
+  end
+
+  test '"without_accepted_state" filters matching value' do
+    article = EnumArticle.create
+    assert_equal(article.workflow_state, 1)
+    assert_equal(EnumArticle.without_accepted_state, [article])
+  end
+
+end
+

data/test/adapter_hook_test.rb

@@ -0,0 +1,52 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'workflow'
+class AdapterHookTest < ActiveRecordTestCase
+  test 'hook to choose adapter' do
+
+    ActiveRecord::Schema.define do
+      create_table(:examples) { |t| t.string :workflow_state }
+    end
+
+    class DefaultAdapter < ActiveRecord::Base
+      self.table_name = :examples
+      include Workflow
+      workflow do
+        state(:initial) { event :progress, :transitions_to => :last }
+        state(:last)
+      end
+    end
+
+    class ChosenByHookAdapter < ActiveRecord::Base
+      self.table_name = :examples
+      attr_reader :foo
+      def self.workflow_adapter
+        Module.new do
+          def load_workflow_state
+            @foo if defined?(@foo)
+          end
+          def persist_workflow_state(new_value)
+            @foo = new_value
+          end
+        end
+      end
+
+      include Workflow
+      workflow do
+        state(:initial) { event :progress, :transitions_to => :last }
+        state(:last)
+      end
+    end
+
+    default = DefaultAdapter.create
+    assert default.initial?
+    default.progress!
+    assert default.last?
+    assert DefaultAdapter.find(default.id).last?, 'should have persisted via ActiveRecord'
+
+    hook = ChosenByHookAdapter.create
+    assert hook.initial?
+    hook.progress!
+    assert_equal hook.foo, :last, 'should have "persisted" with custom adapter'
+    assert ChosenByHookAdapter.find(hook.id).initial?, 'should not have persisted via ActiveRecord'
+  end
+end

data/test/advanced_examples_test.rb

@@ -0,0 +1,84 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'workflow'
+class AdvanceExamplesTest < ActiveRecordTestCase
+
+  class Article
+    include Workflow
+    workflow do
+      state :new do
+        event :submit, :transitions_to => :awaiting_review
+      end
+      state :awaiting_review do
+        event :review, :transitions_to => :being_reviewed
+      end
+      state :being_reviewed do
+        event :accept, :transitions_to => :accepted
+        event :reject, :transitions_to => :rejected
+      end
+      state :accepted do
+      end
+      state :rejected do
+      end
+    end
+  end
+
+  test '#63 undoing event - automatically add revert events for every defined event' do
+    # also see https://github.com/geekq/workflow/issues/63
+    spec = Article.workflow_spec
+    spec.state_names.each do |state_name|
+      state = spec.states[state_name]
+
+        (state.events.flat.reject {|e| e.name.to_s =~ /^revert_/ }).each do |event|
+          event_name = event.name
+          revert_event_name = "revert_" + event_name.to_s
+
+          # Add revert events
+          spec.states[event.transitions_to.to_sym].events.push(
+            revert_event_name,
+            Workflow::Event.new(revert_event_name, state)
+          )
+
+          # Add methods for revert events
+          Article.module_eval do
+            define_method "#{revert_event_name}!".to_sym do |*args|
+              process_event!(revert_event_name, *args)
+            end
+            define_method "can_#{revert_event_name}?" do
+              return self.current_state.events.include?(revert_event_name)
+            end
+          end
+
+        end
+    end
+
+    a = Article.new
+    assert(a.new?, "should start with the 'new' state")
+    a.submit!
+    assert(a.awaiting_review?, "should now be in 'awaiting_review' state")
+    assert_equal(['revert_submit', 'review'], a.current_state.events.keys.map(&:to_s).sort)
+    a.revert_submit! # this method is added by our meta programming magic above
+    assert(a.new?, "should now be back in the 'new' state")
+  end
+
+  test '#92 Load workflow specification' do
+    c = Class.new
+    c.class_eval do
+      include Workflow
+    end
+
+    # build a Specification (you can load it from yaml file too)
+    myspec = Workflow::Specification.new do
+      state :one do
+        event :dynamic_transition, :transitions_to => :one_a
+      end
+      state :one_a
+    end
+
+    c.send :assign_workflow, myspec
+
+    a = c.new
+    a.dynamic_transition!(1)
+    assert a.one_a?, 'Expected successful transition to a new state'
+  end
+
+end

data/test/advanced_hooks_and_validation_test.rb

@@ -0,0 +1,119 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+$VERBOSE = false
+require 'active_record'
+require 'sqlite3'
+require 'workflow'
+
+ActiveRecord::Migration.verbose = false
+
+# Transition based validation
+# ---------------------------
+# If you are using ActiveRecord you might want to define different validations
+# for different transitions. There is a `validates_presence_of` hook that let's
+# you specify the attributes that need to be present for an successful transition.
+# If the object is not valid at the end of the transition event the transition
+# is halted and a TransitionHalted exception is thrown.
+#
+# Here is a sample that illustrates how to use the presence validation:
+# (use case suggested by http://github.com/southdesign)
+class Article < ActiveRecord::Base
+  include Workflow
+  workflow do
+    state :new do
+      event :accept, :transitions_to => :accepted, :meta => {:validates_presence_of => [:title, :body]}
+      event :reject, :transitions_to => :rejected
+    end
+    state :accepted do
+      event :blame, :transitions_to => :blamed, :meta => {:validates_presence_of => [:title, :body, :blame_reason]}
+      event :delete, :transitions_to => :deleted
+    end
+    state :rejected do
+      event :delete, :transitions_to => :deleted
+    end
+    state :blamed do
+      event :delete, :transitions_to => :deleted
+    end
+    state :deleted do
+      event :accept, :transitions_to => :accepted
+    end
+
+    on_transition do |from, to, triggering_event, *event_args|
+      if self.class.superclass.to_s.split("::").first == "ActiveRecord"
+        singleton = class << self; self end
+        validations = Proc.new {}
+
+        meta = Article.workflow_spec.states[from].events[triggering_event].first.meta
+        fields_to_validate = meta[:validates_presence_of]
+        if fields_to_validate
+          validations = Proc.new {
+            errors.add_on_blank(fields_to_validate) if fields_to_validate
+          }
+        end
+
+        singleton.send :define_method, :validate_for_transition, &validations
+        validate_for_transition
+        halt! "Event[#{triggering_event}]'s transitions_to[#{to}] is not valid." unless self.errors.empty?
+      end
+    end
+  end
+end
+
+class AdvancedHooksAndValidationTest < ActiveRecordTestCase
+
+  def setup
+    super
+
+    ActiveRecord::Schema.define do
+      create_table :articles do |t|
+        t.string :title
+        t.string :body
+        t.string :blame_reason
+        t.string :reject_reason
+        t.string :workflow_state
+      end
+    end
+
+    exec "INSERT INTO articles(title, body, blame_reason, reject_reason, workflow_state) VALUES('new1', NULL, NULL, NULL, 'new')"
+    exec "INSERT INTO articles(title, body, blame_reason, reject_reason, workflow_state) VALUES('new2', 'some content', NULL, NULL, 'new')"
+    exec "INSERT INTO articles(title, body, blame_reason, reject_reason, workflow_state) VALUES('accepted1', 'some content', NULL, NULL, 'accepted')"
+
+  end
+
+  def assert_state(title, expected_state, klass = Order)
+    o = klass.find_by_title(title)
+    assert_equal expected_state, o.read_attribute(klass.workflow_column)
+    o
+  end
+
+  test 'deny transition from new to accepted because of the missing presence of the body' do
+    a = Article.find_by_title('new1');
+    assert_raise Workflow::TransitionHalted do
+      a.accept!
+    end
+    assert_state 'new1', 'new', Article
+  end
+
+  test 'allow transition from new to accepted because body is present this time' do
+    a = Article.find_by_title('new2');
+    assert a.accept!
+    assert_state 'new2', 'accepted', Article
+  end
+
+  test 'allow transition from accepted to blamed because of a blame_reason' do
+    a = Article.find_by_title('accepted1');
+    a.blame_reason = "Provocant thesis"
+    assert a.blame!
+    assert_state 'accepted1', 'blamed', Article
+  end
+
+  test 'deny transition from accepted to blamed because of no blame_reason' do
+    a = Article.find_by_title('accepted1');
+    assert_raise Workflow::TransitionHalted do
+      assert a.blame!
+    end
+    assert_state 'accepted1', 'accepted', Article
+  end
+
+end
+