lib/logging/logging.rb spec/unit/logging_spec.rb @@ -7,26 +7,57 @@ AASM started as the acts_as_state_machine plugin but has evolved into a more gen AASM has the following features: * States + - enter + - exit * Machines * Events + - name + - success -> callback + - transitions block * Transitions + - from + - to + - on_transition -> callback + - guard (returns true or false) +* Callbacks + - aasm_before_all_transition -> callback before transition begins + - aasm_after_all_transition -> callback after transition ends +* default and specific log features + - aasm_log_transition -> instance variable that determines whether to log or not. Defaults to true + - aasm_log_method -> the method name for common logging name. Defaults to: aasm_log_transition + - aasm_<event_name>_log -> if you want to have a specific log for one particular event + just implement a method with this naming convention: aasm_<event_name>_log + - aasm also provided the event name, from state and to state to the instance by populating there instance variables: + self.aasm_event_name, self.aasm_old_state, self.aasm_new_state + +* transaction if we choose to persist the transition +* By including AASM, you will have access to these instance methods: + - <state_name>? -> check if the model is in that state + - aasm_current_state -> returns the current state of model + - <event_name>! -> behaves like save! + - <event_name> -> behaves like save + - <event_name>_not_persist -> doesn't save to database + - aasm_events_for_state -> all events that include the passed state in the from transitions + - aasm_events_for_current_state -> all events that include the current state in the from transitions +* By including AASM, you will have access to these class methods: + - aasm_states_for_select -> returns options for all states defined + == Download The latest AASM can currently be pulled from the git repository on github. -* http://github.com/rubyist/aasm/tree/master +* http://github.com/mumboe/aasm A release and a gem are forthcoming. - == Installation === From GitHub hosted gems % sudo gem sources -a http://gems.github.com # (you only need to do this once) - % sudo gem install rubyist-aasm + % sudo gem install mumboe-aasm === Building your own gems @@ -59,8 +90,9 @@ Here's a quick example highlighting some of the features. = Other Stuff -Author:: Scott Barron <scott at elitists dot net> -License:: Copyright 2006, 2007, 2008 by Scott Barron. +Author:: Mumboe Development Team, Scott Barron <scott at elitists dot net> +License:: Copyright 2009 by Mumboe + Copyright 2006, 2007, 2008 by Scott Barron. Released under an MIT-style license. See the LICENSE file included in the distribution. README.rdoc @@ -1,9 +1,4 @@ -Before Next Release: +* Update documentation to include new logging +* Add tests for logging +* Add examples for logging -* Add #aasm_next_state_for_event -* Add #aasm_next_states_for_event - -Cool ideas from users: - -* Support multiple state machines on one object (Chris Nelson) -* http://justbarebones.blogspot.com/2007/11/actsasstatemachine-enhancements.html (Chetan Patil) TODO @@ -2,6 +2,7 @@ require File.join(File.dirname(__FILE__), 'event') require File.join(File.dirname(__FILE__), 'state') require File.join(File.dirname(__FILE__), 'state_machine') require File.join(File.dirname(__FILE__), 'persistence') +require File.join(File.dirname(__FILE__), 'logging', 'logging') module AASM class InvalidTransition < Exception @@ -11,6 +12,7 @@ module AASM base.extend AASM::ClassMethods AASM::Persistence.set_persistence(base) AASM::StateMachine[base] = AASM::StateMachine.new('') + base.send(:include, AASM::Logging::ActiveRecordLogging) base.class_eval do def base.inherited(klass) @@ -20,6 +22,22 @@ module AASM end module ClassMethods + def aasm_before_all_transition(before_transition=nil) + if before_transition + AASM::StateMachine[self].before_all_transition = before_transition + else + AASM::StateMachine[self].before_all_transition + end + end + + def aasm_after_all_transition(after_transition=nil) + if after_transition + AASM::StateMachine[self].after_all_transition = after_transition + else + AASM::StateMachine[self].after_all_transition + end + end + def aasm_initial_state(set_state=nil) if set_state AASM::StateMachine[self].initial_state = set_state @@ -50,11 +68,15 @@ module AASM end define_method("#{name.to_s}!") do |*args| - aasm_fire_event(name, true, *args) + aasm_fire_event(name, true, true, *args) end define_method("#{name.to_s}") do |*args| - aasm_fire_event(name, false, *args) + aasm_fire_event(name, true, false, *args) + end + + define_method("#{name.to_s}_not_persist") do |*args| + aasm_fire_event(name, false, false, *args) end end @@ -69,7 +91,6 @@ module AASM def aasm_states_for_select AASM::StateMachine[self].states.map { |state| state.for_select } end - end # Instance methods @@ -93,11 +114,18 @@ module AASM end private - def aasm_current_state_with_persistence=(state) - if self.respond_to?(:aasm_write_state) || self.private_methods.include?('aasm_write_state') - aasm_write_state(state) + def aasm_current_state_with_persistence=(state, use_bang=false) + result = true + if (self.respond_to?(:aasm_write_state) || self.private_methods.include?('aasm_write_state')) and !use_bang + result = aasm_write_state(state) + result = true if result.nil? + end + + if (self.respond_to?(:aasm_write_state!) || self.private_methods.include?('aasm_write_state!')) and use_bang + aasm_write_state!(state) end - self.aasm_current_state = state + self.aasm_current_state = state if result + result end def aasm_current_state=(state) @@ -111,26 +139,99 @@ module AASM self.class.aasm_states.find {|s| s == name} end - def aasm_fire_event(name, persist, *args) - aasm_state_object_for_state(aasm_current_state).call_action(:exit, self) + def aasm_fire_transition_callback(callback,to_state=nil, *args) + return if callback.blank? + case callback + when Symbol, String + self.send(callback, *args) + when Proc + callback.call(self, *args) + end + end + + # before firing an event, we make sure that we prepopulate + # the args if we pass paramaters. We need to prepopulate the + # args ONLY if we don't pass the transition to state as the + # first parameter and there is only one possible state to go to + def prepare_args_before_firing_event(name, *args) + return args if args.length < 1 + event = self.class.aasm_events[name] + to_state = args.first.blank? ? nil : args.first.to_s.to_sym + to_states = event.get_to_states_when_transitioning_from(self.aasm_current_state) || [] + return args if to_state.nil? or to_states.include?(to_state) + case to_states.length + when 0: + raise AASM::InvalidTransition.new("This event doesn't have any state to go to.") + else + args.insert(0, to_states.first) + # else + # raise AASM::InvalidTransition.new("Please specify your destination state because this event can go to many states.") + end + args + end + + # this method handles the exception caching and active record transaction + # while firing the event. If we persist and use bang, we will + # raise exception thrown, otherwise, just return false + def aasm_fire_event(name, persist, use_bang = false, *args) + begin + args = prepare_args_before_firing_event(name, *args) + puts "**args: #{args.inspect}" if self.aasm_current_state == :processed and name.to_s == 'ship' + if self.is_a?(ActiveRecord::Base) and persist + self.class.transaction do + aasm_fire_event_helper(name, persist, use_bang, *args) + end + else + aasm_fire_event_helper(name, persist, use_bang, *args) + end + rescue AASM::InvalidTransition => e + raise e if use_bang + return false + rescue ActiveRecord::ActiveRecordError => e + raise e if use_bang + return false + end + end + + # this method is the one that actually execute the whole + # transition. Order of execution: + # - fire before_all_transition callback + # - fire exit action for from state + # - fire the event, which will: + # - call guard on transition + # - execute the on_transition callback + # - fire enter action on the new state + # - fire the aasm_event_fire + # - log the transition + # - set the new state (persist/non persist) + # - fire after_all_transition + def aasm_fire_event_helper(name, persist, use_bang = false, *args) + aasm_fire_transition_callback(self.class.aasm_before_all_transition) + aasm_state_object_for_state(aasm_current_state).call_action(:exit, self, *args) new_state = self.class.aasm_events[name].fire(self, *args) + current_state = self.aasm_current_state unless new_state.nil? - aasm_state_object_for_state(new_state).call_action(:enter, self) + aasm_state_object_for_state(new_state).call_action(:enter, self, *args) if self.respond_to?(:aasm_event_fired) self.aasm_event_fired(self.aasm_current_state, new_state) end + result = true if persist - self.aasm_current_state_with_persistence = new_state + # adding logging here + self.do_log_transition(name, current_state, new_state, *args) + + result = self.send("aasm_current_state_with_persistence=", new_state, use_bang) self.send(self.class.aasm_events[name].success) if self.class.aasm_events[name].success else self.aasm_current_state = new_state end + aasm_fire_transition_callback(self.class.aasm_after_all_transition) - true + result else if self.respond_to?(:aasm_event_failed) self.aasm_event_failed(name) lib/aasm.rb @@ -10,6 +10,7 @@ module AASM @success = options[:success] @transitions = [] instance_eval(&block) if block + validate_transitions end def fire(obj, to_state=nil, *args) @@ -19,7 +20,7 @@ module AASM next_state = nil transitions.each do |transition| next if to_state and !Array(transition.to).include?(to_state) - if transition.perform(obj) + if transition.perform(obj, *args) next_state = to_state || Array(transition.to).first transition.execute(obj, *args) break @@ -31,11 +32,48 @@ module AASM def transitions_from_state?(state) @transitions.any? { |t| t.from == state } end + + def transitions_to_state?(state) + @transitions.any? { |t| Array(t.to).include?(state) } + end + + # get me all the possible states that the passed state + # can go to when calling firing this event + def get_to_states_when_transitioning_from(state) + @transitions.inject([]) do |memo, t| + memo.concat(Array(t.to)) if t.from == state + memo + end + end private + + def validate_transitions + # since we can have multiple froms and tos, + # we want to make sure that there is no confusion such as multiple transitions + # that contain same from and to states. + transitions = {} + @transitions.each do |transition| + next if !transition + if transitions.has_key?(transition.from) + existing_tos = transitions[transition.from] + this_tos_array = Array(transition.to) + this_tos_set = this_tos_array.to_set + if existing_tos & this_tos_set + raise AASM::InvalidTransition.new("You can't have transitions that have the same from state and to state.") + return + end + transitions[transition.from] = existing_tos.merge(this_tos_array) + else + transitions[transition.from] = Array(transition.to).to_set + end + end + end + def transitions(trans_opts) Array(trans_opts[:from]).each do |s| - @transitions << SupportingClasses::StateTransition.new(trans_opts.merge({:from => s.to_sym})) + transition = SupportingClasses::StateTransition.new(trans_opts.merge({:from => s.to_sym})) + @transitions << transition end end end lib/event.rb @@ -35,7 +35,7 @@ module AASM base.extend AASM::Persistence::ActiveRecordPersistence::ClassMethods base.send(:include, AASM::Persistence::ActiveRecordPersistence::InstanceMethods) base.send(:include, AASM::Persistence::ActiveRecordPersistence::ReadState) unless base.method_defined?(:aasm_read_state) - base.send(:include, AASM::Persistence::ActiveRecordPersistence::WriteState) unless base.method_defined?(:aasm_write_state) + base.send(:include, AASM::Persistence::ActiveRecordPersistence::WriteState) unless base.method_defined?(:aasm_write_state) or base.method_defined?(:aasm_write_state!) base.send(:include, AASM::Persistence::ActiveRecordPersistence::WriteStateWithoutPersistence) unless base.method_defined?(:aasm_write_state_without_persistence) if base.respond_to?(:named_scope) @@ -179,14 +179,32 @@ module AASM # # foo = Foo.find(1) # foo.aasm_current_state # => :opened - # foo.close! + # foo.close # foo.aasm_current_state # => :closed # Foo.find(1).aasm_current_state # => :closed # # NOTE: intended to be called from an event def aasm_write_state(state) - update_attribute(self.class.aasm_column, state.to_s) + write_attribute(self.class.aasm_column, state.to_s) + self.save + end + + # Writes <tt>state</tt> to the state column and persists it to the database + # using update_attributes! (which doesn't bypasses validation and + # will raise an exception if record is invalid) + # + # foo = Foo.find(1) + # foo.aasm_current_state # => :opened + # foo.close! + # foo.aasm_current_state # => :closed + # Foo.find(1).aasm_current_state # => :closed + # + # NOTE: intended to be called from an event + def aasm_write_state!(state) + write_attribute(self.class.aasm_column, state.to_s) + self.save! end + end module ReadState lib/persistence/active_record_persistence.rb @@ -15,13 +15,13 @@ module AASM end end - def call_action(action, record) + def call_action(action, record, to_state=nil, *args) action = @options[action] case action when Symbol, String - record.send(action) + record.send(action, *args) when Proc - action.call(record) + action.call(record, *args) end end lib/state.rb @@ -9,12 +9,14 @@ module AASM (@machines ||= {})[args] = val end - attr_accessor :states, :events, :initial_state + attr_accessor :states, :events, :initial_state, :before_all_transition, :after_all_transition attr_reader :name def initialize(name) @name = name @initial_state = nil + @before_all_transition = nil + @after_all_transition = nil @states = [] @events = {} end lib/state_machine.rb @@ -8,12 +8,12 @@ module AASM @opts = opts end - def perform(obj) + def perform(obj, *args) case @guard when Symbol, String - obj.send(@guard) + obj.send(@guard, *args) when Proc - @guard.call(obj) + @guard.call(obj, *args) else true end lib/state_transition.rb @@ -1 +1,4 @@ require File.join(File.dirname(__FILE__), '..', 'aasm') +require File.join(File.dirname(__FILE__), '../../rspec-rails/spec/spec_helper') + + spec/spec_helper.rb @@ -139,10 +139,10 @@ describe AASM, '- event firing with persistence' do it 'should attempt to persist if aasm_write_state is defined' do foo = Foo.new - def foo.aasm_write_state + def foo.aasm_write_state! end - foo.should_receive(:aasm_write_state) + foo.should_receive(:aasm_write_state!) foo.close! end @@ -166,12 +166,12 @@ describe AASM, '- event firing without persistence' do it 'should attempt to persist if aasm_write_state is defined' do foo = Foo.new - def foo.aasm_write_state + def foo.aasm_write_state(state) end foo.should_receive(:aasm_write_state_without_persistence) - foo.close + foo.close_not_persist end end @@ -339,3 +339,163 @@ describe ChetanPatil do cp.dress!(:dating, 'purple', 'slacks') end end + +class Order + include AASM + aasm_log_method :my_log_method + aasm_initial_state :received + aasm_before_all_transition :before_all + aasm_after_all_transition Proc.new {|obj| obj.after_all} + aasm_state :processed, :enter => Proc.new {|obj| obj.increment_processed_count}, :exit => :increment_processed_exit + aasm_state :shipped + aasm_state :received + + aasm_event :process do + transitions :from => [:received, :processed], :to => :processed + end + + aasm_event :ship do + transitions :from => :processed, :to => :shipped, \ + :on_transition => Proc.new {|obj, *args| obj.finally_ship_item(*args)} + end + + aasm_event :receive do + transitions :from => [:received, :processed, :shipped], :to => :error + end + + attr_accessor :processed_count, :processed_exit, :test_attr + + def after_all(*args) + end + + def before_all(*args) + end + + def increment_processed_count + processed_count = 0 if processed_count.nil? + processed_count += 1 + end + + def increment_processed_exit(*args) + processed_exit = 0 if processed_exit.nil? + processed_exit += 1 + end + + def finally_ship_item(test) + test_attr = test + end + + def my_log_method(user, comment=nil) + + end + + def aasm_ship_log(user, comment=nil) + end + + def write_attribute(name, value) + end + + def save + true + end + + def save! + end +end + +describe Order do + it 'should respond to the new non persistent event #{event}_not_persist' do + o = Order.new + o.process_not_persist + + o.aasm_current_state.should == :processed + end + + it 'should respond to the new persistent wihtout bang' do + o = Order.new + o.should_receive(:aasm_write_state) + o.process + + o.aasm_current_state.should == :processed + end + + it 'should call the before all transition callback' do + o = Order.new + o.should_receive(:aasm_write_state) + o.should_receive(:before_all) + o.process + + o.aasm_current_state.should == :processed + end + + it 'should call the after all transition callback, which in turn call after all method' do + o = Order.new + o.should_receive(:aasm_write_state) + o.should_receive(:after_all) + o.process + + o.aasm_current_state.should == :processed + end + + + it 'should respond to the new persistent with bang' do + o = Order.new + o.should_receive(:aasm_write_state!) + o.process! + + o.aasm_current_state.should == :processed + end + + it 'since we specify we want to log, we will log the event' do + o = Order.new + o.should_receive(:my_log_method) + o.process! + + o.aasm_current_state.should == :processed + end + + it 'since we specify we don\'t want to log, we will not log the event' do + o = Order.new + o.aasm_log_transition = false + o.should_not_receive(:my_log_method) + o.process! + + o.aasm_current_state.should == :processed + end + + it 'we should still execute the callback even though we are transitioning to and from the same state' do + o = Order.new + o.aasm_current_state.should == :received + o.process! + o.aasm_current_state.should == :processed + + o.should_receive(:my_log_method, 2) + o.should_receive(:increment_processed_count) + o.should_receive(:increment_processed_exit) + o.should_receive(:aasm_write_state!) + o.process! + o.aasm_current_state.should == :processed + end + + it 'if we create a specialized log method by convention of: "aasm_#{event_name}_log", we will executed that log if the log is enabled' do + o = Order.new + o.process + + o.aasm_current_state.should == :processed + + o.should_receive(:aasm_ship_log) + o.ship!(:shipped, true) + o.aasm_current_state.should == :shipped + end + + it 'if we don\'t pass the destination state, it should just go to the first one. ' do + o = Order.new + o.process + + o.aasm_current_state.should == :processed + + o.should_receive(:aasm_ship_log) + o.ship!(true) + o.aasm_current_state.should == :shipped + end +end spec/unit/aasm_spec.rb @@ -1,4 +1,5 @@ require File.join(File.dirname(__FILE__), '..', '..', 'lib', 'aasm') +require File.join(File.dirname(__FILE__), '..', 'spec_helper') begin require 'rubygems' @@ -8,6 +9,20 @@ begin class Connection end + class ExtFooBar < ActiveRecord::Base + include AASM + + # Fake this column for testing purposes + attr_accessor :aasm_state + + aasm_state :open + aasm_state :closed + + aasm_event :view do + transitions :to => :closed, :from => [:open] + end + end + class FooBar < ActiveRecord::Base include AASM @@ -36,6 +51,13 @@ begin include AASM end + class ExtFo < ActiveRecord::Base + def aasm_write_state!(state) + "fo" + end + include AASM + end + class Fum < ActiveRecord::Base def aasm_write_state_without_persistence(state) "fum" @@ -100,6 +122,22 @@ begin end end + describe ExtFo, "class methods" do + before(:each) do + @klass = ExtFo + end + it_should_behave_like "aasm model" + it "should include AASM::Persistence::ActiveRecordPersistence::ReadState" do + @klass.included_modules.should be_include(AASM::Persistence::ActiveRecordPersistence::ReadState) + end + it "should not include AASM::Persistence::ActiveRecordPersistence::WriteState" do + @klass.included_modules.should_not be_include(AASM::Persistence::ActiveRecordPersistence::WriteState) + end + it "should include AASM::Persistence::ActiveRecordPersistence::WriteStateWithoutPersistence" do + @klass.included_modules.should be_include(AASM::Persistence::ActiveRecordPersistence::WriteStateWithoutPersistence) + end + end + describe Fum, "class methods" do before(:each) do @klass = Fum @@ -178,6 +216,18 @@ begin end + describe ExtFooBar, "instance methods" do + before(:each) do + connection = mock(Connection, :columns => []) + ExtFooBar.stub!(:connection).and_return(connection) + end + + it "should respond to aasm read state with bang when not previously defined" do + ExtFooBar.new.should respond_to(:aasm_write_state!) + end + end + + # TODO: figure out how to test ActiveRecord reload! without a database rescue LoadError => e spec/unit/active_record_persistence_spec.rb @@ -47,3 +47,15 @@ describe AASM::SupportingClasses::Event, 'when firing an event' do event.fire(obj).should == :closed end end + +describe AASM::SupportingClasses::Event, 'when declaring the transitions in event block ' do + it 'should raise an AASM::InvalidTransition error if the transitions are ambiguous' do + lambda { + AASM::SupportingClasses::Event.new(:event) do + transitions :from => [:one, :two], :to => [:four,:five], :on_transition => :do_one + transitions :from => [:one, :three], :to => [:five, :six], :on_transition => :do_two + end + }.should raise_error(AASM::InvalidTransition) + end +end + spec/unit/event_spec.rb 2d87b4b3b1e35fbd47b6bec5374990afa197d9c0 Scott Diedrick swalterd@gmail.com http://github.com/mumboe/aasm/commit/80365eecb89ea88096929f70df3227f1a204cf84 80365eecb89ea88096929f70df3227f1a204cf84 2009-06-24T15:36:34-07:00 2009-06-24T15:36:34-07:00 Adding logging support 0bea47a2a6d617a19f278b6cce5d77729344af08 Scott Diedrick swalterd@gmail.com