ruote 0.9.18

data/lib/openwfe/expressions/fe_if.rb

@@ -0,0 +1,303 @@
+#
+#--
+# Copyright (c) 2006-2008, John Mettraux, OpenWFE.org
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without 
+# modification, are permitted provided that the following conditions are met:
+# 
+# . Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.  
+# 
+# . Redistributions in binary form must reproduce the above copyright notice, 
+#   this list of conditions and the following disclaimer in the documentation 
+#   and/or other materials provided with the distribution.
+# 
+# . Neither the name of the "OpenWFE" nor the names of its contributors may be
+#   used to endorse or promote products derived from this software without
+#   specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
+# POSSIBILITY OF SUCH DAMAGE.
+#++
+#
+
+#
+# "made in Japan"
+#
+# John Mettraux at openwfe.org
+#
+
+require 'openwfe/workitem'
+require 'openwfe/flowexpressionid'
+require 'openwfe/expressions/condition'
+require 'openwfe/expressions/flowexpression'
+
+
+#
+# expressions like 'set' and 'unset' and their utility methods
+#
+
+module OpenWFE
+
+    #
+    # The 'if' expression.
+    #
+    #     <if>
+    #         <equals field-value="f0" other-value="true" />
+    #         <participant ref="alpha" />
+    #     </if>
+    #
+    # It accepts an 'else' clause :
+    #
+    #     <if>
+    #         <equals field-value="f0" other-value="true" />
+    #         <participant ref="alpha" />
+    #         <participant ref="bravo" />
+    #     </if>
+    #
+    # The 'test' attribute can be used instead of a condition child :
+    #
+    #     <if test="${f:f0}">
+    #         <participant ref="alpha" />
+    #     </if>
+    #
+    # The 'rtest' attribute can be used to embed a condition expressed directly
+    # in Ruby :
+    #
+    #     <if rtest="5 * 12 == 61">
+    #         <participant ref="alpha" />
+    #     </if>
+    #
+    # (Note that 'rtest' may only be used if the <tt>:ruby_eval_allowed</tt>
+    # parameter has been set in the engine's application_context :
+    #
+    #     engine.application_context[:ruby_eval_allowed] = true
+    #
+    # but this is dangerous if the origin of the process defintions to run
+    # are not trusted)
+    #
+    # Used alone with 'test' or 'rtest', the 'if' expression simply sets the 
+    # the __result__ field of its workitem to the result of its attribute
+    # evaluation :
+    #
+    #     <if test="5 == 6"/>
+    #
+    # will set the __result__ field of the workitem to 'false'.
+    #
+    class IfExpression < FlowExpression
+        include ConditionMixin
+
+        names :if
+
+        #
+        # This boolean is set to true when the conditional claused has
+        # been evaluated and the 'if' is waiting for the consequence's
+        # reply.
+        #
+        attr_accessor :condition_replied
+
+
+        def apply (workitem)
+
+            #workitem.unset_result
+                #
+                # since OpenWFEru 0.9.16 previous __result__ values
+                # are not erased before an 'if'.
+
+            test = eval_condition :test, workitem, :not
+
+            if @children.length < 1
+                #workitem.set_result test if test
+                workitem.set_result((test != nil and test != false))
+                reply_to_parent workitem
+                return
+            end
+
+            @condition_replied = (test != nil)
+                #
+                # if the "test" attribute is not used, test will be null
+
+            store_itself
+
+            # a warning
+
+            maxchildren = (test == nil) ? 3 : 2
+
+            lwarn { 
+                "apply() 'if' with more than #{maxchildren} children"
+            } if @children.size > maxchildren
+
+            # apply next step
+
+            if test != nil
+                #
+                # apply then or else (condition result known)
+                #
+                apply_consequence test, workitem, 0
+            else
+                #
+                # apply condition
+                #
+                get_expression_pool.apply @children.first, workitem
+            end
+        end
+
+        def reply (workitem)
+
+            return reply_to_parent(workitem) \
+                if @condition_replied
+
+            result = workitem.attributes[FIELD_RESULT]
+
+            @condition_replied = true
+
+            store_itself
+
+            apply_consequence result, workitem
+        end
+
+        #
+        # This reply_to_parent takes care of cleaning all the children
+        # before replying to the parent expression, this is important
+        # because only the 'then' or the 'else' child got evaluated, the 
+        # remaining one has to be cleaned out here.
+        #
+        def reply_to_parent (workitem)
+
+            clean_children
+            super workitem
+        end
+
+        protected
+
+            def apply_consequence (index, workitem, offset=1)
+
+                if index == true
+                    index = 0
+                elsif index == false
+                    index = 1
+                elsif index == nil
+                    index = 1
+                elsif not index.integer?
+                    index = 0
+                end
+
+                index = index + offset
+
+                if index >= @children.length
+                    reply_to_parent workitem
+                else
+                    get_expression_pool.apply @children[index], workitem
+                end
+            end
+    end
+
+    #
+    # The 'case' expression.
+    #
+    #     <case>
+    #
+    #         <equals field="f0" other-value="ready" />
+    #         <participant ref="alpha" />
+    #
+    #         <if test="${supply_level} == ${field:supply_request}" />
+    #         <participant ref="bravo" />
+    #
+    #         <participant ref="charly" />
+    #
+    #     </case>
+    #
+    # A generalized 'if'. Will evaluate its children, expecting the order :
+    #
+    #     - condition
+    #     - consequence
+    #     - condition
+    #     - consequence
+    #     ...
+    #     - else consequence (optional)
+    #
+    # The 'switch' nickname can be used for 'case'.
+    #
+    class CaseExpression < FlowExpression
+
+        names :case, :switch
+
+        #
+        # keeping track of where we are in the case iteration
+        #
+        attr_accessor :offset
+
+        #
+        # set to 'true' when the case expression is actually evaluating
+        # a condition (ie not triggering a consequence).
+        #
+        attr_accessor :evaluating_condition
+
+
+        def apply (workitem)
+
+            #workitem.unset_result
+                #
+                # since OpenWFEru 0.9.16 previous __result__ values
+                # are not erased before a 'case'.
+
+            @offset = nil
+
+            trigger_child workitem, true
+        end
+
+        def reply (workitem)
+
+            if @evaluating_condition
+
+                result = workitem.get_boolean_result
+
+                #ldebug { "reply() result : '#{result.to_s}' (#{result.class})" }
+
+                trigger_child workitem, !result
+            else
+
+                reply_to_parent workitem
+            end
+        end
+
+        protected
+
+            def trigger_child (workitem, is_condition)
+
+                @offset = if !@offset
+                    0
+                elsif is_condition
+                    @offset + 2
+                else
+                    @offset + 1
+                end
+
+                #ldebug { "trigger_child() is_condition ? #{is_condition}" }
+                #ldebug { "trigger_child() next offset is #{@offset}" }
+
+                unless @children[@offset]
+                    reply_to_parent workitem
+                    return
+                end
+
+                @evaluating_condition = is_condition
+
+                store_itself
+
+                get_expression_pool.apply(@children[@offset], workitem)
+            end
+    end
+
+end
+

