rbpm 0.0.2 → 0.0.3

data/lib/rbpm/workflow.rb

@@ -0,0 +1,457 @@
+#---------------------------------------------------------------------------------------------------------------------------------
+#
+# rbpm lightweight workflows, copyright (c) 2005 Christian Tschenett <furthermore@nospam@tschenett.ch>
+#
+# This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License 
+# as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
+# This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty 
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+# You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the 
+# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+#
+#---------------------------------------------------------------------------------------------------------------------------------
+
+module Rbpm
+  
+  #workflow base class. do not instantiate this class - always create sub classes!
+  #maybe you dont want to instantiate workflows directly or call workflow instance methods
+  #directly - use some sort of a workflow manager facade for this purpose.
+  class Workflow
+  
+    ##WORKFLOW METADATA
+  
+    #@@meta will be a class attribute of a concrete Workflow
+    def self.init_meta
+      module_eval <<-end_eval  
+        unless defined? @@meta
+          @@meta = {}
+          def self.meta
+            @@meta
+          end
+        end
+      end_eval
+    end
+
+    #insert generic node helper...
+  
+    #adds a node to the workflow.
+    def self.node(node_sym, options = {})
+      self.init_meta
+      self.nodes[node_sym] = {} unless self.nodes[node_sym]
+      options.each do |key,value|
+        case key.to_s
+          when /(.*)_trans$|trans$/
+            trans = $1.nil? ? "default" : $1
+            transition(node_sym, trans.to_sym, value)
+          when /(.*)_trans_action$|trans_action$/
+            trans = $1.nil? ? "default" : $1
+            transition_action(node_sym, trans.to_sym, value)
+          when /(.*)_trans_cond$|trans_cond$/
+            trans = $1.nil? ? "default" : $1
+            transition_condition(node_sym, trans.to_sym, value)
+          when "exception"
+            exception_transition(node_sym, value)
+          when "action"
+            node_action(node_sym, value)
+          when "on_enter"
+            node_enter_action(node_sym, value)
+          when "on_leave"
+            node_leave_action(node_sym, value)
+          when "action_singleton"
+            node_action_singleton(node_sym, value)
+        end
+      end
+    end
+
+    #insert special nodes helpers...
+
+    #adds the start node to the worklow. min/max one start node is allowed per workflow.
+    def self.start_node(node_sym, options = {})
+      node(node_sym, options)
+      nodes[node_sym][:start] = true
+    end
+  
+    #adds an end node to the workflow.
+    def self.end_node(node_sym, options = {})
+      node(node_sym, options)
+      nodes[node_sym][:end] = true
+    end
+  
+    #adds a state node to the workflow.
+    def self.state_node(node_sym, options = {})
+      node(node_sym, options)
+      nodes[node_sym][:state] = true
+    end
+  
+    def self.create_join_node_instance
+      JoinNode.new
+    end
+  
+    #adds a join node to the workflow.
+    def self.join_node(node_sym, options = {})
+      options[:action_singleton] = self.create_join_node_instance
+      node(node_sym, options)
+    end
+  
+    def self.create_fork_node_instance(children_ctx)
+      ForkNode.new children_ctx
+    end
+  
+    #adds a fork node to the workflow.
+    def self.fork_node(node_sym, options = {})
+      options[:action_singleton] = self.create_fork_node_instance(options[:children_ctx])
+      node(node_sym, options)
+    end
+  
+    #adds a call node to the workflow.
+    def self.call_node(node_sym, options = {})
+      options[:action_singleton] = CallNode.new(options[:workflow], options[:workflow_version], options[:call_in], options[:call_out])
+      node(node_sym, options)
+    end
+    
+    #insert node action helpers...
+  
+    #adds a on_node_enter action block to the workflow.
+    def self.enter(node_sym, &blk)
+      node_enter_action(node_sym, blk)
+    end
+  
+    def self.node_enter_action(node_sym, action)
+      nodes[node_sym][:on_enter] = action
+    end
+  
+    def self.action(node_sym, &blk)
+      node_action(node_sym, blk)
+    end
+  
+    def self.node_action(node_sym, action)
+      nodes[node_sym][:action] = action
+    end
+  
+    #adds a on_node_leave action block to the workflow.
+    def self.leave(node_sym, &blk)
+      node_leave_action(node_sym, blk)
+    end
+  
+    def self.node_leave_action(node_sym, action)
+      nodes[node_sym][:on_leave] = action
+    end
+  
+    def self.node_action_singleton(node_sym, instance)
+      nodes[node_sym][:action_singleton] = instance
+    end  
+    
+    #insert transition, transition action and transition condition helpers...
+    
+    def self.transition(node_from_sym, trans_sym, node_to_sym)
+      transitions(node_from_sym)[trans_sym] = node_to_sym
+    end
+  
+    def self.transition_action(node_from_sym, trans_sym, action)
+      transition_actions(node_from_sym)[trans_sym] = action
+    end
+  
+    #adds a on_transit action block to the workflow.
+    def self.transit(node_from_sym, trans_sym, &blk)
+      transition_action(node_from_sym, trans_sym, blk)
+    end
+  
+    def self.transition_condition(node_from_sym, trans_sym, condition)
+      transition_conditions(node_from_sym)[trans_sym] = condition
+    end
+  
+    def self.exception_transition(node_from_sym, node_to_sym)
+      transition(node_from_sym, :exception, node_to_sym)
+      transition_condition(node_from_sym, :exception, "false") #only executed if "hardcoded" signalled
+    end
+  
+    #metadata access helpers...
+    
+    def self.nodes
+      meta[:nodes] = {} unless meta[:nodes]
+      meta[:nodes]
+    end  
+  
+    def self.node_option_values(node, option)
+      nodes[node][option] = {} unless nodes[node][option]
+      nodes[node][option]
+    end
+  
+    def self.transitions(node)
+      node_option_values(node, :transitions)
+    end
+  
+    def self.transition_actions(node)
+      node_option_values(node, :transition_actions)
+    end
+  
+    def self.transition_conditions(node)
+      node_option_values(node, :transition_conditions)
+    end
+  
+    def self.find_first_node_with_option(option)
+      nodes.each do |node,options|
+        return node if options[option]
+      end
+      nil
+    end
+  
+    def self.find_nodes_with_option(option)
+      found = nodes.collect do |node,options|
+        options[option] ? node : nil
+      end
+      found.compact
+    end
+  
+    def self.find_node_with_name(name)
+      nodes[name.to_sym]
+    end
+  
+    def self.find_start_node
+      find_first_node_with_option :start
+    end
+  
+    def self.find_end_nodes
+      find_nodes_with_option :end
+    end
+  
+    def self.end_node?(node)
+      nodes[node][:end]
+    end
+  
+    @@next_token_id = 1
+  
+    def self.generate_token_id
+      @@next_token_id += 1
+    end
+  
+    ##WORKFLOW INSTANCE
+  
+    attr_writer :token_id_generator
+    attr_reader :tokens, :result, :token_id_generator, :super_workflow_ref
+  
+    def initialize(super_workflow_ref = -1)
+      @super_workflow_ref = super_workflow_ref
+      @tokens = []
+      @result = nil
+    end
+  
+    def clazz
+      self.class
+    end
+  
+    #token management...
+  
+    def generate_token_id
+      if token_id_generator
+        token_id_generator.generate_token_id @super_workflow_ref
+      else
+        clazz.generate_token_id
+      end
+    end
+  
+    def create_root_token(ctx_vars = {})
+      create_token(nil, ctx_vars)
+    end
+  
+    def create_token_instance(parent = nil, ctx_vars = {})
+      Token.new(self, parent, ctx_vars, generate_token_id)
+    end
+  
+    def create_token(parent = nil, ctx_vars = {})
+      token = create_token_instance(parent, ctx_vars)
+      @tokens << token
+      token
+    end
+  
+    def token_done(token)
+      unless token.parent
+        @result = token.all_ctx_vars
+      end
+    
+      @tokens.delete token
+    end
+  
+    def find_root_token
+      @tokens.each do |token|
+        return token unless token.parent
+      end
+      nil?
+    end
+    
+    def find_token(ref)
+      @tokens.each do |token|
+        found = token.find_token(ref)
+        if found
+          return found
+        end
+      end
+      nil?
+    end
+  
+    def all_tokens(&blk)
+      @tokens.each do |token|
+        token.all_tokens(&blk)
+      end
+    end
+  
+    def [](key)
+      if @result
+        @result[key]
+      else
+        find_root_token[key]
+      end
+    end
+  
+    #(metadata-driven) reflection helpers...
+  
+    def find_method(method_name)
+      action = method(method_name) if methods.include? method_name
+        
+      unless action    
+        action = clazz.method(method_name) if clazz.methods.include? method_name
+      end
+    
+      action
+    end
+  
+    def find_node_event_action(node, default_method_suffix, action_option)
+      default_method_name = "#{node.to_s}#{default_method_suffix}"
+    
+      action_singleton = clazz.nodes[node][:action_singleton]
+      action = action_singleton.method(action_option) if action_singleton && action_singleton.methods.include?(action_option.to_s)
+    
+      unless action
+        action = find_method(default_method_name)
+      end
+    
+      unless action
+        action_or_name = clazz.nodes[node][action_option] 
+      
+        if action_or_name.is_a? Symbol
+          action_name = action_or_name.to_s
+          action = find_method(action_name)
+        
+          raise "unknown custom action #{action_name}" unless action
+        else
+          action = action_or_name
+        end
+      end
+    
+      action
+    end
+  
+    def find_enter_action(node)
+      find_node_event_action(node, "_on_enter", :on_enter)
+    end
+
+    def find_leave_action(node)
+      find_node_event_action(node, "_on_leave", :on_leave)
+    end  
+  
+    def find_node_action(node)
+      find_node_event_action(node, "_action", :action)
+    end
+
+    def find_transit_action(node, transition)
+      default_method_name = "#{node.to_s}_#{transition.to_s}_trans_action"
+      action = find_method(default_method_name)
+    
+      unless action
+        action_or_name = clazz.transition_actions(node)[transition]
+      
+        if action_or_name.is_a? Symbol
+          action_name = action_or_name.to_s
+          action = find_method(action_name)
+        
+          raise "unknown custom action #{action_name}" unless action
+        else
+          action = action_or_name
+        end
+      end
+    
+      action
+    end
+  
+    def find_transit_target(node, transition)
+      clazz.transitions(node)[transition]
+    end  
+  
+    #flow management...
+  
+    #starts the workflow instance by creating the root token which
+    #takes a hidden transition to the start node. root token variable
+    #initialization is done as well.
+    #only call this method once per workflow instance!
+    def start(ctx_vars = {})
+      token = create_root_token(ctx_vars)
+      token.enter(clazz.find_start_node)
+      token
+    end
+  
+    def call_event_action(action, token, node)
+      begin
+        action.call(token, node) 
+      rescue Exception => exception
+        if clazz.transitions(node)[:exception]
+          token[:exception] = exception
+          return :exception
+        else
+          raise
+        end
+      end
+      return nil
+    end
+  
+    def enter_node(token, node)
+      token.entered(node)
+    
+      hardcoded_transition = call_event_action(find_enter_action(node), token, node) if find_enter_action(node)
+    
+      if hardcoded_transition || (not (clazz.end_node?(node) || clazz.nodes[node][:state]))
+        signal_node(token, node, hardcoded_transition)
+      end
+    end
+  
+    def signal_node(token, node, hardcoded_transition = nil)
+      if hardcoded_transition
+        transitions = [[hardcoded_transition, token]]
+      elsif find_node_action(node)
+        transitions = find_node_action(node).call(token, node) 
+      else
+        clazz.transitions(node).each do |transition,target|
+          if (clazz.transition_conditions(node)[transition].nil? || token.eval_expr(clazz.transition_conditions(node)[transition]))
+            transitions = [[transition, token]]
+            break
+          end
+        end
+      end
+    
+      if not clazz.nodes[node][:end] and transitions
+        take_transitions transitions
+      end
+    end
+    
+    def take_transitions(transition_tokens)
+      #pseudo-parallel execution (token one leaves the node until it reaches a state. afterwards, token two leaves the node...)
+      transition_tokens.each do |transition_token|
+        transition,token = transition_token
+        token.transit(transition)
+      end
+    end
+  
+    def leave_node(token, node)
+      call_event_action(find_leave_action(node), token, node) if find_leave_action(node)
+    end
+  
+    def transit(token, node, transition)
+      hardcoded_transition = call_event_action(find_transit_action(node, transition), token, node) if find_transit_action(node, transition)
+    
+      if hardcoded_transition
+        enter_node(token, find_transit_target(node, hardcoded_transition))
+      else
+        enter_node(token, find_transit_target(node, transition))
+      end
+    end
+  end
+end