openwferu 0.9.10.653 → 0.9.11

data/lib/openwfe/expressions/fe_timeout.rb

@@ -0,0 +1,127 @@
+#
+#--
+# Copyright (c) 2007, 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.
+#++
+#
+# $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
+#
+
+#
+# "made in Japan"
+#
+# John Mettraux at openwfe.org
+#
+
+require 'openwfe/expressions/timeout'
+
+
+#
+# 'timeout' as a simple expression
+#
+
+module OpenWFE
+
+    #
+    # The timeout concept begun with the participant expression. When a
+    # participant doesn't reply for a certain amount of time, a specified
+    # timeout can get triggered.
+    # Sometimes something more complex than a single participant needs a 
+    # timeout setting, this expression sets a timeout for the expression[s]
+    # nested within it.
+    #
+    #     <timeout after="2d">
+    #         <sequence>
+    #             (...)
+    #         </sequence>
+    #     </timeout>
+    #
+    class TimeoutExpression < FlowExpression
+        include TimeoutMixin
+
+        names :timeout
+
+        attr_accessor :applied_workitem
+
+        def apply (workitem)
+
+            if @children.size < 1
+                reply_to_parent workitem
+                return
+            end
+
+            @applied_workitem = workitem.dup
+
+            schedule_timeout(:after)
+
+            get_expression_pool.apply @children[0], workitem
+        end
+
+        #
+        # The child expression replies, make sure to unschedule the timeout
+        # before replying (to our own parent expression).
+        #
+        def reply (workitem)
+
+            unschedule_timeout()
+
+            super
+        end
+
+        #
+        # Cancel order : cancels the child expression (if applied) and 
+        # unschedule the timeout (if any).
+        #
+        def cancel
+
+            get_expression_pool.cancel(@children[0]) if @applied_workitem
+
+            unschedule_timeout()
+
+            super
+        end
+
+        #
+        # The timeout trigger, cancels the nested process segment (the
+        # nested expression).
+        #
+        def trigger (scheduler)
+
+            ldebug { "trigger() timeout requested for #{@fei.to_debug_s}" }
+
+            set_timedout_flag(@applied_workitem)
+
+            cancel()
+
+            reply_to_parent @applied_workitem
+        end
+    end
+
+end
+

data/lib/openwfe/expressions/fe_when.rb

@@ -75,13 +75,25 @@ module OpenWFE
     # condition clause.
     # A different frequency can be stated via the "frequency" attribute :
     #
-    #     when :test => "${completion_level} == 4", :frequency => "1s"
+    #     _when :test => "${completion_level} == 4", :frequency => "1s"
     #         participant "next_stage"
     #     end
     #
     # will check for the completion_level value every second. The scheduler 
     # itself is by default 'waking up' every 250 ms, so setting a frequency to 
     # something smaller than that value might prove useless.
+    # (Note than in the Ruby process definition, the 'when' got escaped to
+    # '_when' not to conflict with the 'when' keyword of the Ruby language).
+    #
+    # The when expression understands the 'timeout' attribute like the 
+    # participant expression does. Thus
+    #
+    #     _when :test => "${cows} == 'do fly'", :timeout => "1y"
+    #         participant "me"
+    #     end
+    #
+    # will timeout after one year (participant "me" will not receive a 
+    # workitem).
     #
     class WhenExpression < WaitingExpression
 

data/lib/openwfe/expressions/flowexpression.rb

@@ -162,7 +162,7 @@ module OpenWFE
         # simply if the expression got swapped out of memory and reloaded later.
         #
         def store_itself
-            ldebug { "store_itself() for  #{@fei.to_debug_s}" }
+            #ldebug { "store_itself() for  #{@fei.to_debug_s}" }
             #ldebug { "store_itself() \n#{OpenWFE::caller_to_s(0, 6)}" }
             get_expression_pool.update self
         end
@@ -499,6 +499,9 @@ module OpenWFE
             children.each do |child|
                 if child.kind_of?(RawExpression)
                     text << child.fei.to_s
+                elsif child.kind_of?(FlowExpressionId)
+                    text << get_expression_pool\
+                        .fetch_expression(child).raw_representation.to_s
                 else
                     text << child.to_s
                 end

data/lib/openwfe/expressions/time.rb

@@ -70,7 +70,7 @@ module OpenWFE
 
                 unschedule()
 
-                return super()
+                super()
             end
         end
 
@@ -81,24 +81,6 @@ module OpenWFE
             get_scheduler.unschedule(@scheduler_job_id) \
                 if @scheduler_job_id
         end
