ruote 0.9.20 → 2.1.1

data/lib/ruote/exp/fe_subprocess.rb

@@ -0,0 +1,203 @@
+#--
+# 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::Exp
+
+  #
+  # An expression for invoking a subprocess.
+  #
+  #   pdef = Ruote.process_definition do
+  #     sequence do
+  #       subprocess :ref => 'delivering'
+  #       subprocess 'invoicing'
+  #       refill_stock :if => '${v:stock_size} < 10'
+  #     end
+  #     define 'delivering' do
+  #       # ...
+  #     end
+  #     define 'invoicing' do
+  #       # ...
+  #     end
+  #     define 'refill_stock' do
+  #       # ...
+  #     end
+  #   end
+  #
+  #
+  # == passing attributes as variables
+  #
+  # The attributes of the subprocess expression are passed as variables of
+  # the new subprocess instance.
+  #
+  #   Ruote.process_definition do
+  #     subprocess 'sub0', :a => 'A', :b => 'B'
+  #     define :sub0 do
+  #       echo '${v:a}:${v:b}'
+  #     end
+  #   end
+  #
+  # This example (and useless) process example will output "A:B" to STDOUT.
+  #
+  #
+  # == passing 'blocks' to subprocesses
+  #
+  # When the subprocess expression has children, the first of them is passed
+  # to the subprocess instance as the 'tree' variable, readily available for
+  # an 'apply' expression.
+  #
+  #   Ruote.process_definition :name => 'double review' do
+  #     sequence do
+  #       sub0 do
+  #         review_board
+  #       end
+  #       sub0 do
+  #         review_board
+  #       end
+  #     end
+  #     define 'sub0' do
+  #       concurrence do
+  #         apply :i => 0
+  #         apply :i => 1
+  #         apply :i => 2
+  #       end
+  #     end
+  #   end
+  #
+  # This example will send 2 x 3 concurrent workitems to the participant
+  # named 'review_board' (note that it could also be the name of another
+  # subprocess).
+  #
+  #
+  # == passing 'parameters' to subprocess
+  #
+  #   Ruote.process_definition :name => 'whatever' do
+  #
+  #     call :who => 'the cops', :when => 'if I\'m not back at 3'
+  #
+  #     process_definition 'call' do
+  #       participant :ref => '${v:who}', :msg => 'this is a call'
+  #     end
+  #   end
+  #
+  # This binds the variables 'who' and 'when' in the subprocess instance.
+  #
+  # Of course you can combine parameters and blocks passing.
+  #
+  #
+  # == pointing to subprocesses via their URI
+  #
+  # It's OK to invoke subprocesses via a URI
+  #
+  #   subprocess :ref => 'pdefs/definition1.rb'
+  #
+  # or
+  #
+  #   subprocess :ref => 'http://pdefs.example.org/account/def1.xml'
+  #
+  # Remember that the :remote_definition_allowed option of the engine has
+  # to be set to true for the latter to work, else the engine will refuse
+  # to load definitions over HTTP.
+  #
+  # Shorter :
+  #
+  #   subprocess 'http://pdefs.example.org/account/def1.xml'
+  #
+  #
+  # == subprocess URIs bound at engine level
+  #
+  # There is a class of variables accessible to process instances in read-only
+  # mode : engine level variables.
+  #
+  # They can be set via the engine's initialization code (or later) like in
+  # this example :
+  #
+  #   engine.variables['inventory_check'] = 'http://pdefs.example.com/ic0.rb'
+  #
+  # All the process instance in the engine may then trigger this process in
+  # these 3 ways :
+  #
+  #   subprocess :ref => 'inventory_check'
+  #   subprocess 'inventory_check'
+  #   inventory_check
+  #
+  # The latter may make process definitions quite readable (but blur the
+  # distinction between expressions, call to participants or to subprocesses).
+  #
+  class SubprocessExpression < FlowExpression
+
+    names :subprocess
+
+    def apply
+
+      ref = attribute(:ref) || attribute_text
+
+      raise "no subprocess referred in #{tree}" unless ref
+
+      pos, subtree = lookup_subprocess(ref)
+
+      vars = compile_atts
+      vars.merge!('tree' => tree_children.first)
+        # NOTE : we're taking the first child here...
+
+      launch_sub(pos, subtree, :variables => vars)
+    end
+
+    protected
+
+    def lookup_subprocess (ref)
+
+      val = lookup_variable(ref)
+
+      # a classical subprocess stored in a variable ?
+
+      return [ '0', val ] if is_tree?(val)
+      return val if is_pos_tree?(val)
+
+      # maybe subprocess :ref => 'uri'
+
+      subtree = @context.parser.parse(ref) rescue nil
+
+      _, subtree = Ruote::Exp::DefineExpression.reorganize(subtree) \
+        if subtree && Ruote::Exp::DefineExpression.is_definition?(subtree)
+
+      return [ '0', subtree ] if is_tree?(subtree)
+
+      # no luck ...
+
+      raise "no subprocess named '#{ref}' found"
+    end
+
+    def is_tree? (a)
+
+      a.is_a?(Array) && a[1].is_a?(Hash) && a.size == 3
+    end
+
+    def is_pos_tree? (a)
+
+      a.is_a?(Array) && a.size == 2 && a[0].is_a?(String) && is_tree?(a[1])
+    end
+  end
+end
+

