ruote 2.3.0.1 → 2.3.0.2

data/CHANGELOG.txt

@@ -2,6 +2,29 @@
 = ruote - CHANGELOG.txt
 
 
+== ruote - 2.3.1    not yet released
+
+
+== ruote - 2.3.0.2    not yet released
+
+- pin ruote.gemspec to ruby_parser ~>2.3 and parslet 1.4.0
+- add Ruote.[de]camelize
+- expose 'history_max_size' config option
+- Dashboard#get_trackers
+- Dashboard#remove_tracker(fei_sid_or_id, wfid)
+- :await attribute
+- let Ruote.deep_mutate mutate matching keys and their collection values
+- stop tripping on empty tags ("")
+- jump to 'x' where x in "participant 'x'" unlocked (thanks Tobias Neubert)
+- unlock on_error more (on_error: "retry * 3, pass" for example)
+- revise "$x" (literal dollars), now return nil instead of "$x" when missing
+- _auto_remove (and _alter) for trackers (pause on apply++)
+- pause on apply concept brought in
+- Dashboard#add_tracker
+- Dashboard#attach(fei, pdef)
+- participant#on_error
+
+
 == ruote - 2.3.0.1    released 2012/09/08
 
 - pin ruote.gemspec to blankslate 2.1.2.4

data/CREDITS.txt

@@ -13,6 +13,8 @@ Kenneth Kalmer - http://www.opensourcery.co.za
 
 == Contributors
 
+Mario Camou - lots of help
+Peter Brindisi - https://gitbhub.com/npj
 Gvozden Neskovic - https://github.com/ladenBrain
 Hartog C. de Mik - https://github.com/coffeeaddict
 Doug Bryant - re_dispatch bug and 'dispatched' << 'workitem'
@@ -54,6 +56,8 @@ Richard Jennings
 
 == Feedback
 
+Larry Marburger - await attribute clarifications
+Tobias Neubert - jump to participant 'x'
 tsdeng - https://github.com/tsdeng
 Klaus Schmidtmamn - sub_wf_name inspiration
 chaofan - https://github.com/chaofoan

data/LICENSE.txt

@@ -1,5 +1,5 @@
 
-Copyright (c) 2001-2012, John Mettraux, jmettraux@gmail.com
+Copyright (c) 2001-2013, 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

data/lib/ruote.rb

@@ -1,4 +1,6 @@
 
+require 'ruby_parser'
+
 require 'ruote/util/deep'
 require 'ruote/util/lookup'
 require 'ruote/util/mpatch'

data/lib/ruote/context.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2012, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2013, 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
@@ -240,6 +240,7 @@ module Ruote
 
       default_conf.merge(conf).each do |key, value|
 
+        key = key.to_s
         add_service(key, *value) if SERVICE_PREFIX.match(key)
       end
     end

data/lib/ruote/dashboard.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2012, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2013, 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
@@ -25,6 +25,7 @@
 require 'ruote/context'
 require 'ruote/util/ometa'
 require 'ruote/receiver/base'
+require 'ruote/dboard/mutation'
 require 'ruote/dboard/process_status'
 
 
@@ -178,6 +179,48 @@ module Ruote
       wfid
     end
 
+    # Given a flow expression id, locates the corresponding ruote
+    # expression and attaches a subprocess to it.
+    #
+    # Accepts the fei as a Hash or as a FlowExpressionId instance.
+    #
+    # By default, the workitem of the expression you attach to provides
+    # the initial workitem for the attached branch. By using the
+    # :fields/:workitem or :merge_fields options, one can change that.
+    #
+    # Returns the fei of the attached [root] expression
+    # (as a FlowExpressionId instance).
+    #
+    def attach(fei_or_fe, definition, opts={})
+
+      fe = Ruote.extract_fexp(@context, fei_or_fe).h
+      fei = fe['fei']
+
+      cfei = fei.merge(
+        'expid' => "#{fei['expid']}_0",
+        'subid' => Ruote.generate_subid(fei.inspect))
+
+      tree = @context.reader.read(definition)
+      tree[0] = 'sequence'
+
+      fields = fe['applied_workitem']['fields']
+      if fs = opts[:fields] || opts[:workitem]
+        fields = fs
+      elsif fs = opts[:merge_fields]
+        fields.merge!(fs)
+      end
+
+      @context.storage.put_msg(
+        'launch', # "apply" is OK, but "launch" stands out better
+        'parent_id' => fei,
+        'fei' => cfei,
+        'tree' => tree,
+        'workitem' => { 'fields' => fields },
+        'attached' => true)
+
+      Ruote::FlowExpressionId.new(cfei)
+    end
+
     # Given a workitem or a fei, will do a cancel_expression,
     # else it's a wfid and it does a cancel_process.
     #