-
-        protected
-
-            #
-            # Will return true if this TimeExpression has a 
-            # 'scheduler_job_ib' and this job is this expression's job.
-            #
-            # The job_id is specifiable, so that this method can also be
-            # used by the 'when' expression for example.
-            #
-            def already_scheduled? (job_id=nil)
-
-                job_id = @scheduler_job_id unless job_id
-
-                s = get_scheduler.get_schedulable job_id
-
-                return (s and s.fei == self.fei)
-            end
     end
 
     #
@@ -146,7 +128,7 @@ module OpenWFE
 
             store_itself()
 
-            trigger(nil)
+            trigger()
         end
 
         def reply (workitem)
@@ -165,16 +147,16 @@ module OpenWFE
             super()
         end
 
-        def trigger (params)
+        def trigger (params={})
 
             ldebug { "trigger() #{@fei.to_debug_s} params is #{params}" }
 
-            if params == :do_timeout!
+            if params[:do_timeout!]
                 #
                 # do timeout...
                 #
-                set_timedout_flag(@applied_workitem)
-                reply_to_parent(@applied_workitem)
+                set_timedout_flag @applied_workitem
+                reply_to_parent @applied_workitem
                 return
             end
 
@@ -185,10 +167,11 @@ module OpenWFE
 
         def reschedule (scheduler)
 
-            #return unless @applied_workitem
+            @scheduler_job_id = "waiting_#{fei.to_s}"
 
-            @scheduler_job_id = 
-                scheduler.schedule_in(@frequency, self, nil)
+            scheduler.schedule_in(
+                @frequency, 
+                { :schedulable => self, :job_id => @scheduler_job_id })
 
             ldebug { "reschedule() @scheduler_job_id is #{@scheduler_job_id}" }
 

data/lib/openwfe/expressions/timeout.rb

@@ -85,6 +85,15 @@ module OpenWFE
             to_reschedule(scheduler)
         end
 
+        #
+        # Combines a call to determine_timeout and to reschedule.
+        #
+        def schedule_timeout (timeout_attname=:timeout)
+
+            determine_timeout(timeout_attname)
+            to_reschedule(get_scheduler)
+        end
+
         #
         # Overrides the parent method to make sure a potential
         # timeout schedules gets removed.
@@ -118,7 +127,7 @@ module OpenWFE
             #
             def to_reschedule (scheduler)
 
-                return if @timeout_job_id
+                #return if @timeout_job_id
                     #
                     # already rescheduled
 
@@ -126,12 +135,19 @@ module OpenWFE
                     #
                     # no need for a timeout
 
-                @timeout_job_id = 
-                    scheduler.schedule_at(@timeout_at, self, :do_timeout!)
+                @timeout_job_id = "timeout_#{self.fei.to_s}"
+
+                scheduler.schedule_at(
+                    @timeout_at, 
+                    { :schedulable => self, 
+                      :job_id => @timeout_job_id,
+                      :do_timeout! => true })
 
                 ldebug do 
-                    "to_reschedule() will timeout at "+
-                    "#{OpenWFE::to_iso8601_date(@timeout_at)}"
+                    "to_reschedule() will timeout at " +
+                    "#{OpenWFE::to_iso8601_date(@timeout_at)}" +
+                    " @timeout_job_id is #{@timeout_job_id}" +
+                    " (oid #{object_id})"
                 end
 
                 #store_itself()
@@ -146,7 +162,8 @@ module OpenWFE
 
                 ldebug do 
                     "unschedule_timeout() " +
-                    "@timeout_job_id is #{@timeout_job_id}" 
+                    "@timeout_job_id is #{@timeout_job_id}" +
+                    " (oid #{object_id})"
                 end
 
                 #ldebug_callstack "unschedule_timeout()"

data/lib/openwfe/flowexpressionid.rb

@@ -44,7 +44,13 @@
 module OpenWFE
 
     #
-    # FlowExpressionId
+    # A FlowExpressionId is a unique identifier for a FlowExpression (an atomic
+    # piece of a process instance).
+    # 
+    # As workitems do transit among the expressions and are emitted outside
+    # of the business process engine via 'participant expressions', workitems
+    # out there are identified via the FlowExpressionId of the participant
+    # expression that pushed them out (and is waiting for them to come back).
     #
     class FlowExpressionId
 
@@ -139,11 +145,6 @@ module OpenWFE
 
         alias eql? ==
 
-        #alias to_debug_s to_s
-        #def to_debug_s
-        #    "#{to_s}  (h#{hash}) (i#{object_id})"
-        #end
-
         def to_debug_s
             "(fei #{@workflow_definition_name} #{@workflow_definition_revision} #{@workflow_instance_id} #{@expression_id} #{@expression_name})"
         end

data/lib/openwfe/listeners/socketlisteners.rb

@@ -129,7 +129,7 @@ module OpenWFE
                 #
                 # seems like XML
 
-                OpenWFE.xml_decode(data)
+                OpenWFE::XmlCodec::decode(data)
 
             elsif data[0, 3] == "---"
                 #

