ruote 2.1.9 → 2.1.10

data/lib/ruote/engine/process_error.rb

@@ -69,6 +69,19 @@ module Ruote
       @h
     end
 
+    # 'apply', 'reply', 'receive', ... Indicates in which "direction" the
+    # error occured.
+    #
+    def action
+      @h['msg']['action']
+    end
+
+    # Exposes the workitem fields directly.
+    #
+    def fields
+      @h['msg']['workitem']['fields']
+    end
+
     protected
 
     def to_dot (opts)

data/lib/ruote/engine/process_status.rb

@@ -58,7 +58,39 @@ module Ruote
     #
     def root_expression
 
-      @expressions.find { |e| e.fei.expid == '0' && e.fei.sub_wfid == nil }
+      #@expressions.find { |e| e.fei.expid == '0' && e.fei.sub_wfid == nil }
+        # vanilla implementation
+
+      root_expressions.first
+    end
+
+    # Returns a list of all the expressions that have no parent expression.
+    # The list is sorted with the deeper (closer to the original root) first.
+    #
+    def root_expressions
+
+      roots = @expressions.select { |e| e.h.parent_id == nil }
+
+      roots = roots.inject({}) { |h, e|
+        h["#{e.h.fei['expid']}__#{e.h.fei['sub_wfid']}"] = e; h
+      }
+
+      roots.keys.sort.collect { |k| roots[k] }
+    end
+
+    # Given an expression id, returns the root (top ancestor) for its
+    # expression.
+    #
+    def root_expression_for (fei)
+
+      sfei = Ruote.sid(fei)
+
+      exp = @expressions.find { |fe| sfei == Ruote.sid(fe.fei) }
+
+      return nil unless exp
+      return exp if exp.parent_id.nil?
+
+      root_expression_for(exp.parent_id)
     end
 
     # Returns the process variables set for this process instance.

data/lib/ruote/error_handler.rb

@@ -0,0 +1,122 @@
+#--
+# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Japan.
+#++
+
+
+module Ruote
+
+  #
+  # A ruote service for turning exceptions into process errors (or letting
+  # those error fire any potential :on_error attributes in the process
+  # definition).
+  #
+  # This service is used, by the worker, the dispatch pool and some
+  # receivers (like the one in ruote-beanstalk).
+  #
+  class ErrorHandler
+
+    def initialize (context)
+
+      @context = context
+    end
+
+    # As used by the dispatch pool and the worker.
+    #
+    def msg_handle (msg, exception)
+
+      fexp = Ruote::Exp::FlowExpression.fetch(
+        @context, msg['fei'] || msg['workitem']['fei'])
+
+      handle(msg, fexp, exception)
+    end
+
+    # As used by some receivers (see ruote-beanstalk's receiver).
+    #
+    def action_handle (action, fei, exception)
+
+      fexp = Ruote::Exp::FlowExpression.fetch(@context, fei)
+
+      msg = {
+        'action' => action,
+        'fei' => fei,
+        'participant_name' => fexp.h.participant_name,
+        'workitem' => fexp.h.applied_workitem }
+
+      handle(msg, fexp, exception)
+    end
+
+    protected
+
+    # As used by the worker.
+    #
+    def handle (msg, fexp, exception)
+
+      wfid = msg['wfid'] || (msg['fei']['wfid'] rescue nil)
+      fei = msg['fei'] || (fexp.h.fei rescue nil)
+
+      backtrace = exception.backtrace || []
+
+      # debug only
+
+      if $DEBUG || ARGV.include?('-d')
+
+        puts "\n== worker intercepted error =="
+        puts
+        p exception
+        puts backtrace[0, 20].join("\n")
+        puts "..."
+        puts
+        puts "-- msg --"
+        msg.keys.sort.each { |k|
+          puts "    #{k.inspect} =>\n#{msg[k].inspect}"
+        }
+        puts "-- . --"
+        puts
+      end
+
+      # on_error ?
+
+      return if fexp && fexp.handle_on_error(msg, exception)
+
+      # emit 'msg'
+
+      @context.storage.put_msg(
+        'error_intercepted',
+        'message' => exception.inspect,
+        'wfid' => wfid,
+        'msg' => msg)
+
+      # fill error in the error journal
+
+      @context.storage.put(
+        'type' => 'errors',
+        '_id' => "err_#{Ruote.to_storage_id(fei)}",
+        'message' => exception.inspect,
+        'trace' => backtrace.join("\n"),
+        'fei' => fei,
+        'msg' => msg
+      ) if fei
+    end
+  end
+end
+

