ruote-maestrodev 2.2.1

data/lib/ruote/exp/fe_apply.rb

@@ -0,0 +1,154 @@
+#--
+# 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
+
+  #
+  # The 'apply' expression is an advanced expression.
+  #
+  # It takes as input an AST and applies it. The AST may be placed in a field
+  # or a variable or passed directly to the apply.
+  #
+  # These apply examples :
+  #
+  #   apply :tree => [ 'echo', { 'nada' => nil }, [] ]
+  #
+  #   sequence do
+  #     set :var => 'tree', :val => [ 'echo', { 'nada' => nil }, [] ]
+  #     apply # looks by default in variable 'tree'
+  #   end
+  #
+  #   sequence do
+  #     set :var => 't', :val => [ 'echo', { 'nada' => nil }, [] ]
+  #     apply :tree_var => 't'
+  #   end
+  #
+  #   sequence do
+  #     set :field => 't', :val => [ 'echo', { 'nada' => nil }, [] ]
+  #     apply :tree_field => 't'
+  #   end
+  #
+  # All are equivalent to
+  #
+  #   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
+
+    # TODO : maybe accept directly ruby and xml (and json)
+    # TODO : _yield ?
+
+    # TODO : apply [ 'echo', { 'nada' => nil }, [] ]
+
+    def apply
+
+      #
+      # find 'tree'
+
+      tree =
+        lookup_val_prefix('tree', :escape => true) ||
+        lookup_variable('tree')
+
+      return reply_to_parent(h.applied_workitem) unless tree
+
+      #
+      # apply 'tree'
+
+      launch_sub(
+        "#{h.fei['expid']}_0", tree,
+        :variables => compile_atts(:escape => true))
+    end
+  end
+end
+

data/lib/ruote/exp/fe_cancel_process.rb

@@ -0,0 +1,78 @@
+#--
+# 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
+
+  #
+  # Cancels a whole process instance.
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     sequence do
+  #       participant :ref => 'editor'
+  #       concurrence do
+  #         participant :ref => 'reviewer1'
+  #         participant :ref => 'reviewer2'
+  #         sequence do
+  #           participant :ref => 'main_reviewer'
+  #           cancel_process :if => '${f:over} == true'
+  #         end
+  #       end
+  #       participant :ref => 'editor'
+  #     end
+  #   end
+  #
+  # This example has a 'main_reviewer' with the ability to cancel the whole
+  # process, if he sets the workitem field 'over' to 'true'.
+  #
+  # If the goal is to cancel only a segment of a process instance, the
+  # expression 'undo' (Ruote::Exp::UndoExpression) is better suited.
+  #
+  # == 'terminate'
+  #
+  # Sometimes 'terminate' reads better than 'cancel_process'
+  #
+  #   Ruote.process_definition do
+  #     alice :task => 'do this'
+  #     terminate :if => '${no_need_for_bob}'
+  #     bob :task => 'do that'
+  #     charly :task => 'just do it'
+  #   end
+  #
+  class CancelProcessExpression < FlowExpression
+
+    names :cancel_process, :terminate
+
+    def apply
+
+      @context.storage.put_msg('cancel_process', 'wfid' => h.fei['wfid'])
+    end
+
+    def reply(workitem)
+
+      # never called
+    end
+  end
+end
+

data/lib/ruote/exp/fe_command.rb

@@ -0,0 +1,156 @@
+#--
+# 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/command'
+
+
+module Ruote::Exp
+
+  #
+  # This class gathers the 'skip', 'back', 'jump', 'rewind', 'continue', 'reset'
+  # and 'break' expressions which are used inside of the 'cursor' and 'repeat'
+  # (loop) expressions.
+  #
+  # Look at the 'cursor' expression Ruote::Exp::Cursor for a discussion of
+  # each of those [sub]expressions.
+  #
+  # The expression that understand commands are 'cursor', 'repeat' ('loop') and
+  # 'iterator'.
+  # 'concurrent_iterator' does not understand commands since it fires all its
+  # branches when applied.
+  #
+  # == :ref => 'tag'
+  #
+  # It's OK to tag a cursor/loop/iterator 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).
+  #
+  # :ref works with the 'iterator' expression as well.
+  #
+  class CommandExpression < FlowExpression
+
+    include CommandMixin
+
+    names :skip, :back, :jump, :rewind, :continue, :break, :stop, :over, :reset
+
+    def apply
+
+      param = case name
+        when 'skip', 'back' then attribute(:step) || attribute_text
+        when 'jump' then attribute(:to) || attribute_text
+        else nil
+      end
+
+      param = Integer(param) rescue param
+
+      command_workitem = Ruote.fulldup(h.applied_workitem)
+
+      set_command(command_workitem, name, param)
+
+      target = parent
+      ancestor = true
+
+      if ref = attribute(:ref)
+
+        fei = lookup_variable(ref)
+
+        target = Ruote::FlowExpressionId.is_a_fei?(fei) ?
+          Ruote::Exp::FlowExpression.fetch(@context, fei) : nil
+
+        target = target.is_a?(Ruote::Exp::CommandedExpression) ?
+          target : nil
+
+        ancestor = target ? ancestor?(target.h.fei) : false
+
+      else
+
+        target = fetch_command_target
+      end
+
+      return reply_to_parent(h.applied_workitem) if target.nil?
+      return reply_to_parent(command_workitem) if target.h.fei == h.parent_id
+
+      @context.storage.put_msg(
+        'reply',
+        'fei' => target.h.fei,
+        'workitem' => command_workitem,
+        'command' => [ name, param ]) # purely indicative for now
+
+      reply_to_parent(h.applied_workitem) unless ancestor
+    end
+
+    protected
+
+    # Walks up the expression tree (process instance and returns the first
+    # expression that includes the CommandMixin
+    #
+    # (CommandExpression includes CommandMixin, but since it doesn't have
+    # children, no need to 'evince' it)
+    #
+    def fetch_command_target(exp=parent)
+
+      case exp
+        when nil then nil
+        when Ruote::Exp::CommandedExpression then exp
+        else fetch_command_target(exp.parent)
+      end
+    end
+  end
+end
+

