ruote-maestrodev 2.2.1

data/lib/ruote/exp/fe_concurrent_iterator.rb

@@ -0,0 +1,219 @@
+#--
+# Copyright (c) 2005-2011, 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.
+#++
+
+
+require 'ruote/exp/fe_concurrence'
+require 'ruote/exp/iterator'
+
+
+module Ruote::Exp
+
+  #
+  # This expression is a cross between 'concurrence' and 'iterator'.
+  #
+  # Please look at the documentation of 'iterator' to learn more about the
+  # common options between 'iterator' and 'concurrent-iterator'.
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     concurrent_iterator :on_val => 'alice, bob, charly', :to_var => 'v' do
+  #       participant '${v:v}'
+  #     end
+  #   end
+  #
+  # will be equivalent to
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     concurrence do
+  #       participant 'alice'
+  #       participant 'bob'
+  #       participant 'charly'
+  #     end
+  #   end
+  #
+  # The 'on' and the 'to' attributes follow exactly the ones for the iterator
+  # expression.
+  #
+  # When there is no 'to', the current iterated value is placed in the variable
+  # named 'i'.
+  #
+  # The variable named 'ii' contains the current iterated index (an int bigger
+  # or egal to 0).
+  #
+  # 'concurrent_iterator' does not understand commands like
+  # rewind/break/jump/... like 'iterator' does, since it fires all its
+  # branches when applied.
+  #
+  # == :times and :branches
+  #
+  # Similarly to the iterator expression, the :times or the :branches attribute
+  # may be used in stead of the 'on' attribute.
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     concurrent_iterator :times => 3 do
+  #       participant 'user${v:i}'
+  #     end
+  #   end
+  #
+  # is equivalent to
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     concurrence do
+  #       participant 'user0'
+  #       participant 'user1'
+  #       participant 'user2'
+  #     end
+  #   end
+  #
+  #
+  # == options
+  #
+  # the concurrent_iterator accepts the same options for merging as its bigger
+  # brother, the concurrence expression.
+  #
+  # :count, :merge (override, mix, isolate), remaining (cancel, forget) and
+  # :over.
+  #
+  #
+  # == add branches
+  #
+  # The 'add_branches'/'add_branch' expression can be used to add branches
+  # to a concurrent-iterator while it is running.
+  #
+  #   concurrent_iterator :on => 'a, b, c' do
+  #     sequence do
+  #       participant :ref => 'worker_${v:i}'
+  #       add_branches 'd, e', :if => '${v:/not_sufficient}'
+  #     end
+  #   end
+  #
+  # In this example, if the process level variable 'not_sufficient' is set to
+  # true, workers d and e will be added to the iterated elements.
+  #
+  # Read more at the 'add_branches' expression description.
+  #
+  #
+  # == 'citerator'
+  #
+  # 'citerator' is an alias for 'concurrent_iterator'.
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     citerator :on_val => 'alice, bob, charly', :to_var => 'v' do
+  #       participant '${v:v}'
+  #     end
+  #   end
+  #
+  class ConcurrentIteratorExpression < ConcurrenceExpression
+
+    include IteratorMixin
+
+    names :concurrent_iterator, :citerator
+
+    ADD_BRANCHES_FIELD = '__add_branches__'
+
+    # Overrides FlowExpression#register_child to make sure that persist is
+    # not called.
+    #
+    def register_child(fei)
+
+      h.children << fei
+    end
+
+    def add_branches(list)
+
+      if h.times_iterator && list.size == 1
+
+        count = (list.first.to_i rescue nil)
+
+        list = (h.list_size + 1..h.list_size + count) if count
+      end
+
+      list.each do |val|
+
+        h.list_size += 1
+
+        workitem = Ruote.fulldup(h.applied_workitem)
+        #workitem = Rufus::Json.dup(h.applied_workitem)
+
+        variables = { 'ii' => h.list_size - 1 }
+
+        if h.to_v
+          variables[h.to_v] = val
+        else #if to_f
+          workitem['fields'][h.to_f] = val
+        end
+
+        launch_sub(
+          "#{h.fei['expid']}_0",
+          tree_children[0],
+          :workitem => workitem,
+          :variables => variables)
+      end
+    end
+
+    def reply(workitem)
+
+      if ab = workitem['fields'].delete(ADD_BRANCHES_FIELD)
+
+        add_branches(ab)
+
+        if h.fei['wfid'] != workitem['fei']['wfid'] ||
+           ( ! workitem['fei']['expid'].match(/^#{h.fei['expid']}_\d+$/))
+
+          do_persist
+          return
+        end
+      end
+
+      super(workitem)
+    end
+
+    protected
+
+    def apply_children
+
+      return reply_to_parent(h.applied_workitem) unless tree_children[0]
+
+      list = determine_list
+
+      return reply_to_parent(h.applied_workitem) if list.empty?
+
+      h.to_v, h.to_f = determine_tos
+      h.to_v = 'i' if h.to_v.nil? && h.to_f.nil?
+
+      h.list_size = 0
+
+      add_branches(list)
+
+      persist_or_raise
+    end
+
+    # Overrides the implementation found in ConcurrenceExpression
+    #
+    def expected_count
+
+      h.ccount ? [ h.ccount, h.list_size ].min : h.list_size
+    end
+  end
+end
+

data/lib/ruote/exp/fe_cron.rb

@@ -0,0 +1,141 @@
+#--
+# Copyright (c) 2005-2011, 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::Exp
+
+  #
+  # This expression executes its children expression according to a cron
+  # schedule or at a given frequency.
+  #
+  #   cron '15 4 * * sun' do # every sunday at 0415
+  #     subprocess :ref => 'refill_the_acid_baths'
+  #   end
+  #
+  # or
+  #
+  #   every '10m' do
+  #     send_reminder # subprocess or participant
+  #   end
+  #
+  # The 'tab' or 'interval' attributes may be used, this is a bit more verbose,
+  # but, for instance, in XML, it is quite necessary :
+  #
+  #   <cron tab="15 4 * * sun">
+  #     <subprocess ref="refill_the_acid_baths" />
+  #   <cron>
+  #
+  # Triggered children subprocesses are 'forgotten'. This implies they
+  # will never reply to the cron/every expression and they won't get cancelled
+  # when the cron/every expression gets cancelled (the cron/every schedule
+  # gets cancelled though, no new children will get cancelled).
+  #
+  # "man 5 crontab" in the command line of your favourite unix system might
+  # help you with the semantics of the string expected by the cron expression.
+  #
+  #
+  # == an example use case
+  #
+  # The cron/every expression appears often in scenarii like :
+  #
+  #   concurrence :count => 1 do
+  #
+  #     participant 'operator'
+  #
+  #     cron '0 9 * * 1-5' do # send a reminder every weekday at 0900
+  #       notify 'operator'
+  #     end
+  #   end
+  #
+  # With a subprocess, this could become a bit more reusable :
+  #
+  #   Ruote.process_defintion :name => 'sample' do
+  #
+  #     sequence do
+  #       with_reminder :participant => 'operator1'
+  #       with_reminder :participant => 'operator2'
+  #     end
+  #
+  #     define 'with_reminder' do
+  #       concurrence :count => 1 do
+  #         participant '${v:participant}'
+  #         cron '0 9 * * 1-5' do # send a reminder every weekday at 0900
+  #           notify '${v:participant}'
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  class CronExpression < FlowExpression
+
+    names :cron, :every
+
+    def apply
+
+      h.schedule = attribute(:tab) || attribute(:interval) || attribute_text
+      h.job_id = nil
+
+      reschedule
+    end
+
+    def reply(workitem)
+
+      launch_sub(
+        "#{h.fei['expid']}_0",
+        tree_children[0],
+        :workitem => Ruote.fulldup(h.applied_workitem),
+        :forget => true)
+
+      reschedule
+    end
+
+    def cancel(flavour)
+
+      @context.storage.delete_schedule(h.job_id)
+      reply_to_parent(h.applied_workitem)
+    end
+
+    # Note : this method has to be public.
+    #
+    def reschedule
+
+      h.job_id = @context.storage.put_schedule(
+        'cron',
+        h.fei,
+        h.schedule,
+        'action' => 'reply',
+        'fei' => h.fei,
+        'workitem' => h.applied_workitem)
+
+      @context.storage.delete_schedule(h.job_id) if try_persist
+        #
+        # if the persist failed, immediately unschedule
+        # the just scheduled job
+        #
+        # this is meant to cope with cases where one worker reschedules
+        # while another just cancelled
+    end
+  end
+end
+

data/lib/ruote/exp/fe_cursor.rb

@@ -0,0 +1,324 @@
+#--
+# Copyright (c) 2005-2011, 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.
+#++
+
+
+require 'ruote/exp/commanded'
+
+
+module Ruote::Exp
+
+  #
+  # This class implements the 'cursor' and the 'repeat' (loop) expressions.
+  #
+  # The cursor expression is a kind of enhanced 'sequence'. Like a sequence
+  # it will execute its child expression one by one, sequentially. Unlike a
+  # sequence though, it will obey 'commands'.
+  #
+  #   cursor do
+  #     author
+  #     reviewer
+  #     rewind :if => '${f:not_ok}'
+  #     publisher
+  #   end
+  #
+  # In this simplistic example, the process will flow from author to reviewer
+  # and back until the reviewer sets the workitem field 'not_ok' to something
+  # else than the value 'true'.
+  #
+  # There are two ways to pass commands to a cursor either directly from
+  # the process definition with a cursor command expression, either via
+  # the workitem '__command__' [special] field.
+  #
+  # == cursor commands
+  #
+  # The commands that a cursor understands are listed here. The most powerful
+  # ones are 'rewind' and 'jump'.
+  #
+  # === rewind
+  #
+  # Rewinds the cursor up to its first child expression.
+  #
+  #   cursor do
+  #     author
+  #     reviewer
+  #     rewind :if => '${f:not_ok}'
+  #     publisher
+  #   end
+  #
+  # === reset
+  #
+  # Whereas 'rewind' places the cursor back to the initial step with the current
+  # workitem, 'reset' will rewind it and start again but with the workitem
+  # as it was when it reached the cursor/repeat.
+  #
+  # === stop, over & break
+  #
+  # Exits the cursor.
+  #
+  #   cursor do
+  #     author
+  #     reviewer
+  #     rewind :if => '${f:review} == fix'
+  #     stop :if => '${f:review} == abort'
+  #     publisher
+  #   end
+  #
+  # '_break' or 'over' can be used instead of 'stop'.
+  #
+  # === skip & back
+  #
+  # Those two commands jump forth and back respectively. By default, they
+  # skip 1 child, but they accept a numeric parameter holding the number
+  # of children to skip.
+  #
+  #   cursor do
+  #     author
+  #     reviewer
+  #     rewind :if => '${f:review} == fix'
+  #     skip 2 :if => '${f:review} == publish'
+  #     reviewer2
+  #     rewind :if => '${f:review} == fix'
+  #     publisher
+  #   end
+  #
+  # === jump
+  #
+  # Jump is probably the most powerful of the cursor commands. It allows to
+  # jump to a specified expression that is a direct child of the cursor.
+  #
+  #   cursor do
+  #     author
+  #     reviewer
+  #     jump :to => 'author', :if => '${f:review} == fix'
+  #     jump :to => 'publisher', :if => '${f:review} == publish'
+  #     reviewer2
+  #     jump :to => 'author', :if => '${f:review} == fix'
+  #     publisher
+  #   end
+  #
+  # Note that the :to accepts the name of an expression or the value of
+  # its :ref attribute or the value of its :tag attribute.
+  #
+  #   cursor do
+  #     participant :ref => 'author'
+  #     participant :ref => 'reviewer'
+  #     jump :to => 'author', :if => '${f:review} == fix'
+  #     participant :ref => 'publisher'
+  #   end
+  #
+  # == cursor command with :ref
+  #
+  # It's OK to tag a cursor/repeat/loop with the :tag attribute and then
+  # point a command to it via :ref :
+  #
+  #   concurrence do
+  #
+  #     cursor :tag => 'main' do
+  #       author
+  #       editor
+  #       publisher
+  #     end
+  #
+  #     # meanwhile ...
+  #
+  #     sequence do
+  #       sponsor
+  #       rewind :ref => 'main', :if => '${f:stop}'
+  #     end
+  #   end
+  #
+  # This :ref technique may also be used with nested cursor/loop/iterator
+  # constructs :
+  #
+  #   cursor :tag => 'main' do
+  #     cursor do
+  #       author
+  #       editor
+  #       rewind :if => '${f:not_ok}'
+  #       _break :ref => 'main', :if => '${f:abort_everything}'
+  #     end
+  #     head_of_edition
+  #     rewind :if => '${f:not_ok}'
+  #     publisher
+  #   end
+  #
+  # this example features two nested cursors. There is a "_break" in the inner
+  # cursor, but it will break the main 'cursor' (and thus break the whole
+  # review process).
+  #
+  # == cursor command in the workitem
+  #
+  # The command expressions are merely setting the workitem field '__command__'
+  # with an array value [ {command}, {arg} ].
+  #
+  # For example,
+  #
+  #   jump :to => 'author'
+  #     # is equivalent to
+  #   set 'field:__command__' => 'author'
+  #
+  # It is entirely OK to have a participant implementation that sets __command__
+  # by itself.
+  #
+  #   class Reviewer
+  #     include Ruote::LocalParticipant
+  #
+  #     def consume(workitem)
+  #       # somehow review the book
+  #       if review == 'bad'
+  #         #workitem.fields['__command__'] = [ 'rewind' ] # old style
+  #         workitem.command = 'rewind' # new style
+  #       else
+  #         # let it go
+  #       end
+  #       reply_to_engine(workitem)
+  #     end
+  #
+  #     def cancel(fei, flavour)
+  #       # cancel if review is still going on...
+  #     end
+  #   end
+  #
+  # This example uses the Ruote::Workitem#command= method which can be fed
+  # strings like 'rewind', 'skip 2', 'jump to author' or the equivalent arrays
+  # [ 'rewind' ], [ 'skip', 2 ], [ 'jump', 'author' ].
+  #
+  #
+  # == :break_if / :rewind_if
+  #
+  # As an attribute of the cursor/repeat expression, you can set a :break_if.
+  # It tells the cursor (loop) if it has to break.
+  #
+  #   cursor :break_if => '${f:completed}' do
+  #     participant 'alpha'
+  #     participant 'bravo'
+  #     participant 'charly'
+  #   end
+  #
+  # If alpha or bravo replies and the field 'completed' is set to true, this
+  # cursor will break.
+  #
+  # :break_unless is accepted. :over_if and :over_unless are synonyms for
+  # :break_if and :break_unless respectively.
+  #
+  # :rewind_if / :rewind_unless behave the same, but the cursor/loop, instead
+  # of breaking, is put back in its first step.
+  #
+  #
+  # = repeat (loop)
+  #
+  # A 'cursor' expression exits implicitely as soon as its last child replies
+  # to it.
+  # a 'repeat' expression will apply (again) the first child after the last
+  # child replied. A 'break' cursor command might be necessary to exit the loop
+  # (or a cancel_process, but that exits the whole process instance).
+  #
+  #   sequence do
+  #     repeat do
+  #       author
+  #       reviewer
+  #       _break :if => '${f:review} == ok'
+  #     end
+  #     publisher
+  #   end
+  #
+  class CursorExpression < CommandedExpression
+
+    names :cursor, :loop, :repeat
+
+    def apply
+
+      move_on
+    end
+
+    protected
+
+    # Determines which child expression of the cursor is to be applied next.
+    #
+    def move_on(workitem=h.applied_workitem)
+
+      position = workitem['fei'] == h.fei ?
+        -1 : Ruote::FlowExpressionId.child_id(workitem['fei'])
+
+      position += 1
+
+      com, arg = get_command(workitem)
+
+      return reply_to_parent(workitem) if com == 'break'
+
+      case com
+        when 'rewind', 'continue', 'reset' then position = 0
+        when 'skip' then position += arg
+        when 'jump' then position = jump_to(workitem, position, arg)
+      end
+
+      position = 0 if position >= tree_children.size && is_loop?
+
+      if position < tree_children.size
+
+        workitem = h.applied_workitem if com == 'reset'
+        apply_child(position, workitem)
+
+      else
+
+        reply_to_parent(workitem)
+      end
+    end
+
+    # Will return true if this instance is about a 'loop' or a 'repeat'.
+    #
+    def is_loop?
+
+      name == 'loop' || name == 'repeat'
+    end
+
+    # Jumps to an integer position, or the name of an expression
+    # or a tag name of a ref name.
+    #
+    def jump_to(workitem, position, arg)
+
+      pos = Integer(arg) rescue nil
+
+      return pos if pos != nil
+
+      tree_children.each_with_index do |c, i|
+
+        exp_name = c[0]
+        ref = c[1]['ref']
+        tag = c[1]['tag']
+
+        ref = @context.dollar_sub.s(ref, self, workitem) if ref
+        tag = @context.dollar_sub.s(tag, self, workitem) if tag
+
+        next if exp_name != arg && ref != arg && tag != arg
+
+        pos = i
+        break
+      end
+
+      pos ? pos : position
+    end
+  end
+end
+