data/lib/ruote/evt/tracker.rb

@@ -25,6 +25,13 @@
 
 module Ruote
 
+  #
+  # The tracker service is used by the "listen" expression. This services
+  # sees all the msg processed by a worker and triggers any
+  # listener interested in a particular msg.
+  #
+  # Look at the ListenExpression for more details.
+  #
   class Tracker
 
     def initialize (context)
@@ -44,6 +51,9 @@ module Ruote
       end
     end
 
+    # The worker passes all the messages it has to process to the tracker via
+    # this method.
+    #
     def notify (msg)
 
       doc = @context.storage.get_trackers
@@ -67,16 +77,8 @@ module Ruote
       end
     end
 
-    def does_match? (msg, conditions)
-
-      conditions.each do |k, v|
-        val = msg[k]
-        return false unless val && val.match(v)
-      end
-
-      true
-    end
-
+    # Adds a tracker (usually when a 'listen' expression gets applied).
+    #
     def add_tracker (wfid, action, fei, conditions, msg, doc=nil)
 
       doc ||= @context.storage.get_trackers
@@ -94,6 +96,9 @@ module Ruote
         # the put failed, have to redo the work
     end
 
+    # Removes a tracker (usually when a 'listen' expression replies to its
+    # parent expression or is cancelled).
+    #
     def remove_tracker (fei, doc=nil)
 
       doc ||= @context.storage.get_trackers
@@ -105,6 +110,18 @@ module Ruote
       remove_tracker(fei, r) if r
         # the put failed, have to redo the work
     end
+
+    protected
+
+    def does_match? (msg, conditions)
+
+      conditions.each do |k, v|
+        val = msg[k]
+        return false unless val && val.match(v)
+      end
+
+      true
+    end
   end
 end
 

data/lib/ruote/exp/fe_apply.rb

@@ -55,6 +55,73 @@ module Ruote::Exp
   #   echo 'nada'
   #
   #
+  # == apply and subprocesses
+  #
+  # There is an interesting way of using 'apply', it's close to the way of
+  # the Ruby "yield" expression.
+  #
+  #   pdef = Ruote.process_definition 'test' do
+  #     sequence do
+  #       handle do
+  #         participant 'alpha'
+  #       end
+  #       handle do
+  #         participant 'bravo'
+  #       end
+  #     end
+  #     define 'handle' do
+  #       sequence do
+  #         participant 'prepare_data'
+  #         apply
+  #         participant 'rearrange_data'
+  #       end
+  #     end
+  #   end
+  #
+  # With this process definition, the particpant alpha and bravo are handed
+  # a workitem in sequence, but each time, the data gets prepared and
+  # re-arranged.
+  #
+  # 'apply' simply picks the value of the tree to apply in the local variable
+  # 'tree'.
+  #
+  # Passing variables to applied trees is possible :
+  #
+  #   pdef = Ruote.process_definition do
+  #     handle do
+  #       participant '${v:target}', :message => 'x'
+  #     end
+  #     define 'handle' do
+  #       sequence do
+  #         participant 'prepare_data'
+  #         apply :v => 'alpha'
+  #         apply :v => 'bravo'
+  #         participant 'rearrange_data'
+  #       end
+  #     end
+  #   end
+  #
+  #
+  # == on_error
+  #
+  # It's OK, to place an on_error on the apply
+  #
+  #   pdef = Ruote.process_definition do
+  #     handle do
+  #       sequence do
+  #         echo 'in'
+  #         nemo
+  #       end
+  #     end
+  #     define 'handle' do
+  #       apply :on_error => 'notify' # <==
+  #       echo 'over.'
+  #     end
+  #     define 'notify' do
+  #       echo 'error'
+  #     end
+  #   end
+  #
   class ApplyExpression < FlowExpression
 
     names :apply
@@ -62,6 +129,8 @@ module Ruote::Exp
     # TODO : maybe accept directly ruby and xml (and json)
     # TODO : _yield ?
 
+    # TODO : apply [ 'echo', { 'nada' => nil }, [] ]
+
     def apply
 
       #

data/lib/ruote/exp/fe_participant.rb

@@ -23,7 +23,6 @@
 #++
 
 
-require 'ruote/workitem'
 require 'ruote/exp/condition'
 
 
@@ -120,6 +119,10 @@ module Ruote::Exp
 
     names :participant
 
+    # Should return true when the dispatch was successful.
+    #
+    h_reader :dispatched
+
     def apply
 
       #