data/lib/ruote/exp/fe_concurrence.rb

@@ -0,0 +1,321 @@
+#--
+# 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/merge'
+
+
+module Ruote::Exp
+
+  #
+  # The 'concurrence' expression applies its child branches in parallel
+  # (well it makes a best effort to make them run in parallel).
+  #
+  #   concurrence do
+  #     alpha
+  #     bravo
+  #   end
+  #
+  # == attributes
+  #
+  # The concurrence expression takes a number of attributes that allow for
+  # sophisticated control (especially at merge time).
+  #
+  # === :count
+  #
+  #   concurrence :count => 1 do
+  #     alpha
+  #     bravo
+  #   end
+  #
+  # in that example, the concurrence will terminate as soon as 1 (count) of
+  # the branches replies. The other branch will get cancelled.
+  #
+  # === :remaining
+  #
+  # As said for :count, the remaining branches get cancelled. By setting
+  # :remaining to :forget (or 'forget'), the remaining branches will continue
+  # their execution, forgotten.
+  #
+  #   concurrence :count => 1, :remaining => :forget do
+  #     alpha
+  #     bravo
+  #   end
+  #
+  # === :merge
+  #
+  # By default, the workitems override each others. By default, the first
+  # workitem to reply will win.
+  #
+  #   sequence do
+  #     concurrence do
+  #       alpha
+  #       bravo
+  #     end
+  #     charly
+  #   end
+  #
+  # In that example, if 'alpha' replied first, the workitem that reaches
+  # 'charly' once 'bravo' replied will have the payload as seen/modified by
+  # 'alpha'.
+  #
+  # The :merge attribute determines which branch wins the merge.
+  #
+  # * first (default)
+  # * last
+  # * highest
+  # * lowest
+  #
+  # highest and lowest refer to the position in the list of branch. It's useful
+  # to set a fixed winner.
+  #
+  #   concurrence :merge => :highest do
+  #     alpha
+  #     bravo
+  #   end
+  #
+  # makes sure that alpha's version of the workitem wins.
+  #
+  # === :merge_type
+  #
+  # ==== :override
+  #
+  # By default, the merge type is set to 'override', which means that the
+  # 'winning' workitem's payload supplants all other workitems' payloads.
+  #
+  # ==== :mix
+  #
+  # Setting :merge_type to :mix, will actually attempt to merge field by field,
+  # making sure that the field value of the winner(s) are used.
+  #
+  # ==== :isolate
+  #
+  # :isolate will rearrange the resulting workitem payload so that there is
+  # a new field for each branch. The name of each field is the index of the
+  # branch from '0' to ...
+  #
+  # ==== :stack
+  #
+  # :stack will stack the workitems coming back from the concurrence branches
+  # in an array whose order is determined by the :merge attributes. The array
+  # is placed in the 'stack' field of the resulting workitem.
+  # Note that the :stack merge_type also creates a 'stack_attributes' field
+  # and populates it with the expanded attributes of the concurrence.
+  #
+  # Thus
+  #
+  #   sequence do
+  #     concurrence :merge => :highest, :merge_type => :stack do
+  #       reviewer1
+  #       reviewer2
+  #     end
+  #     editor
+  #   end
+  #
+  # will see the 'editor' receive a workitem whose fields look like :
+  #
+  #   { 'stack' => [{ ... reviewer1 fields ... }, { ... reviewer2 fields ... }],
+  #     'stack_attributes' => { 'merge'=> 'highest', 'merge_type' => 'stack' } }
+  #
+  # This could prove useful for participant having to deal with multiple merge
+  # strategy results.
+  #
+  # ==== :union
+  #
+  # Will override atomic fields, concat arrays and merge hashes...
+  #
+  # The union of those two workitems
+  #
+  #   { 'a' => 0, 'b' => [ 'x' ], 'c' => { 'aa' => 'bb' }
+  #   { 'a' => 1, 'b' => [ 'y' ], 'c' => { 'cc' => 'dd' }
+  #
+  # will be
+  #
+  #   { 'a' => 1, 'b' => [ 'x', 'y' ], 'c' => { 'aa' => 'bb', 'cc' => 'dd' } }
+  #
+  #
+  # === :over_if (and :over_unless)
+  #
+  # Like the :count attribute controls how many branches have to reply before
+  # a concurrence ends, the :over attribute is used to specify a condition
+  # upon which the concurrence will [prematurely] end.
+  #
+  #   concurrence :over_if => '${f:over}'
+  #     alpha
+  #     bravo
+  #     charly
+  #   end
+  #
+  # will end the concurrence as soon as one of the branches replies with a
+  # workitem whose field 'over' is set to true. (the remaining branches will
+  # get cancelled unless :remaining => :forget is set).
+  #
+  # :over_unless needs no explanation.
+  #
+  class ConcurrenceExpression < FlowExpression
+
+    include MergeMixin
+
+    names :concurrence
+
+    def apply
+
+      h.ccount = attribute(:count).to_i rescue 0
+      h.ccount = nil if h.ccount < 1
+
+      h.cmerge = att(:merge, %w[ first last highest lowest ])
+      h.cmerge_type = att(:merge_type, %w[ override mix isolate stack union ])
+      h.remaining = att(:remaining, %w[ cancel forget ])
+
+      h.workitems = (h.cmerge == 'first' || h.cmerge == 'last') ? [] : {}
+
+      h.over = false
+
+      apply_children
+    end
+
+    def reply(workitem)
+
+      workitem = Ruote.fulldup(workitem)
+        #
+        # since workitem field merging might happen, better to work on
+        # a copy of the workitem (so that history, coming afterwards,
+        # doesn't see a modified version of the workitem)
+
+      if h.cmerge == 'first' || h.cmerge == 'last'
+        h.workitems << workitem
+      else
+        h.workitems[workitem['fei']['expid']] = workitem
+      end
+
+      over = h.over
+      h.over = over || over?(workitem)
+
+      if (not over) && h.over
+        # just became 'over'
+
+        reply_to_parent(nil)
+
+      elsif h.children.empty?
+
+        do_unpersist || return
+
+        @context.storage.put_msg(
+          'ceased',
+          'wfid' => h.fei['wfid'], 'fei' => h.fei, 'workitem' => workitem)
+      else
+
+        do_persist
+      end
+    end
+
+    protected
+
+    def apply_children
+
+      # a) register children
+      # b) persist
+      # c) trigger children applies
+
+      msgs = []
+
+      tree_children.each_with_index do |c, i|
+        msgs << pre_apply_child(i, h.applied_workitem.dup, false)
+      end
+
+      persist_or_raise
+
+      msgs.each { |m| @context.storage.put_msg('apply', m) }
+    end
+
+    def over?(workitem)
+
+      over_if = attribute(:over_if, workitem)
+      over_unless = attribute(:over_unless, workitem)
+
+      if over_if && Condition.true?(over_if)
+        true
+      elsif over_unless && (not Condition.true?(over_unless))
+        true
+      else
+        (h.workitems.size >= expected_count)
+      end
+    end
+
+    # How many branch replies are expected before the concurrence is over ?
+    #
+    # (note : concurrent_iterator overrides it)
+    #
+    def expected_count
+
+      h.ccount ? [ h.ccount, tree_children.size ].min : tree_children.size
+    end
+
+    def reply_to_parent(_workitem)
+
+      workitem = merge_all_workitems
+
+      if h.ccount == nil || h.children.empty?
+
+        do_unpersist && super(workitem, false)
+
+      elsif h.remaining == 'cancel'
+
+        if r = do_unpersist
+
+          super(workitem, false)
+
+          h.children.each do |i|
+            @context.storage.put_msg('cancel', 'fei' => i) #unless replied?(i)
+          end
+        end
+
+      else # h.remaining == 'forget'
+
+        h.variables = compile_variables
+        h.forgotten = true
+
+        do_persist && super(workitem, false)
+      end
+    end
+
+    def merge_all_workitems
+
+      return h.applied_workitem if h.workitems.size < 1
+
+      wis = case h.cmerge
+        when 'first'
+          h.workitems.reverse
+        when 'last'
+          h.workitems
+        when 'highest', 'lowest'
+          is = h.workitems.keys.sort.collect { |k| h.workitems[k] }
+          h.cmerge == 'highest' ? is.reverse : is
+      end
+
+      merge_workitems(wis, h.cmerge_type)
+    end
+  end
+end
+