data/lib/openwfe/participants/enoparticipants.rb

@@ -47,7 +47,102 @@ require 'openwfe/participants/participant'
 module OpenWFE
 
     #
-    # This participant is used to send an email notification
+    # MailParticipant is a simplification of EmailNotificationParticipant.
+    #
+    # It's initialized in this way :
+    #
+    #     p = MailParticipant.new(
+    #         :smtp_server => "mailhost.ourcompany.co.jp",
+    #         :from_address => "bpms@our.ourcompany.co.jp",
+    #         :template => "Dear ${f:name}, you've got mail")
+    #
+    # or
+    #
+    #     p = MailParticipant.new(
+    #         :smtp_server => "mailhost.ourcompany.co.jp",
+    #         :smtp_port => 25,
+    #         :from_address => "bpms@our.ourcompany.co.jp"
+    #     ) do |workitem|
+    #         s = ""
+    #         s << "Dear #{workitem.name},\n"
+    #         s << "\n"
+    #         s << "it's #{Time.new.to_s} and you've got mail"
+    #         s
+    #     end
+    #
+    # When passing the mail template as a block, you have 
+    # four possible arities :
+    #     { |workitem| ... }
+    #     { |participant_expression, workitem| ... }
+    #     { |participant_expression, participant_instance, workitem| ... }
+    #     { ... }
+    #
+    # The smtp server and host default to "127.0.0.1" / 25.
+    #
+    class MailParticipant
+        include LocalParticipant
+
+        def initialize (params, &block)
+
+            @smtp_server = params[:smtp_server]
+            @smtp_port = params[:smtp_port]
+            @from_address = params[:from_address]
+            @template = params[:template]
+
+            @block_template = block
+
+            # some defaults
+
+            @smtp_server = "127.0.0.1" unless @smtp_server
+            @smtp_port = 25 unless @smtp_port
+        end
+
+        #
+        # The method called each time a workitem reaches this participant
+        #
+        def consume (workitem)
+
+            fe = get_flow_expression(workitem)
+            to_address = workitem.email_target
+
+            #
+            # 1. Expand variables
+
+            msg  = if @block_template
+                #@block_template.call(fe, self, workitem)
+                call_block @block_template, workitem
+            elsif @template
+                template = if @template.kind_of? File
+                    @template.readlines
+                else
+                    @template.to_s
+                end
+                OpenWFE::dosub(template, fe, workitem)
+            else
+                "(no template given)"
+            end
+
+            puts "msg >>>\n#{msg}<<<"
+
+            #
+            # 2. Send message
+
+            Net::SMTP.start(@smtp_server, @smtp_port) do |smtp|
+                smtp.send_message(msg, @from_address, to_address)
+            end
+
+            #
+            # 3. Reply to engine
+
+            reply_to_engine(workitem)
+        end
+    end
+
+    #
+    # This participant is used to send an email notification.
+    #
+    # It's perhaps better to use MailParticipant which is simpler to 
+    # initialiaze. This class is anyway an extension of MailParticipant.
     #
     #     @engine.register_participant(
     #         'eno', 
@@ -113,8 +208,7 @@ module OpenWFE
     # Note that the template integrates the subject and requires then a double
     # newline before the message body.
     #
-    class EmailNotificationParticipant 
-        include LocalParticipant
+    class EmailNotificationParticipant < MailParticipant
 
         #
         # Create a new email notification participant.  Requires
@@ -123,52 +217,14 @@ module OpenWFE
         def initialize (
             smtp_server, smtp_port, from_address, template=nil, &block)
 
-            @smtp_server = smtp_server
-            @smtp_port = smtp_port
-            @from_address = from_address
-            @template = template
+            params = {}
+            params[:smtp_server] = smtp_server
+            params[:smtp_port] = smtp_port
+            params[:from_address] = from_address
 
-            @block_template = block
-        end
+            params[:template] = template if template
 
-        #
-        # The method called each time a workitem reaches this participant
-        #
-        def consume (workitem)
-
-            fe = get_flow_expression(workitem)
-            to_address = workitem.email_target
-
-            #
-            # 1. Expand variables
-
-            msg  = if @block_template
-                @block_template.call(fe, self, workitem)
-            elsif @template
-                template = if @template.kind_of? File
-                    @template.readlines
-                else
-                    @template.to_s
-                end
-                OpenWFE::dosub(template, fe, workitem)
-            else
-                "(no template given)"
-            end
-
-            puts "msg >>>\n#{msg}<<<"
-
-            #
-            # 2. Send message
-
-            Net::SMTP.start(@smtp_server, @smtp_port) do |smtp|
-                smtp.send_message(msg, @from_address, to_address)
-            end
-
-            #
-            # 3. Reply to engine
-
-            reply_to_engine(workitem)
+            super(params, &block)
         end