data/lib/openwfe/expressions/fe_iterator.rb

@@ -0,0 +1,145 @@
+#
+#--
+# Copyright (c) 2007-2008, John Mettraux, OpenWFE.org
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without 
+# modification, are permitted provided that the following conditions are met:
+# 
+# . Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.  
+# 
+# . Redistributions in binary form must reproduce the above copyright notice, 
+#   this list of conditions and the following disclaimer in the documentation 
+#   and/or other materials provided with the distribution.
+# 
+# . Neither the name of the "OpenWFE" nor the names of its contributors may be
+#   used to endorse or promote products derived from this software without
+#   specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
+# POSSIBILITY OF SUCH DAMAGE.
+#++
+#
+
+#
+# "made in Japan"
+#
+# John Mettraux at openwfe.org
+#
+
+require 'openwfe/expressions/flowexpression'
+require 'openwfe/expressions/iterator'
+require 'openwfe/expressions/fe_command'
+
+
+module OpenWFE
+
+    #
+    # The 'iterator' expression can be used like that for example :
+    #
+    #     <iterator
+    #         on-value="alice, bob, charles"
+    #         to-variable="user-name"
+    #     >
+    #         <set 
+    #             field="${user-name} comment" 
+    #             value="(please fill this field)"
+    #         />
+    #     </iterator>
+    #
+    # Within the iteration, the workitem field "\_\_ic__" contains the number
+    # of elements in the iteration and the field "\_\_ip__" the index of the
+    # current iteration.
+    #
+    # The 'iterator' expression understands the same cursor commands as the
+    # CursorExpression. One can thus exit an iterator or skip steps in it.
+    #
+    #     iterator :on_value => "alice, bob, charles, doug", to_variable => "v" do
+    #         sequence do
+    #             participant :variable_ref => "v"
+    #             skip 1, :if => "${f:reply} == 'skip next'"
+    #         end
+    #     end
+    #
+    # For more information about those commands, see CursorCommandExpression.
+    #
+    class IteratorExpression < FlowExpression
+        include CommandMixin
+
+        names :iterator
+
+        uses_template
+
+        #
+        # an Iterator instance that holds the list of values being iterated
+        # upon.
+        #
+        attr_accessor :iterator
+
+        def apply (workitem)
+
+            return reply_to_parent(workitem) \
+                if raw_children.length < 1
+
+            @iterator = Iterator.new(self, workitem)
+
+            return reply_to_parent(workitem) \
+                if @iterator.size < 1
+
+            reply workitem
+        end
+
+        def reply (workitem)
+
+            command, step = determine_command_and_step workitem
+
+            vars = if not command
+
+                @iterator.next workitem
+
+            elsif command == C_BREAK or command == C_CANCEL
+
+                nil
+
+            elsif command == C_REWIND or command == C_CONTINUE
+
+                @iterator.rewind workitem
+
+            elsif command.match "^#{C_JUMP}"
+
+                @iterator.jump workitem, step
+
+            else # C_SKIP or C_BACK
+
+                @iterator.skip workitem, step
+            end
+
+            return reply_to_parent(workitem) \
+                unless vars
+
+            @children = []
+
+            get_expression_pool.tlaunch_child(
+                self,
+                raw_children.first,
+                @iterator.index,
+                workitem,
+                true, # registering child
+                vars)
+            
+            store_itself
+        end
+    end
+
+end
+

