rbpm 0.0.2 → 0.0.3

data/lib/rbpm/nodes.rb

@@ -0,0 +1,109 @@
+#---------------------------------------------------------------------------------------------------------------------------------
+#
+# 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
+  
+  #the arriving (parent-) token won't leave the node using the node's default transition. in lieu thereof, a number
+  #of cild tokens will be generated and every child token will leave the node using the node's :default transition
+  #immediately. only one leaving transition - :default - is allowed. the number of child tokens is determined by
+  #the length of the :children_ctx token context variable. the :children_ctx token variable holds a hash of initial
+  #context variables for every child token (:token_variable_name => token_variable_content hash).
+  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
+
+  #arriving child tokens - generated by a fork node - are consumed upon arrival. the last arriving child token transfers the
+  #child's parent token to this node which will leave the node immediately using the node's :default transition. thus, only
+  #one leaving transition - :default - is allowed. children token variables will also be lost upon arrival of their associated
+  #tokens - you have to save child tokens variables manually if you want to preserve them (by copying them to the parent token's
+  #context, for instance) 
+  class JoinNode
+    def action(token, caller)
+      parent_token = token.parent
+      token.done
+      parent_token.childs? ? nil : [[:default, parent_token]]
+    end
+  end
+
+  #the arriving token triggers the creation and execution of a named sub process instance/workflow. token variables mentioned in
+  #the :call_in mapping are copied from arriving token's context to the root token of the newly created sub process instance
+  #before starting the sub process instance. if the sub workflow does not contain states - and therefore the sub 
+  #workflow will terminate immediately -, the token will leave the call node
+  #immediately using the node's :default transition. only one leaving transition - :default - is allowed. before leaving,
+  #all token variables mentioned in the :call_out mapping are copied from the sub workflow's root token context to the 
+  #context of the token waiting in the call node. otherwise, if the sub workflow's root token arrived in a state, the token remains in the
+  #call node and - from a workflow user's point of view - the call node behaves like a state node. but do not call signal
+  #on the token waiting in the call node! you have to call signal on the sub workflow's token waiting in the sub workflow's
+  #state node - the node waiting in the call node will be signaled automatically upon sub workflow termination.
+  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, token.workflow.super_workflow_ref)
+        else
+          sub_wf = @workflow.new(token.workflow.super_workflow_ref)
+        end
+        sub_wf.token_id_generator = token.workflow.token_id_generator
+    
+        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
+end

data/lib/rbpm/persistence2.rb