@@ -325,6 +368,11 @@ module Ruote
     #   dashboard.re_apply(
     #     fei, :fields => { 'customer' => 'bob' })
     #
+    # :workitem is ok too
+    #
+    #   dashboard.re_apply(
+    #     fei, :workitem => { 'fields' => { 'customer' => 'bob' } })
+    #
     # :merge_in_fields is used to add / override fields
     #
     #   dashboard.re_apply(
@@ -338,6 +386,28 @@ module Ruote
         're_apply' => Ruote.keys_to_s(opts))
     end
 
+    # Returns a Mutation instance listing all the operations necessary
+    # to transform the current tree of the process (wfid) into
+    # the given definition tree (pdef).
+    #
+    # See also #apply_mutation
+    #
+    def compute_mutation(wfid, pdef)
+
+      Mutation.new(self, wfid, @context.reader.read(pdef))
+    end
+
+    # Computes mutation and immediately applies it...
+    #
+    # See #compute_mutation
+    #
+    # Return the mutation instance (forensic?)
+    #
+    def apply_mutation(wfid, pdef)
+
+      Mutation.new(self, wfid, @context.reader.read(pdef)).apply
+    end
+
     # This method re_apply all the leaves of a process instance. It's meant
     # to be used against stalled workflows to give them back the spark of
     # life.
@@ -676,11 +746,11 @@ module Ruote
     #     def initialize(opts)
     #       @name = opts['name']
     #     end
-    #     def consume(workitem)
+    #     def on_workitem
     #       workitem.fields['rocket_name'] = @name
     #       send_to_the_moon(workitem)
     #     end
-    #     def cancel(fei, flavour)
+    #     def on_cancel
     #       # do nothing
     #     end
     #   end
@@ -693,11 +763,14 @@ module Ruote
     #   class TotalParticipant
     #     include Ruote::LocalParticipant
     #
-    #     def consume(workitem)
+    #     def on_workitem
     #       workitem['total'] = workitem.fields['items'].inject(0.0) { |t, item|
     #         t + item['count'] * PricingService.lookup(item['id'])
     #       }
-    #       reply_to_engine(workitem)
+    #       reply
+    #     end
+    #
+    #     def on_cancel
     #     end
     #   end
     #   dashboard.register_participant 'total', TotalParticipant
@@ -1077,15 +1150,72 @@ module Ruote
     #
     def on_terminate=(target)
 
+      msg = {
+        'action' => 'launch',
+        'tree' => target.is_a?(String) ?
+          [ 'define', {}, [ [ target, {}, [] ] ] ] : target,
+        'workitem' => 'replace' }
+
       @context.tracker.add_tracker(
-        nil, # do not track a specific wfid
-        'terminated', # react on 'error_intercepted' msgs
-        'on_terminate', # the identifier
-        nil, # no specific condition
-        { 'action' => 'launch',
-          'tree' => target.is_a?(String) ?
-            [ 'define', {}, [ [ target, {}, [] ] ] ] : target,
-          'workitem' => 'replace' })
+        nil,             # do not track a specific wfid
+        'terminated',    # react on 'error_intercepted' msgs
+        'on_terminate',  # the identifier
+        nil,             # no specific condition
+        msg)             # the message that gets triggered
+    end
+
+    # /!\ warning: advanced method.
+    #
+    # Adds a tracker to the ruote engine.
+    #
+    # === Arguments
+    #
+    # * wfid:
+    #   When nil will track any workflow execution, when set will only
+    #   react on msgs for the given wfid.
+    # * action:
+    #   A string like "apply", "reply" or "receive", the action being tracked
+    #   May begin with a "pre_" prefix.
+    # * tracker_id:
+    #   When nil, ruote chooses a tracker_id, else its the unique identifier
+    #   for the new tracker.
+    # * conditions:
+    #   A Hash of keys pointing to arrays of expected values.
+    #   For example { 'tree.0' ~=> [ 'alfred', 'knuth' ] } will trigger
+    #   if the first element of msg['tree'] equals alfred or knuth.
+    # * msg:
+    #   The msg to place in the msg queue if the tracker matches the msg,
+    #   the reaction.
+    #
+    # Returns the tracker_id.
+    #
+    def add_tracker(wfid, action, tracker_id, conditions, msg)
+
+      @context.tracker.add_tracker(wfid, action, tracker_id, conditions, msg)
+    end
+
+    # /!\ warning: advanced method.
+    #
+    # Removes a tracker from the ruote system.
+    #
+    # The first arg is a FlowExpressionId, in its instance form, hash form or
+    # shortened (sid) string form. It can also be any string (any tracker id).
+    #
+    # The second arg is optional, it's a wfid. It's useful for some storage
+    # implementations (like ruote-swf) and helps determine how to grab
+    # the tracker list. Most of the ruote deployments don't need that arg set.
+    #
+    def remove_tracker(fei_sid_or_id, wfid=nil)
+
+      @context.tracker.remove_tracker(fei_sid_or_id, wfid)
+    end
+
+    # Returns a hash { tracker_id => tracker_hash } enumerating all
+    # the trackers in the ruote system.
+    #
+    def get_trackers(wfid=nil)
+
+      @context.storage.get_trackers(wfid)['trackers']
     end
 
     # A debug helper :