-
     end
 end

data/lib/openwfe/participants/participant.rb

@@ -65,11 +65,12 @@ module OpenWFE
                 "is missing in class '#{self.class}'")
         end
 
-        #
+        #--
         # (optional)
         #
         #def cancel (cancelitem)
         #end
+        #++
     end
 
     #
@@ -88,8 +89,33 @@ module OpenWFE
 
             return nil if not @application_context
 
-            @application_context[S_EXPRESSION_POOL]\
-                .fetch_expression(workitem.flow_expression_id)
+            get_expression_pool.fetch_expression(workitem.flow_expression_id)
+        end
+
+        #
+        # A convenience method for calling block passed to participants
+        # for templates (mail participants) or execution (BlockParticipant).
+        #
+        # Allows for such blocks :
+        #
+        #     { |workitem| ... }
+        #     { |participant_expression, workitem| ... }
+        #     { |participant_expression, participant, workitem| ... }
+        #
+        # For 0 or more than 3 arguments, the block will be called without
+        # arguments.
+        #
+        def call_block (block, workitem)
+
+            if block.arity == 1
+                block.call workitem
+            elsif block.arity == 2
+                block.call get_flow_expression(workitem), workitem
+            elsif block.arity == 3
+                block.call get_flow_expression(workitem), self, workitem
+            else
+                block.call
+            end
         end
 
         #

data/lib/openwfe/participants/participantmap.rb

@@ -137,7 +137,7 @@ module OpenWFE
             @participants.each do |tuple|
                 return tuple[1] if tuple[0].match(participant_name)
             end
-            return nil
+            nil
         end
 
         #
@@ -153,7 +153,8 @@ module OpenWFE
                 end
             end
             @participants.delete(pos) if pos > -1
-            return pos > -1
+            
+            pos > -1
         end
 
         #
@@ -187,6 +188,13 @@ module OpenWFE
 
             onotify :dispatch, :after_consume, workitem
         end
+
+        #
+        # The method onotify (from Osbservable) is made public so that
+        # ParticipantExpression instances may notify the pmap of applies
+        # and replies.
+        #
+        public :onotify
     end
 
 end

data/lib/openwfe/participants/participants.rb

@@ -68,14 +68,6 @@ module OpenWFE
         #
         def initialize (context_or_dir=nil)
 
-            #if context_or_dir.kind_of? Hash
-            #    @application_context = context_or_dir
-            #    @workdir = @application_context[:work_directory]
-            #else
-            #    @workdir = context_or_dir
-            #end
-            #@workdir = OpenWFE::DEFAULT_WORK_DIRECTORY unless @workdir
-            #@workdir = "#{@workdir}/out/"
             @workdir = OpenWFE::get_work_directory(context_or_dir) + "/out/"
 
             @reply_anyway = false
@@ -177,18 +169,9 @@ module OpenWFE
 
         def consume (workitem)
 
-            result = if @block.arity == 1
-                @block.call workitem
-            elsif @block.arity > 1
-                @block.call get_flow_expression(workitem), workitem
-            else
-                @block.call
-            end
+            result = call_block @block, workitem
 
-            if result
-                #ldebug { "consume() result is of class #{result.class.name}" }
-                workitem.set_result(result) 
-            end
+            workitem.set_result(result) if result
 
             reply_to_engine(workitem) \
                 if workitem.kind_of? InFlowWorkItem
@@ -196,6 +179,35 @@ module OpenWFE
         end
     end
 
+    #
+    # The NullParticipant never replies, it simply discards the workitems
+    # it receives.
+    #
+    class NullParticipant
+        include LocalParticipant
+
+        #
+        # Simply discards the incoming workitem
+        #
+        def consume (workitem)
+        end
+    end
+
+    #
+    # The NoOperationParticipant immediately replies to the engine upon 
+    # receiving a workitem.
+    #
+    class NoOperationParticipant
+        include LocalParticipant
+
+        #
+        # Simply discards the incoming workitem
+        #
+        def consume (workitem)
+            reply_to_engine workitem
+        end
+    end
+
     #
     # The PrintParticipant will just emit its name to the
     # test tracer if any or to stdout else.

data/lib/openwfe/participants/socketparticipants.rb

@@ -94,6 +94,8 @@ module OpenWFE
             socket.puts
             socket.close_write
 
+            #print "\n__socket.closed? #{socket.closed?}"
+
             reply = fetch_reply(socket)
 
             socket.close
@@ -190,7 +192,7 @@ module OpenWFE
             #
             def encode_workitem (wi)
 
-                sxml = OpenWFE::xml_encode(wi)
+                sxml = OpenWFE::XmlCodec::encode(wi)
 
                 s = "xmlCoder #{sxml.length}\n"
                 s << "\n"