ruote 0.9.20 → 2.1.1

data/lib/ruote/exp/fe_listen.rb

@@ -0,0 +1,197 @@
+#--
+# 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.
+#++
+
+
+require 'ruote/exp/condition'
+
+
+module Ruote::Exp
+
+  #
+  # Listens for activity (incoming or outgoing workitems) on a (set of)
+  # participant(s).
+  #
+  # This expression is an advanced one. It allows for cross process instance
+  # communication or at least cross branch communication within the same
+  # process instance.
+  #
+  # DO NOT confuse the listen expression with the 'listener' concept. They are
+  # not directly related. The listen expression listens to workitem activity
+  # inside of the engine, while a listener listens for workitems or launchitems
+  # from sources external to the ruote workflow engine.
+  #
+  # It can be used in two ways : 'blocking' or 'triggering'. In both cases
+  # the listen expression 'reacts' upon activity (incoming or outgoing workitem)
+  # happening on a channel (a participant name).
+  #
+  # == blocking
+  #
+  # A blocking example :
+  #
+  #   sequence do
+  #     participant 'alice'
+  #     listen :to => 'bob'
+  #     participant 'charly'
+  #   end
+  #
+  # Once the listen expression got applied, this process will block until a
+  # workitem (in any other process instance in the same engine) is dispatched
+  # to participant 'bob'. It then proceeds to charly.
+  #
+  # == triggering
+  #
+  # This way of using 'listen' is useful for launching processes that "stalk"
+  # other processes :
+  #
+  #   Ruote.process_definition :name => 'stalker' do
+  #     listen :to => 'bob' do
+  #       participant :ref => 'charly'
+  #     end
+  #   end
+  #
+  # This small process will never exits and will send a workitem to charly
+  # each time the ruote engine sends a workitem to bob.
+  #
+  # The workitems passed to charly will be copies of the workitem initially
+  # applied to the 'listen' expression, but with a copy of the fields of the
+  # workitem passed to bob, merged in.
+  #
+  # Note : for now, the triggered segments of processes are 'forgotten'. The
+  # 'listen' expression doesn't keep track of them. This also means that in
+  # case of cancel, the triggered segments will not get cancelled.
+  #
+  # == :merge
+  #
+  # By default, :merge is set to true, the listened for workitems see their
+  # values merged into a copy of the workitem held in the listen expression
+  # and this copy is delivered to the expressions that are client to the
+  # 'listen'.
+  #
+  # == :upon
+  #
+  # There are two kinds of main events in ruote, apply and reply. Thus,
+  # a listen expression may listen to 'apply' and to 'reply' and this is
+  # defined by the :upon attribute.
+  #
+  # By default, listens upon 'apply' (engine handing workitem to participant).
+  #
+  # Can be set to 'reply', to react on workitems being handed back to the
+  # engine by the participant.
+  #
+  # == :to and :on
+  #
+  # The :to attribute has already been seen, it can be replaced by the :on one.
+  #
+  # Those two attributes are expected to hold regular expressions, so it's OK to
+  # write things like :
+  #
+  #   listen :to => "^user\_.+"
+  #
+  # or
+  #
+  #   listen :to => /^user\_.+/
+  #
+  # To listen for workitems for all the participant whose name start with
+  # "user_".
+  #
+  # == :wfid
+  #
+  # By default, a listen expression listens for any workitem/participant event
+  # in the engine. Setting the :wfid attribute to 'true' or 'same' or 'current'
+  # will make the listen expression only care for events belonging to the
+  # same process instance (same wfid).
+  #
+  class ListenExpression < FlowExpression
+
+    names :listen, :receive, :intercept
+
+    def apply
+
+      h.to = attribute(:to) || attribute(:on)
+
+      upon = attribute(:upon) || 'apply'
+      h.upon = (upon == 'reply') ? 'receive' : 'dispatch'
+
+      h.lmerge = attribute(:merge).to_s
+      h.lmerge = 'true' if h.lmerge == ''
+
+      h.wfid = attribute(:wfid).to_s
+      h.wfid = %w[ same current true ].include?(h.wfid)
+
+      persist_or_raise
+
+      @context.tracker.add_tracker(
+        h.wfid ? h.fei['wfid'] : nil,
+        h.upon,
+        h.fei,
+        { 'participant_name' => h.to },
+        { 'action' => 'reply', 'fei' => h.fei, 'flavour' => 'listen' })
+    end
+
+    def reply (workitem)
+
+      #
+      # :where guard
+
+      where = attribute(:where, workitem)
+      return if where && ( ! Condition.true?(where))
+
+      #
+      # green for trigger
+
+      wi = h.applied_workitem.dup
+
+      if h.lmerge == 'true'
+        wi['fields'].merge!(workitem['fields'])
+      elsif h.lmerge == 'override'
+        wi['fields'] = workitem['fields']
+      #else don't touch
+      end
+
+      if tree_children.size > 0
+
+        launch_sub(
+          "#{h.fei['expid']}_0", tree[2][0], :forget => true, :workitem => wi)
+      else
+
+        reply_to_parent(wi)
+      end
+    end
+
+    def cancel (flavour)
+
+      reply_to_parent(h.applied_workitem)
+    end
+
+    protected
+
+    def reply_to_parent (workitem)
+
+      @context.tracker.remove_tracker(h.fei)
+
+      super(workitem)
+    end
+  end
+end
+

