rbpm 0.0.1

data/README

@@ -0,0 +1,18 @@
+what is rBPM?
+
+	rbpm is a (JBoss-)jBPM-like lightweight workflow framework. it helps you to
+	develop asynchronous programs. developers describe their process definitions 
+	(workflows) using extended ruby class definition syntax - no use of xml 
+	files is planned.
+
+license terms?
+
+	LGPL
+
+author?
+
+	(c) 2005 by Christian Tschenett
+
+getting startet...
+
+	take a look at the unit tests

data/docs/todo.txt

@@ -0,0 +1,12 @@
+[ok] 		workflow instance persistence
+[ok] 		states
+[ok]		context variables
+[ok]		versioning
+[ok]		more nodes (join, fork)
+[ok]		more nodes (call)
+[ok]		conditions
+[~ok]		consistent and clean meta syntax
+[~ok]		clean block support
+[pending]	rbpm server
+[pending]	rpbm server java/web service interface
+[ok]		workflow support for exception handling

data/lib/rbpm.rb

@@ -0,0 +1,590 @@
+class WorkflowVersionManager
+  def self.find_workflow_versions(workflow_name)
+    versions = []
+    ObjectSpace.each_object(Module) do |m|
+      module_name = m.to_s
+      if module_name =~ /#{workflow_name}Version([0-9]+)$/
+        versions << $1.to_i
+      end
+    end
+    versions
+  end
+  
+  def self.create_workflow_instance(workflow_name, version = :latest)
+    workflow_name = workflow_name.to_s if workflow_name.is_a? Symbol
+    if :latest == version
+      versions = find_workflow_versions(workflow_name)  
+      if versions.empty?
+        #fallback to non-versionned wf
+        return eval("#{workflow_name}.new")
+      else
+        version = versions.max
+      end  
+    end
+    return eval("#{workflow_name}Version#{version}::#{workflow_name}.new")
+  end
+end
+
+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...
+  
+  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...
+
+  def self.start_node(node_sym, options = {})
+    node(node_sym, options)
+    nodes[node_sym][:start] = true
+  end
+  
+  def self.end_node(node_sym, options = {})
+    node(node_sym, options)
+    nodes[node_sym][:end] = true
+  end
+  
+  def self.state_node(node_sym, options = {})
+    node(node_sym, options)
+    nodes[node_sym][:state] = true
+  end
+  
+  def self.join_node(node_sym, options = {})
+    options[:action_singleton] = JoinNode.new
+    node(node_sym, options)
+  end
+  
+  def self.fork_node(node_sym, options = {})
+    options[:action_singleton] = ForkNode.new(options[:children_ctx])
+    node(node_sym, options)
+  end
+  
+  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...
+  
+  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
+  
+  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
+  
+  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
+  
+  def initialize
+    @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
+    else
+      clazz.generate_token_id
+    end
+  end
+  
+  def create_root_token(ctx_vars = {})
+    create_token(nil, ctx_vars)
+  end
+  
+  def create_token(parent = nil, ctx_vars = {})
+    token = Token.new(self, parent, ctx_vars, generate_token_id)
+    @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 [](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...
+  
+  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
+      transitions.each do |transition_token|
+        transition,token = transition_token
+        token.transit(transition)
+      end
+    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
+
+class Token
+  
+  attr_writer :sub_process, :parent_process
+  attr_reader :workflow, :node, :parent, :sub_process, :parent_process, :ref
+  
+  def initialize(workflow, parent = nil, ctx_vars = {}, ref = -1)
+    @workflow = workflow
+    @parent = parent
+    @ctx_vars = ctx_vars
+    @ref = ref
+    @childs = []
+    @sub_process = nil
+    @parent_process = nil
+    @done = false
+    if parent
+      @node = parent.node
+      @parent.add_child(self)
+    else
+      @node = nil
+    end
+  end
+
+  def all_ctx_vars
+    @ctx_vars
+  end
+  
+  def token
+    self
+  end
+  
+  def []=(key, value)
+    @ctx_vars[key] = value
+  end
+  
+  def [](key)
+    @ctx_vars[key]
+  end
+  
+  def add_child(token)
+    @childs << token
+  end
+  
+  def remove_child(token)
+    @childs.delete(token)
+  end
+  
+  def childs?
+    not @childs.empty?
+  end
+  
+  def signal
+    @workflow.signal_node(self, node)
+    
+    if end? && @parent_process
+      @parent_process.signal
+      @parent_process = nil
+    end
+  end
+  
+  def enter(node)
+    @workflow.enter_node(self, node)
+  end
+  
+  def entered(node)
+    @node = node
+    
+    if @workflow.clazz.end_node?(@node) and not @parent
+      @workflow.token_done(self)
+    end
+  end
+  
+  def transit(transition)
+    hardcoded_transition = @workflow.leave_node(self, @node)
+    if hardcoded_transition
+      @workflow.transit(self, @node, hardcoded_transition)
+    else
+      @workflow.transit(self, @node, transition)
+    end
+  end
+  
+  def jump(child)
+    @node = child.node
+  end
+  
+  def done
+    @parent.remove_child(self) if @parent
+    @parent.jump(self) if @parent
+    @workflow.token_done(self)
+    @done = true
+  end
+  
+  def end?
+    @done || @workflow.clazz.end_node?(@node)
+  end
+  
+  def fork(ctx_vars = {})
+    @workflow.create_token(self, ctx_vars)
+  end
+  
+  def eval_expr(expr)
+    eval(expr, binding())
+  end
+end
+
+class ForkNode
+  def initialize(children_ctx_var)
+    @children_ctx_var = children_ctx_var
+  end
+  
+  def action(token, caller)
+    exits = []
+    token[@children_ctx_var].each do |ctx_vars|
+      exits << [:default, token.fork(ctx_vars)] 
+    end
+    return exits
+  end
+end
+
+class JoinNode
+  def action(token, caller)
+    parent_token = token.parent
+    token.done
+    parent_token.childs? ? nil : [[:default, parent_token]]
+  end
+end
+
+class CallNode
+  def initialize(workflow, workflow_version, call_in, call_out)
+    @workflow = workflow
+    @workflow_version = workflow_version
+    @call_in = call_in
+    @call_out = call_out
+  end
+  
+  def action(token, caller)
+    if token.sub_process
+      #sub process has been finished...
+      
+      @call_out.each do |remote,local|
+        token[local] = token.sub_process[remote]
+      end
+  
+      token.sub_process = nil
+  
+      return [[:default, token]]
+    else
+      #let's start a sub process...
+    
+      if (@workflow.is_a? Symbol)
+        sub_wf = WorkflowVersionManager.create_workflow_instance(@workflow, @workflow_version.nil? ? :latest : @workflow_version)
+      else
+        sub_wf = @workflow.new
+      end
+    
+      params = {}
+      @call_in.each do |local,remote|
+        params[remote] = token[local]
+      end
+    
+      sub_t = sub_wf.start(params)
+    
+      if (sub_t.end?)
+        @call_out.each do |remote,local|
+          token[local] = sub_t[remote]
+        end
+    
+        return [[:default, token]]
+      else
+        sub_t.parent_process = token
+        token.sub_process = sub_t
+      
+        return nil #stop wf execution... we'll be called later...
+      end
+    end
+  end
+end