data/lib/{openwfe/expool/errors.rb → ruote/exp/fe_undo.rb}

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2009, John Mettraux, jmettraux@gmail.com
+# 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
@@ -23,47 +23,45 @@
 #++
 
 
-module OpenWFE
+module Ruote::Exp
 
   #
-  # This error is raised when an expression belonging to a paused
-  # process is applied or replied to.
+  # Undoes (cancels) another expression referred by its tag.
   #
-  class PausedError < RuntimeError
+  #   pdef = Ruote.process_definition do
+  #     concurrence do
+  #       alpha :tag => 'kilroy'
+  #       undo :ref => 'kilroy'
+  #     end
+  #   end
+  #
+  # This example is rather tiny, but it shows a process branch (undo) cancelling
+  # another (alpha).
+  #
+  # == cancel
+  #
+  # This expression is aliased to 'cancel'
+  #
+  #   cancel :ref => 'invoicing_stage'
+  #
+  class UndoExpression < FlowExpression
 
-    attr_reader :wfid
+    names :undo, :cancel
 
-    def initialize (wfid)
+    def apply
 
-      super "process '#{wfid}' is paused"
-      @wfid = wfid
-    end
+      ref = attribute(:ref) || attribute_text
+      tag = ref ? lookup_variable(ref) : nil
 
-    #
-    # Returns a hash for this PausedError instance.
-    # (simply returns the hash of the paused process' wfid).
-    #
-    def hash
+      @context.storage.put_msg('cancel', 'fei' => tag)
 
-      @wfid.hash
+      reply_to_parent(h.applied_workitem)
     end
 
-    #
-    # Returns true if the other is a PausedError issued for the
-    # same process instance (wfid).
-    #
-    def == (other)
+    def reply (workitem)
 
-      return false unless other.is_a?(PausedError)
-
-      (@wfid == other.wfid)
+      # never called
     end
   end
-
-  #
-  # This is the error used by the 'error' expression (forcing an error...)
-  #
-  class ForcedError < RuntimeError
-  end
 end
 

data/lib/ruote/exp/fe_wait.rb

@@ -0,0 +1,92 @@
+#--
+# 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::Exp
+
+  #
+  # Waits (sleeps) for a given period of time before resuming the flow.
+  #
+  #   sequence do
+  #     accounting :task => 'invoice'
+  #     wait '30d' # 30 days
+  #     accounting :task => 'check if customer paid'
+  #   end
+  #
+  # '_sleep' is also OK
+  #
+  #   _sleep '7d10h' # 7 days and 10 hours
+  #
+  # (the underscore prevents collision with Ruby's sleep method)
+  #
+  # == :for and :until
+  #
+  # TODO
+  #
+  class WaitExpression < FlowExpression
+
+    names :wait, :sleep
+
+    def apply
+
+      h.for = attribute(:for) || attribute_text
+      h.until = attribute(:until)
+
+      s = h.for
+      s = h.until if s == ''
+
+      h.at = s
+
+      if h.at
+
+        h.schedule_id = @context.storage.put_schedule(
+          'at',
+          h.fei,
+          h.at,
+          'action' => 'reply',
+          'fei' => h.fei,
+          'workitem' => h.applied_workitem)
+
+        persist_or_raise
+
+      else
+
+        reply_to_parent(h.applied_workitem)
+      end
+    end
+
+    #--
+    # no need to override, simply reply to parent expression.
+    #def reply (workitem)
+    #end
+    #++
+
+    def cancel (flavour)
+
+      @context.storage.delete_schedule(h.schedule_id)
+      reply_to_parent(h.applied_workitem)
+    end
+  end
+end
+

data/lib/ruote/exp/fe_when.rb

@@ -0,0 +1,214 @@
+#--
+# 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::Exp
+
+  #
+  # The '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
+  #
+  #     _when '${v:/invoice_status} == emitted' do
+  #       open_customer_support_account
+  #     end
+  #
+  #     sequence do
+  #       participant 'accounting'
+  #       set 'v:/invoice_status' => 'emitted'
+  #       participant 'accounting 2'
+  #     end
+  #   end
+  #
+  # Note the '_when' since 'when' is a Ruby keyword :-(
+  #
+  # 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
+  #     _when '${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
+  #     _when :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 :
+  #
+  #   <when test="${v:ready}">
+  #     <participant ref="role_publisher" />
+  #   </when>
+  #
+  # In a Ruby process definition :
+  #
+  #   _when :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'
+  #
+  #      _when '${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.
+  #
+  #   _when '${v:delivery_complete}', :freq => '5 0 * * *'
+  #     # this 'when' 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 'when' 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.
+  #
+  #   _when '${r:"hell" + "o"} == hello'
+  #
+  # This Ruby code is checked before hand against malicious code, but beware...
+  #
+  class WhenExpression < FlowExpression
+
+    names :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)
+      reply_to_parent(h.applied_workitem)
+    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
+