data/lib/openwfe/expressions/fe_listen.rb

@@ -0,0 +1,371 @@
+#
+#--
+# Copyright (c) 2007-2008, John Mettraux, OpenWFE.org
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without 
+# modification, are permitted provided that the following conditions are met:
+# 
+# . Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.  
+# 
+# . Redistributions in binary form must reproduce the above copyright notice, 
+#   this list of conditions and the following disclaimer in the documentation 
+#   and/or other materials provided with the distribution.
+# 
+# . Neither the name of the "OpenWFE" nor the names of its contributors may be
+#   used to endorse or promote products derived from this software without
+#   specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
+# POSSIBILITY OF SUCH DAMAGE.
+#++
+#
+
+#
+# "made in Japan"
+#
+# John Mettraux at openwfe.org
+#
+
+require 'openwfe/expressions/merge'
+require 'openwfe/expressions/timeout'
+require 'openwfe/expressions/condition'
+require 'openwfe/expressions/flowexpression'
+
+
+module OpenWFE
+
+    #
+    # The "listen" expression can be viewed in two ways :
+    #
+    # 1)
+    # It's a hook into the participant map to intercept apply or reply
+    # operations on participants.
+    #
+    # 2)
+    # It allows OpenWFE[ru] to be a bit closer to the 'ideal' process-calculus
+    # world (http://en.wikipedia.org/wiki/Process_calculi)
+    #
+    # Anyway...
+    #
+    #     <listen to="alice">
+    #         <subprocess ref="notify_bob" />
+    #     </listen>
+    #
+    # Whenever a workitem is dispatched (applied) to the participant 
+    # named "alice", the subprocess named "notify_bob" is triggered (once).
+    #
+    #     listen :to => "^channel_.*", :upon => "reply" do
+    #         sequence do
+    #             participant :ref => "delta"
+    #             participant :ref => "echo"
+    #         end
+    #     end
+    #
+    # After the listen has been applied, the first workitem coming back from 
+    # a participant whose named starts with "channel_" will trigger a sequence
+    # with the participants 'delta' and 'echo'.
+    #
+    #     listen :to => "alpha", :where => "${f:color} == red" do
+    #         participant :ref => "echo"
+    #     end
+    #
+    # Will send a copy of the first workitem meant for participant "alpha" to 
+    # participant "echo" if this workitem's color field is set to 'red'.
+    #
+    #     listen :to => "alpha", :once => "false" do
+    #         send_email_to_stakeholders
+    #     end
+    #
+    # This is some kind of a server : each time a workitem is dispatched to
+    # participant "alpha", the subprocess (or participant) named 
+    # 'send_email_to_stakeholders') will receive a copy of that workitem.
+    # Use with care.
+    #
+    #     listen :to => "alpha", :once => "false", :timeout => "1M2w" do
+    #         send_email_to_stakeholders
+    #     end
+    #
+    # The 'listen' expression understands the 'timeout' attribute. It can thus
+    # be instructed to stop listening after a certain amount of time (here,
+    # after one month and two weeks).
+    #
+    # The listen expression can be used without a
+    # child expression. It blocks until a valid messages comes in the 
+    # channel, at which point it resumes the process, with workitem that came
+    # as the message (not with the workitem at apply time).
+    # (no merge implemented for now).
+    #
+    #     sequence do
+    #         listen :to => "channel_z", :upon => :reply
+    #         participant :the_rest_of_the_process
+    #     end
+    #
+    # In this example, the process will block until a workitem comes for
+    # a participant named 'channel_z'.
+    #
+    # The engine accept (in its reply() 
+    # method) workitems that don't belong to a process intance (ie workitems
+    # that have a nil flow_expression_id). So it's entirely feasible to
+    # send 'notifications only' workitems to the OpenWFEru engine.
+    # (see http://openwferu.rubyforge.org/svn/trunk/openwfe-ruby/test/ft_54b_listen.rb)
+    #
+    # This expression has been aliased 'intercept'
+    # and 'receive'. It also accepts the 'on' parameter as an alias parameter
+    # to the 'to' parameter. Think "listen to" and "receive on".
+    #
+    # A 'merge' attribute can be set to true (the 
+    # default value being false), the incoming workitem will then be merged
+    # with a copy of the workitem that 'applied' (activated) the listen
+    # expression.
+    #
+    class ListenExpression < FlowExpression
+        include TimeoutMixin
+        include ConditionMixin
+        include MergeMixin
+
+        names :listen, :intercept, :receive
+
+        uses_template
+
+        #
+        # the channel on which this expression 'listens'
+        #
+        attr_accessor :participant_regex
+
+        #
+        # is set to true if the expression listen to 1! workitem and
+        # then replies to its parent.
+        # When set to true, it listens until the process it belongs to
+        # terminates.
+        # The default value is true.
+        #
+        attr_accessor :once
+
+        #
+        # can take :apply or :reply as a value, if not set (nil), will listen
+        # on both 'directions'.
+        #
+        attr_accessor :upon
+
+        #
+        # 'listen' accepts a :merge attribute, when set to true, this
+        # field will contain a copy of the workitem that activated the
+        # listen activity. This copy will be merged with incoming (listened
+        # for) workitems when triggering the listen child.
+        #
+        attr_accessor :applied_workitem
+
+        #
+        # how many messages were received (can more than 0 or 1 if 'once'
+        # is set to false).
+        #
+        attr_accessor :call_count
+
+
+        def apply (workitem)
+
+            #if @children.size < 1
+            #    reply_to_parent workitem
+            #    return
+            #end
+                #
+                # 'listen' now blocks if there is no children
+
+            @participant_regex = lookup_string_attribute(:to, workitem)
+
+            @participant_regex = lookup_string_attribute(:on, workitem) \
+                unless @participant_regex
+
+            raise "attribute 'to' is missing for expression 'listen'" \
+                unless @participant_regex
+
+            ldebug { "apply() listening to '#{@participant_regex}'" }
+
+            #
+            # once
+
+            @once = lookup_boolean_attribute :once, workitem, true
+
+            @once = true if raw_children.size < 1
+                # a 'blocking listen' can only get triggered once.
+
+            ldebug { "apply() @once is #{@once}" }
+
+            #
+            # merge
+
+            merge = lookup_boolean_attribute :merge, workitem, false
+
+            ldebug { "apply() merge is #{@merge}" }
+
+            @applied_workitem = workitem.dup if merge
+
+            #
+            # upon
+
+            @upon = lookup_sym_attribute(
+                :upon, workitem, :default => :apply)
+
+            @upon = (@upon == :reply) ? :reply : :apply
+
+            ldebug { "apply() @upon is #{@upon}" }
+
+            @call_count = 0
+
+            determine_timeout
+            reschedule get_scheduler
+
+            store_itself
+        end
+
+        def cancel
+
+            stop_observing
+            super
+        end
+
+        def reply_to_parent (workitem)
+
+            ldebug { "reply_to_parent() 'listen' done." }
+
+            stop_observing
+            super
+        end
+
+        #
+        # Only called in case of timeout.
+        #
+        def trigger (params)
+
+            reply_to_parent workitem
+        end
+
+        #
+        # This is the method called when a 'listenable' workitem comes in
+        #
+        def call (channel, *args)
+            #synchronize do
+
+            upon = args[0]
+
+            ldebug { "call() channel : '#{channel}' upon '#{upon}'" }
+
+            return if upon != @upon
+
+            workitem = args[1].dup
+
+            conditional = eval_condition :where, workitem
+                #
+                # note that the values if the incoming workitem (not the
+                # workitem at apply time) are used for the evaluation
+                # of the condition (if necessary).
+
+            return if conditional == false
+
+            return if @once and @call_count > 0
+
+            #
+            # workitem does match...
+
+            ldebug do 
+                "call() "+
+                "through for fei #{workitem.fei} / "+
+                "'#{workitem.participant_name}'"
+            end
+
+            @call_count += 1
+
+            #ldebug { "call() @call_count is #{@call_count}" }
+
+            #
+            # eventual merge
+            
+            workitem = merge_workitems @applied_workitem.dup, workitem \
+                if @applied_workitem
+
+            #
+            # reply or launch nested child expression
+
+            return reply_to_parent(workitem) \
+                if raw_children.size < 1
+                    #
+                    # was just a "blocking listen"
+
+            #parent = @once ? self : nil
+            #get_expression_pool.launch_template(
+            #    parent, 
+            #    nil, 
+            #    @call_count - 1, 
+            #    @children[0], 
+            #    workitem, 
+            #    nil)
+
+            if @once
+
+                # triggering just once
+
+                get_expression_pool.tlaunch_child(
+                    self,
+                    raw_children.first,
+                    @call_count - 1,
+                    workitem,
+                    true) # registering child
+
+            else
+
+                # triggering multiple times
+
+                get_expression_pool.tlaunch_orphan(
+                    self,
+                    raw_children.first,
+                    @call_count - 1,
+                    workitem,
+                    true) # registering child (in case of cancel)
+            end
+
+            store_itself
+            #end
+        end
+
+        #
+        # Registers for timeout and start observing the participant
+        # activity.
+        #
+        def reschedule (scheduler)
+
+            to_reschedule(scheduler)
+            start_observing
+        end
+
+        protected
+
+            #
+            # Start observing a [participant name] channel.
+            #
+            def start_observing
+
+                get_participant_map.add_observer @participant_regex, self
+            end
+
+            #
+            # Expression's job is over, deregister.
+            #
+            def stop_observing
+
+                get_participant_map.remove_observer self
+            end
+    end
+
+end
+