@@ -1100,6 +1230,32 @@ module Ruote
       @context.logger.noisy = b
     end
 
+    # Warning: advanced method.
+    #
+    # Currently only used by mutations.
+    #
+    def update_expression(fei, opts)
+
+      fei = Ruote.extract_fei(fei)
+      fexp = Ruote::Exp::FlowExpression::fetch(@context, fei)
+
+      raise ArgumentError.new(
+        "no expression found with fei #{fei.sid}"
+      ) unless fexp
+
+      if t = opts[:tree]
+        fexp.h.updated_tree = opts[:tree]
+      end
+
+      r = @context.storage.put(fexp.h)
+
+      raise ArgumentError.new(
+        "expression #{fei.sid} is gone"
+      ) if r == true
+
+      return update_expression(fei, opts) unless r.nil?
+    end
+
     protected
 
     # Used by #pause and #resume.

data/lib/ruote/dboard/mutation.rb

@@ -0,0 +1,282 @@
+#--
+# Copyright (c) 2005-2013, 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
+
+  #
+  # Gathers info about a possible mutation. The point of application (fei),
+  # the new tree (tree) and if it's a re_apply or an update (only changing
+  # the tree of the expression behind (fei)).
+  #
+  class MutationPoint
+
+    attr_reader :fei
+    attr_reader :tree
+    attr_reader :type # :re_apply or :update
+
+    def initialize(fei, tree, type)
+
+      @fei = fei
+      @tree = tree
+      @type = type
+    end
+
+    def to_s
+
+      s = []
+      s << self.class.name
+      s << "  at:      #{@fei.sid} (#{@fei.expid})"
+      s << "  action:  #{@type.inspect}"
+      s << "  tree:"
+
+      s.concat(
+        Ruote::Reader.to_radial(@tree).split("\n").map { |l| "    | #{l}" })
+
+      s.join("\n")
+    end
+
+    def apply(dboard, option=nil)
+
+      option ||= @type
+      option = option.to_sym
+
+      return if option != :force_update && option != @type
+
+      type = option == :force_update ? :update : @type
+
+      if type == :re_apply
+        dboard.re_apply(@fei, :tree => @tree)
+      else
+        dboard.update_expression(@fei, :tree => @tree)
+      end
+    end
+  end
+
+  #
+  # A set of mutation points.
+  #
+  # Initialized by Ruote::Dashboard#compute_mutation
+  #
+  class Mutation
+
+    # ProcessStatus instance (advanced stuff).
+    #
+    attr_reader :ps
+
+    attr_reader :points
+
+    def initialize(dboard, wfid, tree)
+
+      @dboard = dboard
+      @points = []
+      @ps = @dboard.ps(wfid)
+
+      walk(@ps.root_expression, Ruote.compact_tree(tree))
+
+      @points = @points.sort_by { |point| point.fei.expid }
+    end
+
+    def to_a
+
+      @points.collect { |pt|
+        { 'fei' => pt.fei, 'action' => pt.type, 'tree' => pt.tree }
+      }
+    end
+
+    def to_s
+
+      @points.collect(&:to_s).join("\n")
+    end
+
+    # Applies the mutation, :update points first then :re_apply points.
+    #
+    # Accepts an option, nil means apply all, :update means apply only
+    # update mutations points, :re_apply means apply on re_apply points,
+    # :force_update means apply all but turn re_apply points into update
+    # points.
+    #
+    def apply(option=nil)
+
+      updates, re_applies = @points.partition { |pt| pt.type == :update }
+      points = updates + re_applies
+
+      points.each { |pt| pt.apply(@dboard, option) }
+
+      self
+    end
+
+    protected
+
+    def register(point)
+
+      pt = @points.find { |p| p.fei == point.fei }
+
+      if pt && point.type == :re_apply
+        @points.delete(pt)
+        @points << point
+      else
+        @points << point
+      end
+    end
+
+    # Look for mutation points in an expression and its children.
+    #
+    def walk(fexp, tree)
+
+      ftree = Ruote.compact_tree(@ps.current_tree(fexp))
+
+      if ftree[0] != tree[0] || ftree[1] != tree[1]
+        #
+        # if there is anything different between the current tree and the
+        # desired tree, let's force a re-apply
+
+        register(MutationPoint.new(fexp.fei, tree, :re_apply))
+
+      elsif ftree[2] == tree[2]
+        #
+        # else, if the tree children are the same, exit, there is nothing to do
+
+        return
+
+      else
+
+        register(MutationPoint.new(fexp.fei, tree, :update))
+          #
+          # NOTE: maybe a switch for this mutation not to be added would
+          #       be necessary...
+
+        if fexp.is_concurrent?
+          #
+          # concurrent expressions follow a different heuristic
+
+          walk_concurrence(fexp, ftree, tree)
+
+        else
+          #
+          # all other expressions are considered sequence-like
+
+          walk_sequence(fexp, ftree, tree)
+        end
+      end
+    end
+
+    # Look for mutation points in a concurrent expression (concurrence or
+    # concurrent-iterator).
+    #
+    def walk_concurrence(fexp, ftree, tree)
+
+      if ftree[2].size != tree[2].size
+        #
+        # that's lazy, but why not?
+        #
+        # we could add/apply a new child...
+
+        register(MutationPoint.new(fexp.fei, tree, :re_apply))
+
+      else
+        #
+        # if there is a least one child that replied and whose
+        # tree must be changes, then re-apply the whole concurrence
+        #
+        # else try to re-apply only the necessary branch (walk them)
+
+        branches = ftree[2].zip(tree[2]).each_with_object([]) { |(ft, t), a|
+          #
+          # match child expressions (if not yet replied) with current tree (ft)
+          # and desired tree (t)
+          #
+          cfei = fexp.children[a.size]
+          cexp = cfei ? @ps.fexp(cfei) : nil
+          a << [ cexp, ft, t ]
+          #
+        }.select { |cexp, ft, t|
+          #
+          # only keep diverging branches
+          #
+          ft != t
+        }
+
+        branches.each do |cexp, ft, t|
+
+          next if cexp
+
+          # there is at least one branch that replied,
+          # this forces re-apply for the whole concurrence
+
+          register(MutationPoint.new(fexp.fei, tree, :re_apply))
+          return
+        end
+
+        branches.each do |cexp, ft, t|
+          #
+          # we're left with divering branches that haven't yet replied,
+          # let's walk to register the mutation point deep into it
+
+          walk(cexp, t)
+        end
+      end
+    end
+
+    # Look for mutation points in any non-concurrent expression.
+    #
+    def walk_sequence(fexp, ftree, tree)
+
+      i = fexp.child_ids.first
+
+      ehead = ftree[2].take(i)
+      ecurrent = ftree[2][i]
+      etail = ftree[2].drop(i + 1)
+      head = tree[2].take(i)
+      current = tree[2][i]
+      tail = tree[2].drop(i + 1)
+
+      if ehead != head
+        #
+        # if the name and/or attributes of the exp are supposed to change
+        # then we have to reapply it
+        #
+        register(MutationPoint.new(fexp.fei, tree, :re_apply))
+        return
+      end
+
+      if ecurrent != current
+        #
+        # if the child currently applied is supposed to change, let's walk
+        # it down
+        #
+        walk(@ps.fexp(fexp.children.first), current)
+      end
+
+      #if etail != tail
+      #  #
+      #  # if elements are added at the end of the sequence, let's register
+      #  # a mutation that simply changes the tree (no need to re-apply)
+      #  #
+      #  register(MutationPoint.new(fexp.fei, tree, :update))
+      #end
+    end
+  end
+end
+