ruote 2.1.11 → 2.2.0

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

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# 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

data/lib/ruote/exp/{fe_when.rb → fe_once.rb}

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# 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
@@ -26,14 +26,14 @@
 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.
+  # 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
   #
-  #     _when '${v:/invoice_status} == emitted' do
+  #     once '${v:/invoice_status} == emitted' do
   #       open_customer_support_account
   #     end
   #
@@ -44,8 +44,6 @@ module Ruote::Exp
   #     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.
@@ -55,7 +53,7 @@ module Ruote::Exp
   #
   #   sequence do
   #     first_stage
-  #     _when '${v:ready_for_second_stage}'
+  #     once '${v:ready_for_second_stage}'
   #     second_stage
   #   end
   #
@@ -64,7 +62,7 @@ module Ruote::Exp
   # 'sequence'.
   #
   #   concurrence do
-  #     _when :test => '${v:go_on} == yes' do
+  #     once :test => '${v:go_on} == yes' do
   #       subprocess :ref => 'final_stage'
   #     end
   #     sequence do
@@ -80,13 +78,13 @@ module Ruote::Exp
   # if you prefer it this way, you can use the :test attribute to formulate the
   # condition :
   #
-  #   <when test="${v:ready}">
+  #   <once test="${v:ready}">
   #     <participant ref="role_publisher" />
-  #   </when>
+  #   </once>
   #
   # In a Ruby process definition :
   #
-  #   _when :test => '${v:ready}' do
+  #   once :test => '${v:ready}' do
   #     participant :ref => 'role_publisher'
   #   end
   #
@@ -98,7 +96,7 @@ module Ruote::Exp
   #
   #   sequence do
   #     participant 'logistic_unit'
-  #     _when '${v:/delivery_ok}', :frequency => '2d'
+  #     once '${v:/delivery_ok}', :frequency => '2d'
   #       # block until delivery is OK (another branch of the process probably)
   #       # check every two days
   #     participant 'accounting_unit'
@@ -109,8 +107,8 @@ module Ruote::Exp
   #
   # 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
+  #   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
@@ -124,7 +122,7 @@ module Ruote::Exp
   # 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
+  # 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.
   #
   #
@@ -133,13 +131,19 @@ module Ruote::Exp
   # Remember that, if the engine's 'ruby_eval_allowed' is set to true, the
   # condition may contain Ruby code.
   #
-  #   _when '${r:"hell" + "o"} == hello'
+  #   once '${r:"hell" + "o"} == hello'
   #
   # This Ruby code is checked before hand against malicious code, but beware...
   #
-  class WhenExpression < FlowExpression
+  #
+  # == aliases
+  #
+  # 'once', '_when' and 'as_soon_as' are three different names for this
+  # expression.
+  #
+  class OnceExpression < FlowExpression
 
-    names :when, :as_soon_as
+    names :once, :when, :as_soon_as
 
     def apply
 
@@ -150,7 +154,7 @@ module Ruote::Exp
       reply(h.applied_workitem)
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       return reply_to_parent(workitem) if h.triggered
 
@@ -180,10 +184,10 @@ module Ruote::Exp
       end
     end
 
-    def cancel (flavour)
+    def cancel(flavour)
 
       @context.storage.delete_schedule(h.job_id)
-      reply_to_parent(h.applied_workitem)
+      super
     end
 
     protected

data/lib/ruote/exp/fe_participant.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# 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
@@ -91,7 +91,8 @@ module Ruote::Exp
   #
   # 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 #timeout method and provide a meaningful timeout value.
+  # 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.
@@ -114,9 +115,6 @@ module Ruote::Exp
   #
   class ParticipantExpression < FlowExpression
 
-    #include FilterMixin
-      # TODO
-
     names :participant
 
     # Should return true when the dispatch was successful.
@@ -166,11 +164,10 @@ module Ruote::Exp
         'fei' => h.fei,
         'participant_name' => h.participant_name,
         'participant' => h.participant,
-        'workitem' => h.applied_workitem,
-        'for_engine_worker?' => (participant_info.class != Array))
+        'workitem' => h.applied_workitem)
     end
 
-    def cancel (flavour)
+    def cancel(flavour)
 
       return reply_to_parent(h.applied_workitem) unless h.participant_name
         # no participant, reply immediately
@@ -189,7 +186,7 @@ module Ruote::Exp
         'workitem' => h.applied_workitem)
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       pinfo =
         h.participant ||
@@ -202,7 +199,7 @@ module Ruote::Exp
       super(workitem)
     end
 
-    def reply_to_parent (workitem)
+    def reply_to_parent(workitem)
 
       workitem['fields'].delete('params')
       workitem['fields'].delete('dispatched_at')
@@ -218,7 +215,7 @@ module Ruote::Exp
     # See http://groups.google.com/group/openwferu-users/browse_thread/thread/ff29f26d6b5fd135
     # for the motivation.
     #
