ruote-maestrodev 2.2.1

data/lib/ruote/exp/fe_lose.rb

@@ -0,0 +1,110 @@
+#--
+# 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
+
+  #
+  # Never replies to its parent expression. Simply applies its first child,
+  # if any, and just sits there.
+  #
+  # When cancelled, cancels its child (if any).
+  #
+  # In this example, the reminding sequence never replies to the concurrence.
+  # The concurrence is only over when "alfred" replies.
+  #
+  #   Ruote.process_definition do
+  #     concurrence :count => 1 do
+  #       alfred
+  #       lose do
+  #         sequence do
+  #           wait '2d'
+  #           send_reminder_to_alfred
+  #           wait '2h'
+  #           send_alarm_to_boss
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # Maybe shorter :
+  #
+  #   Ruote.process_definition do
+  #     concurrence :count => 1 do
+  #       alfred
+  #       sequence do
+  #         wait '2d'
+  #         send_reminder_to_alfred
+  #         wait '2h'
+  #         send_alarm_to_boss
+  #         lose
+  #       end
+  #     end
+  #   end
+  #
+  # 'lose' on its own acts like a dead-end.
+  #
+  #
+  # == the :lose attribute
+  #
+  # Every expression understands the 'lose' attribute :
+  #
+  #   Ruote.process_definition do
+  #     concurrence :count => 1 do
+  #       alfred
+  #       sequence :lose => true do
+  #         wait '2d'
+  #         send_reminder_to_alfred
+  #         wait '2h'
+  #         send_alarm_to_boss
+  #       end
+  #     end
+  #   end
+  #
+  # Probably produces definitions more compact than when using the 'lose'
+  # expression.
+  #
+  # == forget vs lose
+  #
+  # forget : replies to parent expression immediately, is not cancellable
+  # (not reachable).
+  #
+  # lose : never replies to parent expression, is cancellable.
+  #
+  class LoseExpression < FlowExpression
+
+    names :lose
+
+    def apply
+
+      apply_child(0, h.applied_workitem)
+    end
+
+    def reply(workitem)
+
+      # never gets called
+    end
+  end
+end
+

data/lib/ruote/exp/fe_noop.rb

@@ -0,0 +1,45 @@
+#--
+# 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
+
+  #
+  # 'No Operation' expression. Does nothing, immediately replies to
+  # its parent expression.
+  #
+  # Could be useful within a cursor expression with a :tag attribute
+  # as a jump expression target.
+  #
+  class NoOpExpression < FlowExpression
+
+    names :noop
+
+    def apply
+
+      reply_to_parent(h.applied_workitem)
+    end
+  end
+end
+

data/lib/ruote/exp/fe_once.rb