@@ -0,0 +1,265 @@
+#---------------------------------------------------------------------------------------------------------------------------------
+#
+# 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
+#
+#---------------------------------------------------------------------------------------------------------------------------------
+
+require 'yaml'
+
+module Rbpm
+  #placeholder
+end
+
+module Rbpm::FlockFileSystem
+  
+  class WorkflowPersistenceManager
+    def initialize(index_file_path)
+      @token_list = WorkflowTokenIndex.new index_file_path
+    end
+    
+    #creates a - named - workflow and starts the workflow afterwards.
+    #if the workflow is not finished - a token waits in a state -
+    #after execution, the current state of the workflow - and
+    #the state of started sub workflows as well - will be
+    #persisted in a YAML file associated with the workflow instance.
+    #furthermore, all active tokens - and child tokens, and
+    #tokens of started sub processes as well - are added to the
+    #token list and the current state of the token list (some sort
+    #of index which allows to find a persisted workflow associated
+    #with a token) will be persisted too. 
+    def create_and_start(workflow_name, token_vars = {})
+      wf_ref = @token_list.create_new_super_workflow_id
+      begin
+        wf = Rbpm::WorkflowVersionManager.create_workflow_instance workflow_name, :latest, wf_ref
+        wf.token_id_generator = @token_list
+        t = wf.start token_vars
+        unless t.end?
+          create_persistent_workflow wf, wf_ref
+          wf_ref = nil
+        end
+        return t.freeze
+      ensure
+        @token_list.update_workflow_tokens(wf_ref, []) if wf_ref
+      end
+    end
+    
+    #sends a signal to a token associated with a persisted workflow (only token
+    #residing in a state should be signaled). the state of the "root-parent" workflow
+    #of the workflow associated with the token - can be the workflow itself :) -
+    #is loaded from disk - and therefore the state of all sub workflows is restored as well -
+    #and the token is signalled afterwards. from now on, this method behaves like
+    #create_and_start: the state is only persisted again, if there is at least one
+    #token waiting in a state after execution. this means that you business logic
+    #has to preserve all relevant information stored as token context variables!
+    def signal(token_ref, token_vars = {})
+      wf_ref = @token_list.lookup_super_workflow token_ref
+      wf_tokens = []
+      begin
+        modify_lock_workflow(wf_ref, true) do |wf|
+          token = wf.find_token token_ref
+          token_vars.each do |key,value|
+            token[key] = value
+          end
+          token.signal
+          wf.all_tokens do |wf_token|
+            wf_tokens << wf_token.ref unless wf_token.end?
+          end
+          return token.freeze
+        end
+      ensure
+        @token_list.update_workflow_tokens wf_ref, wf_tokens
+      end
+    end
+    
+    #returns a freezed version of a token associated with a persisted workflow. the
+    #workflow is loaded using the logic mentioned in the comment of the signal method.
+    #using this method you can gain access to token variables of tokens waiting
+    #in states. as mentioned above, you cannot access the token context of "finished"
+    #tokens because they are already destroyed!
+    def freezed_token(token_ref)
+      wf_ref = @token_list.lookup_super_workflow token_ref
+      modify_lock_workflow(wf_ref, false) do |wf|
+        token = wf.find_token token_ref
+        return token.freeze
+      end
+    end
+   
+    protected
+    
+    def create_persistent_workflow(wf, wf_ref)
+      file = File.open("rbpm-workflow-#{wf_ref}.yml", "w+") do |file|
+        file.flock(File::LOCK_EX)
+        write(file, wf)
+        file.flock(File::LOCK_UN)
+      end
+      wf_tokens = []
+      wf.all_tokens do |wf_token|
+        wf_tokens << wf_token.ref unless wf_token.end?
+      end
+      @token_list.update_workflow_tokens wf_ref, wf_tokens
+    end
+    
+    def modify_lock_workflow(wf_ref, write_back) #do |wf|
+      delete_path = nil
+      begin
+        file = File.open("rbpm-workflow-#{wf_ref}.yml", "r+") do |file|
+          file.flock(File::LOCK_EX)
+          begin
+            wf = read(file)
+            begin
+              yield(wf)
+            ensure
+              unless wf.find_root_token
+                delete_path = file.path
+              else
+                if write_back
+                  file.pos = 0
+                  file.truncate 0
+                  write(file, wf)
+                end
+              end
+            end
+          ensure
+            file.flock(File::LOCK_UN)
+          end
+        end
+      ensure
+        File.delete delete_path if delete_path
+      end
+    end
+    
+    def read(f)
+      content = ""
+      while (line = f.gets)
+        content = content + "\n" + line
+      end
+      YAML.load(content)
+    end
+    
+    def write(file, object)
+      content = YAML.dump(object)
+      file.puts content
+    end
+  end
+  
+  class WorkflowTokenIndex
+    def initialize(index_file_path)
+      @index_file_path = index_file_path
+    end 
+      
+    def lookup_super_workflow(lookup_token_id)
+      return nil unless index_file_exists?
+      file = open_read_locked_index_file
+      begin
+        while (token_workflow = read_index_entry file)
+          token_id, workflow_id = token_workflow
+          return workflow_id if token_id == lookup_token_id
+        end
+      ensure
+        close_unlock_file file
+      end
+      return nil
+    end
+    
+    def update_workflow_tokens(super_workflow_id, token_ids)
+      manage_workflow_tokens :update_workflow_tokens, super_workflow_id, token_ids
+    end
+    
+    def create_new_super_workflow_id
+      manage_workflow_tokens
+    end
+    
+    def generate_token_id(super_workflow_id)
+      manage_workflow_tokens :create_new_workflow_token_id, super_workflow_id
+    end
+    
+    protected
+    
+    def manage_workflow_tokens(operation = :create_super_workflow_and_placeholder_token, super_workflow_id = nil, token_ids = [])
+      token_workflows = []
+      not_empty = index_file_exists?
+      file = not_empty ? open_readwrite_locked_index_file : open_create_locked_index_file
+      begin
+        max_id = -1;
+        if not_empty          
+          while (token_workflow = read_index_entry file)
+            token_id, workflow_id = token_workflow
+            case operation
+              when :update_workflow_tokens
+                token_workflows << token_workflow unless workflow_id == super_workflow_id          
+              when :create_super_workflow_and_placeholder_token 
+                token_workflows << token_workflow
+                max_id = workflow_id if workflow_id > max_id
+              when :create_new_workflow_token_id
+                token_workflows << token_workflow
+                max_id = token_id if token_id > max_id
+            end
+          end
+          file.pos = 0
+          file.truncate 0
+        end
+        case operation
+          when :create_super_workflow_and_placeholder_token
+            super_workflow_id = (max_id + 1)
+            token_ids << -1
+          when :create_new_workflow_token_id
+            token_ids << (max_id + 1)
+        end
+        token_ids.each do |token_id|
+          token_workflows << [token_id, super_workflow_id]
+        end
+        token_workflows.each do |token_workflow|
+          token_id, workflow_id = token_workflow
+          file.puts token_id
+          file.puts workflow_id
+        end
+        return (max_id + 1)
+      ensure
+        close_unlock_file file
+        File.delete file.path if token_workflows.empty?
+      end
+    end
+    
+    def index_file_exists?
+      File.exist?(@index_file_path)
+    end
+    
+    def open_read_locked_index_file
+      file = File.open(@index_file_path, "r")
+      file.flock(File::LOCK_EX)
+      return file
+    end
+    
+    def open_readwrite_locked_index_file
+      file = File.open(@index_file_path, "r+")
+      file.flock(File::LOCK_EX)
+      return file
+    end
+    
+    def open_create_locked_index_file
+      file = File.open(@index_file_path, "w+")
+      file.flock(File::LOCK_EX)
+      return file
+    end
+    
+    def read_index_entry(file)
+      token_id = file.gets
+      return nil unless 
+      workflow_id = file.gets
+      return nil unless workflow_id
+      return [token_id.to_i, workflow_id.to_i]
+    end
+    
+    def close_unlock_file(file)
+      file.flock(File::LOCK_UN)
+      file.close
+    end
+  end
+end