-    def do_dispatched (msg)
+    def do_dispatched(msg)
 
       h.dispatched = true
       do_persist
@@ -236,18 +233,18 @@ module Ruote::Exp
     # Note that process definition timeout has priority over participant
     # specified timeout.
     #
-    def schedule_timeout (p_info)
+    def schedule_timeout(p_info)
 
       timeout = attribute(:timeout)
 
       unless timeout
 
-        pa = @context.plist.instantiate(p_info, :if_respond_to? => :timeout)
+        pa = @context.plist.instantiate(p_info, :if_respond_to? => :rtimeout)
 
-        timeout = pa.timeout if pa && pa.method(:timeout).arity == 0
-          #
-          # the arity check is for jruby which seems to have a timeout
-          # method here and there
+        timeout = (pa.method(:rtimeout).arity == 0 ?
+          pa.rtimeout :
+          pa.rtimeout(Ruote::Workitem.new(h.applied_workitem))
+        ) if pa
       end
 
       do_schedule_timeout(timeout)

data/lib/ruote/exp/fe_redo.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# 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
@@ -29,8 +29,8 @@ module Ruote::Exp
   # Undoes and the redoes (re-applies) an expression identified by a tag.
   #
   #   pdef = Ruote.process_definition do
-  #     sequence do
-  #       alpha :tag => 'kilroy'
+  #     sequence :tag => 'kilroy' do
+  #       alpha
   #       _redo :ref => 'kilroy', :unless => '${f:ok} == true'
   #     end
   #   end
@@ -43,11 +43,15 @@ module Ruote::Exp
   #
   #   pdef = Ruote.process_definition do
   #     cursor do
-  #       alpha :tag => 'kilroy'
+  #       alpha
   #       rewind :unless => '${f:ok} == true'
   #     end
   #   end
   #
+  # (There is a big difference though, a redo will restart with the workitem
+  # as it was when the workitem entered the tagged region, while the rewind
+  # keeps the workitem as is)
+  #
   class RedoExpression < FlowExpression
 
     names :redo
@@ -57,7 +61,7 @@ module Ruote::Exp
       ref = attribute(:ref) || attribute_text
       tag = ref ? lookup_variable(ref) : nil
 
-      if tag
+      if tag && Ruote.is_a_fei?(tag)
 
         @context.storage.put_msg('cancel', 'fei' => tag, 're_apply' => true)
 
@@ -69,7 +73,7 @@ module Ruote::Exp
       end
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       # never called
     end

data/lib/ruote/exp/fe_ref.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# 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

data/lib/ruote/exp/fe_registerp.rb

@@ -0,0 +1,112 @@
+#--
+# 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
+
+  #
+  # (Since ruote 2.1.12)
+  #
+  # This expressions lets one register participants directly from a process
+  # definition.
+  #
+  #   pdef = Ruote.define do
+  #
+  #     registerp 'alpha', :class => 'MyParticipant', :target => 'mail'
+  #       # register participant named 'alpha' with the given class
+  #       # and some attributes
+  #
+  #     registerp /^user_.+/, :class => 'MyParticipant'
+  #     registerp :regex => '^user_.+', :class => 'MyParticipant'
+  #       # register participant with a given regular expression
+  #
+  #     registerp 'admin', :class => 'MyParticipant', :position => -2
+  #       # register participant 'admin' as second to last in participant list
+  #   end
+  #
+  # Participant info can be given as attributes to the expression (see code
+  # above) or via the workitem.
+  #
+  #   pdef = Ruote.define do
+  #
+  #     registerp :participant => 'participant'
+  #       # participant info is found in the field 'participant'
+  #
+  #     registerp :participants => 'participants'
+  #       # an array of participant info is found in the field 'participants'
+  #   end
+  #
+  # The expression 'unregisterp' can be used to remove participants from the
+  # participant list.
+  #
+  class RegisterpExpression < FlowExpression
+
+    names :registerp
+
+    def apply
+
+      registerp_allowed?
+
+      if pa = attribute('participant')
+
+        register_participant(h.applied_workitem['fields'][pa])
+
+      elsif pas = attribute('participants')
+
+        h.applied_workitem['fields'][pas].each do |part|
+          register_participant(part)
+        end
+
+      else
+
+        register_participant(attributes)
+      end
+
+      reply_to_parent(h.applied_workitem)
+    end
+
+    def reply(workitem)
+
+      # never called
+    end
+
+    protected
+
+    def registerp_allowed?
+
+      raise ArgumentError.new(
+        "'registerp_allowed' is set to false, cannot [un]register " +
+        "participants from process definitions"
+      ) if context['registerp_allowed'] != true
+    end
+
+    def register_participant(info)
+
+      name, (klass, opts) = Ruote::ParticipantEntry.read(info)
+
+      context.engine.register_participant(name, klass, opts)
+    end
+  end
+end
+