data/lib/{openwfe/engine.rb → ruote/exp/fe_noop.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
@@ -22,7 +22,24 @@
 # Made in Japan.
 #++
 
-# just for nicer looking examples
 
-require 'openwfe/engine/engine'
+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_participant.rb

@@ -0,0 +1,202 @@
+#--
+# 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.
+#++
+
+
+require 'ruote/workitem'
+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 #timeout method and provide a meaningful timeout value.
+  #
+  # 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
+
+    #include FilterMixin
+      # TODO
+
+    names :participant
+
+    def apply
+
+      #
+      # determine participant
+
+      h.participant_name = attribute(:ref) || attribute_text
+
+      h.participant_name = h.participant_name.to_s
+
+      if h.participant_name == ''
+        raise ArgumentError.new("no participant name specified")
+      end
+
+      participant_info = @context.plist.lookup_info(h.participant_name)
+
+      raise(ArgumentError.new(
+        "no participant named #{h.participant_name.inspect}")
+      ) if participant_info.nil?
+
+      #
+      # participant found, consider timeout
+
+      schedule_timeout(participant_info)
+
+      #
+      # dispatch to participant
+
+      h.applied_workitem['participant_name'] = h.participant_name
+      h.applied_workitem['fields']['params'] = compile_atts
+
+      persist_or_raise
+
+      @context.storage.put_msg(
+        'dispatch',
+        'fei' => h.fei,
+        'participant_name' => h.participant_name,
+        'workitem' => h.applied_workitem,
+        'for_engine_worker?' => participant_info.class != Array)
+    end
+
+    def cancel (flavour)
+
+      participant = @context.plist.lookup(h.participant_name)
+      participant.cancel(fei, flavour)
+        # should this be threaded ?
+
+      reply_to_parent(h.applied_workitem)
+    end
+
+    def reply_to_parent (workitem)
+
+      workitem['fields'].delete('params')
+      super(workitem)
+    end
+
+    protected
+
+    # 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) ||
+        (p_info.respond_to?(:timeout) ? p_info.timeout : nil) ||
+        (p_info.is_a?(Array) ? p_info.last['timeout'] : nil)
+
+      do_schedule_timeout(timeout)
+    end
+  end
+end
+

data/lib/ruote/exp/fe_redo.rb

@@ -0,0 +1,83 @@
+#--
+# 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
+
+  #
+  # Undoes and the redoes (re-applies) an expression identified by a tag.
+  #
+  #   pdef = Ruote.process_definition do
+  #     sequence do
+  #       alpha :tag => 'kilroy'
+  #       _redo :ref => 'kilroy', :unless => '${f:ok} == true'
+  #     end
+  #   end
+  #
+  # will redo at tag 'kilroy' if the field 'ok' is not set to true.
+  #
+  # (redo is escaped as _redo not to conflict with the "redo" Ruby keyword)
+  #
+  # Maybe this case is better served by a cursor/rewind combination
+  #
+  #   pdef = Ruote.process_definition do
+  #     cursor do
+  #       alpha :tag => 'kilroy'
+  #       rewind :unless => '${f:ok} == true'
+  #     end
+  #   end
+  #
+  class RedoExpression < FlowExpression
+
+    names :redo
+
+    def apply
+
+      ref = attribute(:ref) || attribute_text
+      tag = ref ? lookup_variable(ref) : nil
+
+      if tag
+
+        @context.storage.put_msg('cancel', 'fei' => tag, 're_apply' => true)
+
+        reply_to_parent(h.applied_workitem) unless ancestor?(tag)
+
+      else
+
+        reply_to_parent(h.applied_workitem)
+      end
+    end
+
+    def reply (workitem)
+
+      # never called
+    end
+
+    def cancel (flavour)
+
+      reply_to_parent(h.applied_workitem)
+    end
+  end
+end
+