data/lib/rbpm/persistence2_standalone.rb

@@ -0,0 +1,46 @@
+begin
+  require 'rubygems'
+  require_gem 'rbpm', '>= 0.0.3'
+rescue LoadError
+  require '../lib/rbpm'
+end
+
+def args_to_hash(args, start_index = 1)
+  result = {}
+  if args.length > start_index
+    key = nil
+    args[start_index .. args.length - 1].each do |arg|
+      if key
+        result[key.to_sym] = arg
+        key = nil
+      else
+        key = arg
+      end
+    end
+  end
+  result
+end
+
+#note: don't forget to load (-r) your workflow. sample: ruby -r sample_wf  generic_persistent_workflow_manager.rb create "SampleWorkflow"
+
+mgr = Rbpm::FlockFileSystem::WorkflowPersistenceManager.new "ptoken.ind" #stores workflows in the current working directory!
+cmd = ARGV[0].to_sym
+
+case cmd
+when :create
+  workflow_name = ARGV[1]
+  token_vars = args_to_hash ARGV, 2
+  token = mgr.create_and_start(workflow_name, token_vars)
+  puts token.ref
+  exit(token.end? ? 0 : token.ref)
+when :signal
+  token_ref = ARGV[1].to_i
+  token_vars = args_to_hash ARGV, 2
+  token = mgr.signal(token_ref, token_vars)
+  exit(token.end? ? 0 : token.ref)
+when :print
+  token_ref = ARGV[1].to_i
+  ctx_var = ARGV[2].to_sym
+  token = mgr.freezed_token(token_ref)
+  puts token[ctx_var]
+end

data/lib/rbpm/token.rb

@@ -0,0 +1,169 @@
+#---------------------------------------------------------------------------------------------------------------------------------
+#
+# 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
+  
+  #tokens traverse a directed graph composed of nodes and transitions. they cause execution
+  #of event actions upon arrival in a node, before leaving a node or while moving from one
+  #node to another by taking a transition. tokens can create child tokens and a token
+  #can be associated with 0..1 parent- and 0..1 child- process instances. if a token does not
+  #have a parent token then it is the process instance's root token. in general, a token never
+  #waits in a node but immediately leaves the node after arrival. there are three exceptions:
+  #a token can create sub tokens which leave the node immediately (instead of the parent token). 
+  #a token can wait in a state node (wait being signaled manually). and last but 
+  #not least a node can defer execution to the root node of a newly created
+  #sub process and wait in a call node until the sub process has been finished. you can
+  #store :named variables in the token context. token variables can be involved in transition
+  #condition expression and can be get or set by event actions. if a token waits in a state
+  #the token variables can be manipulated by the workflow caller as well. but note that
+  #child tokens - and token variables - are destroyed upon arrival in a join node and
+  #that the root token is destroyed after the workflow has been finished.
+  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 find_root_token
+      return parent.nil? ? self : parent.find_root_token
+    end
+    
+    def find_super_token
+      return find_root_token.parent_process.nil? ? find_root_token : find_root_token.parent_process.find_super_token
+    end
+    
+    def find_token(token_ref)
+      if @ref == token_ref
+        return self
+      elsif sub_process
+        return sub_process.find_token(token_ref)
+      else
+        return nil
+      end
+    end
+    
+    def all_tokens(&blk)
+      blk.call(self)
+      if sub_process
+        sub_process.all_tokens(&blk)
+      end
+    end
+
+    def all_ctx_vars
+      @ctx_vars
+    end
+  
+    #transition condition expressions are evaluated using token's binding()
+    #and this method is here to support expressions like "token[:var_name] == ..."
+    def token 
+      self
+    end
+  
+    #set a token variable
+    def []=(key, value)
+      @ctx_vars[key] = value
+    end
+  
+    #get a token variable
+    def [](key)
+      @ctx_vars[key]
+    end
+  
+    def add_child(token)
+      @childs << token
+    end
+  
+    def remove_child(token)
+      @childs.delete(token)
+    end
+  
+    #is this the parent of children tokens?
+    def childs?
+      not @childs.empty?
+    end
+  
+    #sends a signal to a node waiting in a state.
+    #never call this method manually if the node
+    #does not wait in a state but does wait in
+    #a call node, because the node will be signalled
+    #automatically after the sub process instance
+    #has been finished.
+    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
+end