@@ -0,0 +1,215 @@
+#--
+# 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 'once' / 'when' expression verifies if a condition is true,
+  # if not it will block and after 10 seconds it will check again.
+  # If true, it will resume or it will execute its child expression (before
+  # resuming).
+  #
+  #   concurrence do
+  #
+  #     once '${v:/invoice_status} == emitted' do
+  #       open_customer_support_account
+  #     end
+  #
+  #     sequence do
+  #       participant 'accounting'
+  #       set 'v:/invoice_status' => 'emitted'
+  #       participant 'accounting 2'
+  #     end
+  #   end
+  #
+  # The condition is usually something about variables, since the workitem that
+  # this expression has access to is always the one that reached it, at apply
+  # time.
+  #
+  # Without a child expression, this expression behaves in a 'blocking way', and
+  # it makes most sense in a 'sequence' or in a 'cursor'.
+  #
+  #   sequence do
+  #     first_stage
+  #     once '${v:ready_for_second_stage}'
+  #     second_stage
+  #   end
+  #
+  # When there is a child expression, it will get triggered when the condition
+  # realizes. Only 1 child expression is accepted, there is no implicit
+  # 'sequence'.
+  #
+  #   concurrence do
+  #     once :test => '${v:go_on} == yes' do
+  #       subprocess :ref => 'final_stage'
+  #     end
+  #     sequence do
+  #       participant :ref => 'controller'
+  #       set 'v:go_on' => 'yes'
+  #     end
+  #   end
+  #
+  # == :test
+  #
+  # Most of the example process definitions until now were placing the condition
+  # directly after the expression name itself. In an XML process definition or
+  # if you prefer it this way, you can use the :test attribute to formulate the
+  # condition :
+  #
+  #   <once test="${v:ready}">
+  #     <participant ref="role_publisher" />
+  #   </once>
+  #
+  # In a Ruby process definition :
+  #
+  #   once :test => '${v:ready}' do
+  #     participant :ref => 'role_publisher'
+  #   end
+  #
+  #
+  # == :frequency
+  #
+  # As said, the default 'check' frequency is 10 seconds. This can be changed
+  # by using the :frequency (or :freq) attribute.
+  #
+  #   sequence do
+  #     participant 'logistic_unit'
+  #     once '${v:/delivery_ok}', :frequency => '2d'
+  #       # block until delivery is OK (another branch of the process probably)
+  #       # check every two days
+  #     participant 'accounting_unit'
+  #   end
+  #
+  #
+  # == :frequency and cron notation
+  #
+  # It's OK to pass a 'cron string' to the :frequency attribute.
+  #
+  #   once '${v:delivery_complete}', :freq => '5 0 * * *'
+  #     # this 'once' will check its condition once per day, five minutes
+  #     # after midnight
+  #
+  # See "man 5 crontab" on your favourite unix system for the details of
+  # the 'cron string', but please note that ruote (thanks to the
+  # rufus-scheduler (http://rufus.rubyforge.org/rufus-scheduler) accepts
+  # seconds as well.
+  #
+  #
+  # == the :timeout attribute common to all expressions
+  #
+  # Don't forget that this expression, like all the other expressions accepts
+  # the :timeout attribute. It's perhaps better to use :timeout when there is
+  # a child expression, so that the child won't get 'triggered' in case of
+  # timeout. When there is no child expression and the 'once' behaves in a
+  # 'blocking way', a timeout will unblock, as if the condition became true.
+  #
+  #
+  # == ${ruby:'hello'}
+  #
+  # Remember that, if the engine's 'ruby_eval_allowed' is set to true, the
+  # condition may contain Ruby code.
+  #
+  #   once '${r:"hell" + "o"} == hello'
+  #
+  # This Ruby code is checked before hand against malicious code, but beware...
+  #
+  #
+  # == aliases
+  #
+  # 'once', '_when' and 'as_soon_as' are three different names for this
+  # expression.
+  #
+  class OnceExpression < FlowExpression
+
+    names :once, :when, :as_soon_as
+
+    def apply
+
+      h.frequency = attribute(:frequency) || attribute(:freq) || '10s'
+      h.triggered = false
+      h.job_id = nil
+
+      reply(h.applied_workitem)
+    end
+
+    def reply(workitem)
+
+      return reply_to_parent(workitem) if h.triggered
+
+      t = attribute(:test) || attribute_text
+
+      if Condition.true?(t)
+
+        h.triggered = true
+
+        @context.storage.delete_schedule(h.job_id)
+          # especially for a cron...
+
+        if tree_children[0]
+          #
+          # trigger first child
+          #
+          apply_child(0, workitem)
+        else
+          #
+          # blocking case
+          #
+          reply_to_parent(workitem)
+        end
+      else
+
+        reschedule
+      end
+    end
+
+    def cancel(flavour)
+
+      @context.storage.delete_schedule(h.job_id)
+      super
+    end
+
+    protected
+
+    def reschedule
+
+      h.job_id = @context.storage.put_schedule(
+        'cron',
+        h.fei,
+        h.frequency,
+        '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_participant.rb

@@ -0,0 +1,287 @@
+#--
+# 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/condition'
+
+
+module Ruote::Exp
+
+  #
+  # The 'participant' expression is very special. It sits on the fence between
+  # the engine and the external world.
+  #
+  # The participant expression is used to pass workitems to participants
+  # from the engine. Those participants are bound at start time (usually) in
+  # the engine via its register_participant method.
+  #
+  # Here's an example of two concurrent participant expressions in use :
+  #
+  #   concurrence do
+  #     participant :ref => 'alice'
+  #     participant :ref => 'bob'
+  #   end
+  #
+  # Upon encountering the two expressions, the engine will lookup their name
+  # in the participant map and hand the workitems to the participant instances
+  # registered for those names.
+  #
+  #
+  # == attributes passed as arguments
+  #
+  # All the attributes passed to a participant will be fed to the outgoing
+  # workitem under a new 'params' field.
+  #
+  # Thus, with
+  #
+  #     participant :ref => 'alice', :task => 'maw the lawn', :timeout => '2d'
+  #
+  # Alice will receive a workitem with a field params set to
+  #
+  #     { :ref => 'alice', :task => 'maw the lawn', :timeout => '2d' }
+  #
+  # The fields named 'params' will be deleted before the workitems resumes
+  # in the flow (with the engine replying to the parent expression of this
+  # participant expression).
+  #
+  #
+  # == simplified participant notation
+  #
+  # This process definition is equivalent to the one above. Less to write.
+  #
+  #   concurrence do
+  #     participant 'alice'
+  #     bob
+  #   end
+  #
+  # Please note that 'bob' alone could stand for the participant 'bob' or
+  # the subprocess named 'bob'. Subprocesses do take precedence over
+  # participants (if there is a subprocess named 'bob' and a participant
+  # named 'bob'.
+  #
+  #
+  # == participant defined timeout
+  #
+  # Usually, timeouts are given for an expression in the process definition.
+  #
+  #   participant 'alice', :timeout => '2d'
+  #
+  # where alice as two days to complete her task (send back the workitem).
+  #
+  # But it's OK for participant classes registered in the engine to provide
+  # their own timeout value. The participant instance simply has to reply to
+  # the #rtimeout method and provide a meaningful timeout value (like a
+  # number of seconds, or a string like "2d" or "1M2w".
+  #
+  # Note however, that the process definition timeout (if any) will take
+  # precedence over the participant specified one.
+  #
+  #
+  # == asynchronous
+  #
+  # The expression will make sure to dispatch to the participant in an
+  # asynchronous way. This means that the dispatch will occur in a dedicated
+  # thread.
+  #
+  # Since the dispatching to the participant could take a long time and block
+  # the engine for too long, this 'do thread' policy is used by default.
+  #
+  # If the participant itself replies to the method #do_not_thread and replies
+  # positively to it, a new thread (or a next_tick) won't get used. This is
+  # practical for tiny participants that don't do IO and reply immediately
+  # (after a few operations). By default, BlockParticipant instances do not
+  # thread.
+  #
+  class ParticipantExpression < FlowExpression
+
+    names :participant
+
+    # Should yield true when the dispatch was successful.
+    #
+    h_reader :dispatched
+
+    h_reader :participant
+
+    def apply
+
+      #
+      # determine participant
+
+      h.participant_name = (attribute(:ref) || attribute_text).to_s
+
+      raise ArgumentError.new(
+        "no participant name specified"
+      ) if h.participant_name == ''
+
+      h.participant ||=
+        @context.plist.lookup_info(h.participant_name, h.applied_workitem)
+
+      raise(ArgumentError.new(
+        "no participant named #{h.participant_name.inspect}")
+      ) if h.participant.nil?
+
+      #
+      # dispatch to participant
+
+      h.applied_workitem['participant_name'] = h.participant_name
+
+      h.applied_workitem['fields']['params'] = compile_atts
+      h.applied_workitem['fields'].delete('t')
+
+      schedule_timeout(h.participant)
+
+      persist_or_raise
+
+      @context.storage.put_msg(
+        'dispatch',
+        'fei' => h.fei,
+        'participant_name' => h.participant_name,
+        'participant' => h.participant,
+        'workitem' => h.applied_workitem)
+    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 cannot continue
+
+      @context.storage.put_msg(
+        'dispatch_cancel',
+        'fei' => h.fei,
+        'participant_name' => h.participant_name,
+        'participant' => h.participant,
+        'flavour' => flavour,
+        'workitem' => h.applied_workitem)
+    end
+
+    def reply(workitem)
+
+      pinfo =
+        h.participant ||
+        @context.plist.lookup_info(h.participant_name, workitem)
+
+      pa = @context.plist.instantiate(pinfo, :if_respond_to? => :on_reply)
+
+      pa.on_reply(Ruote::Workitem.new(workitem)) if pa
+
+      super(workitem)
+    end
+
+    def reply_to_parent(workitem)
+
+      workitem['fields'].delete('params')
+      workitem['fields'].delete('dispatched_at')
+      super(workitem)
+    end
+
+    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.
+    #
+    def consider_timeout
+    end
+
+    # Determines and schedules timeout if any.
+    #
+    # Note that process definition timeout has priority over participant
+    # specified timeout.
+    #
+    def schedule_timeout(p_info)
+
+      timeout = attribute(:timeout)
+
+      unless timeout
+
+        pa = @context.plist.instantiate(p_info, :if_respond_to? => :rtimeout)
+
+        timeout = (pa.method(:rtimeout).arity == 0 ?
+          pa.rtimeout :
+          pa.rtimeout(Ruote::Workitem.new(h.applied_workitem))
+        ) if pa
+      end
+
+      do_schedule_timeout(timeout)
+    end
+
+    def do_pause(msg)
+
+      return if h.state != nil
+
+      h['state'] = 'paused'
+      h['breakpoint'] = true if msg['breakpoint']
+
+      do_persist || return
+
+      @context.storage.put_msg(
+        'dispatch_pause',
+        'fei' => h.fei,
+        'participant_name' => h.participant_name,
+        'participant' => h.participant
+      ) unless msg['breakpoint']
+    end
+
+    def do_resume(msg)
+
+      return if h.state != 'paused'
+
+      h['state'] = nil
+      replies = h.delete('paused_replies') || []
+
+      do_persist || return
+
+      if replies.empty?
+        @context.storage.put_msg(
+          'dispatch_resume',
+          'fei' => h.fei,
+          'participant_name' => h.participant_name,
+          'participant' => h.participant
+        ) unless h['breakpoint']
+      else
+        replies.each { |m| @context.storage.put_msg(m.delete('action'), m) }
+          # trigger replies
+      end
+    end
+  end
+end
+