@@ -157,17 +160,18 @@ module Ruote::Exp
         'fei' => h.fei,
         'participant_name' => h.participant_name,
         'workitem' => h.applied_workitem,
-        'for_engine_worker?' => participant_info.class != Array)
-          #
-          # NOTE : is this for_engine_worker? still necessary ?
+        'for_engine_worker?' => (participant_info.class != Array))
     end
 
     def cancel (flavour)
 
+      return reply_to_parent(h.applied_workitem) unless h.participant_name
+        # no participant, reply immediately
+
       do_persist || return
         #
         # if do_persist returns false, it means we're operating on stale
-        # data and have thus to cease
+        # data and cannot continue
 
       @context.storage.put_msg(
         'dispatch_cancel',
@@ -177,6 +181,16 @@ module Ruote::Exp
         'workitem' => h.applied_workitem)
     end
 
+    def reply (workitem)
+
+      pa = @context.plist.lookup(
+        workitem['participant_name'], :on_reply => true)
+
+      pa.on_reply(Ruote::Workitem.new(workitem)) if pa
+
+      super(workitem)
+    end
+
     def reply_to_parent (workitem)
 
       workitem['fields'].delete('params')
@@ -186,6 +200,20 @@ module Ruote::Exp
 
     protected
 
+    # Once the dispatching work (done by the dispatch pool) is done, a
+    # 'dispatched' msg is sent, we have to flag the participant expression
+    # as 'dispatched' => true
+    #
+    # See http://groups.google.com/group/openwferu-users/browse_thread/thread/ff29f26d6b5fd135
+    # for the motivation.
+    #
+    def do_dispatched (msg)
+
+      h.dispatched = true
+      do_persist
+        # let's not care if it fails...
+    end
+
     # Overriden with an empty behaviour. The work is now done a bit later
     # via the #schedule_timeout method.
     #

data/lib/ruote/exp/flowexpression.rb

@@ -31,7 +31,27 @@ require 'ruote/util/hashdot'
 module Ruote::Exp
 
   #
-  # TODO : document me
+  # Ruote is a process definition interpreter. It doesn't directly "read"
+  # process definitions, it relies on a parser/generator to produce "abstract
+  # syntax trees" that look like
+  #
+  #   [ expression_name, { ... attributes ... }, [ children_expressions ] ]
+  #
+  # The nodes (and leaves) in the trees are expressions. This is the base
+  # class for all expressions.
+  #
+  # The most visible expressions are "define", "sequence" and "participant".
+  # Think :
+  #
+  #   pdef = Ruote.process_definition do
+  #     sequence do
+  #       participant :ref => 'customer'
+  #       participant :ref => 'accounting'
+  #       participant :ref => 'logistics'
+  #     end
+  #   end
+  #
+  # Each node is an expression...
   #
   class FlowExpression
 
@@ -390,9 +410,14 @@ module Ruote::Exp
     def do_fail (msg)
 
       @h['state'] = 'failing'
-      persist_or_raise
+      @h['applied_workitem'] = msg['workitem']
 
-      h.children.each { |i| @context.storage.put_msg('cancel', 'fei' => i) }
+      if h.children.size < 1
+        reply_to_parent(@h['applied_workitem'])
+      else
+        persist_or_raise
+        h.children.each { |i| @context.storage.put_msg('cancel', 'fei' => i) }
+      end
     end
 
     #--
@@ -449,6 +474,7 @@ module Ruote::Exp
       elsif h.parent_id
 
         par = parent
+          # :( get_parent would probably be a better name for #parent
 
         unless par
           puts "~~"
@@ -469,7 +495,7 @@ module Ruote::Exp
 
     # Looks up parent with on_error attribute and triggers it
     #
-    def handle_on_error
+    def handle_on_error (msg, error)
 
       return false if h.state == 'failing'
 
@@ -483,10 +509,15 @@ module Ruote::Exp
       return false if handler == ''
         # empty on_error handler nullifies ancestor's on_error
 
+      workitem = msg['workitem']
+
+      workitem['fields']['__error__'] = [
+        h.fei, Ruote.now_to_utc_s, error.class.to_s, error.message ]
+
       @context.storage.put_msg(
         'fail',
         'fei' => oe_parent.h.fei,
-        'error_fei' => h.fei)
+        'workitem' => workitem)
 
       true # yes, error is being handled.
     end
@@ -685,6 +716,7 @@ module Ruote::Exp
     def trigger (on, workitem)
 
       hon = h[on]
+
       t = hon.is_a?(String) ? [ hon, {}, [] ] : hon
 
       if on == 'on_error'