openwferu 0.9.2 → 0.9.3

data/examples/mano_tracker.rb

@@ -0,0 +1,165 @@
+#
+#--
+# 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
+#
+
+#
+# see
+# http://groups.google.com/group/openwferu-users/browse_frm/thread/81294030fc52cd04
+# for the context of this example
+#
+
+require 'openwfe/engine/engine'
+require 'openwfe/expressions/raw_prog'
+require 'openwfe/participants/storeparticipant'
+
+
+#
+# The process definition
+# (using a programmatic process definition instead of an XML process definition)
+
+class TrackerDefinition < OpenWFE::ProcessDefinition
+    def make
+
+        process_definition :name => "mano_tracker", :revision => "0.2" do
+            _loop do
+                participant "${f:creative}"
+                participant "${f:analyst}"
+
+                _break :if => "${f:done}"
+                    #
+                    # loops until the analyst sets the value of the field
+                    # 'done' to true.
+            end
+                #
+                # 'loop' and 'break' are ruby keywords, they have to be
+                # preceded by an underscore '_' to be used in their 
+                # OpenWFEru sense.
+        end
+    end
+end
+
+#
+# prepare the engine and the participants
+
+ANALYSTS = [ "Mano", "Matt", "Moe" ]
+CREATIVES = [ "Jamie", "Jeff", "John", "Jeremy" ]
+
+#
+# instantiate the engine (a transient one is sufficient for the example)
+
+$engine = OpenWFE::engine.new
+    #
+    # setting up a transient engine
+
+$analyst_stores = {}
+$creative_stores = {}
+    #
+    # gathering the stores for our fictitious organization
+
+def add_stores (names, store_map)
+    names.each do |name|
+        hp = OpenWFE::HashParticipant.new
+        $engine.register_participant(name, hp)
+        store_map[name] = hp
+    end
+end
+
+add_stores(ANALYSTS, $analyst_stores)
+add_stores(CREATIVES, $creative_stores)
+
+#
+# a quick method for launching a tracker process instance
+#
+def launch_tracker (analyst_name, creative_name, title, item_url)
+
+    li = LaunchItem.new(TrackerDefinition)
+        #
+        # preparing a lunchitem ;) around our TrackerDefinition
+
+    li.analyst = analyst_name
+    li.creative = creative_name
+    li.title = title
+    li.item_url = item_url
+        #
+        # filling the workitem with attributes
+
+    $engine.launch(li)
+end
+
+# the system is ready...
+
+
+#
+# (...)
+#
+# Later it can be used as follow
+
+fei = launch_tracker(
+    "Mano", 
+    "Jamie", 
+    "new logo for company", 
+    "http://openwferu.rubyforge.org/images/openwfe-logo.png")
+
+puts "launched tracker process #{fei.workflow_instance_id}"
+
+#
+# the creative Jamie can browse the items he has to treat with :
+
+jamie_store = $analyst_stores["Jamie"]
+
+first_fei = nil
+
+jamie_store.each do |fei, workitem|
+    first_fei = fei unless fei
+    puts " - #{fei.workflow_instance_id} -- #{workitem.title}"
+end
+
+workitem = jamie_store[first_fei]
+
+# play with the workitem and then send it back to the engine
+
+workitem.item_url = "some other url"
+    #
+    # actually just changing the item_url
+
+jamie_store.forward(workitem)
+
+# ...
+

data/examples/scheduler_cron_usage.rb

@@ -0,0 +1,46 @@
+
+#
+# showing how to use the scheduler
+#
+
+require 'time'
+
+require 'openwfe/util/scheduler'
+include OpenWFE
+
+
+def p (msg)
+    t = Time.new
+    puts "#{t.iso8601} -- #{msg}"
+end
+    #
+    # a small method for displaying the time at the beginning
+    # of each output line
+
+
+scheduler = Scheduler.new
+scheduler.start
+    #
+    # create a scheduler instance and start it
+
+p "started scheduler"
+
+i = 0
+
+scheduler.schedule("1-60 * * * *") do
+    p "minute ##{i}"
+    i = i + 1
+end
+
+scheduler.schedule_in("2m10s") do
+    p "after 2 minutes and 10 seconds stopping the scheduler and exiting..."
+    scheduler.do_stop
+end
+    #
+    # using a regular "at" job to stop the scheduler after 4 minutes
+
+scheduler.join
+    #
+    # align the thread of this program to the scheduler thread
+    # i.e. exit program only when scheduler terminates
+

data/examples/scheduler_usage.rb

@@ -0,0 +1,54 @@
+
+#
+# showing how to use the scheduler
+#
+
+require 'time'
+
+require 'openwfe/util/scheduler'
+include OpenWFE
+
+
+def p (msg)
+    t = Time.new
+    puts "#{t.iso8601} -- #{msg}"
+end
+    #
+    # a small method for displaying the time at the beginning
+    # of each output line
+
+
+scheduler = Scheduler.new
+scheduler.start
+    #
+    # create a scheduler instance and start it
+
+p "started scheduler"
+
+scheduler.schedule_in("3s") do
+    p "after 3 seconds"
+end
+
+scheduler.schedule_in("2s") do
+    p "after 2 seconds"
+end
+
+scheduler.schedule_in("5500") do
+    p "after 5500 ms stopping the scheduler and exiting..."
+    scheduler.do_stop
+end
+
+#scheduler.schedule_at("x" do
+#end
+
+#scheduler.schedule_in("3M4h27m") do
+#    p "3 months, 4 hours and 27 minutes... A bit too much"
+#end
+    #
+    # showing what the time strings are capable of
+
+scheduler.join
+    #
+    # align the thread of this program to the scheduler thread
+    # i.e. exit program only when scheduler terminates
+

data/lib/openwfe/contextual.rb

@@ -38,9 +38,14 @@
 #
 # John Mettraux at openwfe.org
 # Nicolas Modrzyk at openwfe.org
+#
 
 module OpenWFE
 
+    #
+    # This mixin helds an application_context field and provides a
+    # lookup method for digging into that context.
+    #
     module Contextual
 
         attr_accessor :application_context
@@ -61,8 +66,9 @@ module OpenWFE
         end
         
         #
-        # use reflection to instanciate the new service,and 
+        # Use reflection to instantiate the new service,and 
         # add it to the application context
+        #
         def init_service (service_name, service_class)
             @application_context[service_name] = \
                 service_class.new(service_name,@application_context)

data/lib/openwfe/engine/engine.rb

@@ -40,6 +40,8 @@
 # Nicolas Modrzyk at openwfe.org
 # 
 
+require 'logger'
+
 require 'openwfe/workitem'
 require 'openwfe/rudefinitions'
 require 'openwfe/service'
@@ -65,44 +67,54 @@ module OpenWFE
 
             @application_context[@service_name] = self
 
+            build_scheduler()
+
             build_expression_map()
-            build_expression_pool()
             build_expression_storage()
+            build_expression_pool()
+
             build_participant_map()
-            build_scheduler()
 
-            init_default_logging('engine.log')
+            $OWFE_LOG = Logger.new("engine.log") unless $LOG
         end
 
         #
         # Launches a [business] process.
-        # The 'object' param may contain either a LaunchItem instance, 
+        # The 'launch_object' param may contain either a LaunchItem instance, 
         # either a String containing the URL of the process definition
         # to launch (with an empty LaunchItem created on the fly).
         #
-        def launch (object)
+        def launch (launch_object)
 
             launchitem = nil
 
-            #ldebug { "launch() param is #{object.class}" }
-
-            if object.kind_of? OpenWFE::LaunchItem
-                launchitem = object
-            #elsif object.kind_of? REXML::Element
-                #nada
-            elsif object.kind_of? String
+            if launch_object.kind_of? OpenWFE::LaunchItem
+                launchitem = launch_object
+            elsif launch_object.kind_of? Class
+                launchitem = LaunchItem.new(launch_object)
+            elsif launch_object.kind_of? String
                 launchitem = OpenWFE::LaunchItem.new
-                if object[0] == '<'
+                if launch_object[0] == '<'
                     launchitem.workflowDefinitionUrl = "field:__definition"
-                    launchitem['definition'] = object
+                    launchitem['definition'] = launch_object
                 else
-                    launchitem.workflowDefinitionUrl = object
+                    launchitem.workflowDefinitionUrl = launch_object
                 end
             end
 
             get_expression_pool.launch(launchitem)
         end
 
+        #
+        # This method is used to feed a workitem back to the engine (after
+        # it got sent to a worklist or wherever by a participant).
+        # Participant implementations themselves do call this method usually.
+        #
+        def reply (workitem)
+
+            get_expression_pool.reply(workitem.last_expression_id, workitem)
+        end
+
         #
         # Registers a participant in this [embedded] engine.
         # This method is a shortcut to the ParticipantMap method
@@ -113,6 +125,37 @@ module OpenWFE
             get_participant_map.register_participant(regex, participant, &block)
         end
 
+        #
+        # Given a participant name, returns the participant in charge
+        # of handling workitems for that name.
+        # May be useful in some embedded contexts.
+        #
+        def get_participant (participant_name)
+
+            get_participant_map.lookup_participant(participant_name)
+        end
+
+        #
+        # Stopping the engine will stop all the services in the
+        # application context.
+        #
+        def stop
+
+            linfo { "stop() stopping engine '#{@service_name}'" }
+
+            @application_context.each do |name, service|
+                next if name == self.service_name
+                #service.stop if service.respond_to? :stop
+                if service.kind_of? ServiceMixin
+                    service.stop
+                    linfo do 
+                        "stop() stopped service '#{service.service_name}' "+
+                        "(#{service.class})"
+                    end
+                end
+            end
+        end
+
         protected
 
             #

data/lib/openwfe/expool/expressionpool.rb

@@ -49,6 +49,7 @@ require 'openwfe/service'
 require 'openwfe/logging'
 require 'openwfe/rudefinitions'
 require 'openwfe/flowexpressionid'
+require 'openwfe/util/stoppable'
 require 'openwfe/util/lru_cache'
 require 'openwfe/expressions/environment'
 require 'openwfe/expressions/raw_xml'
@@ -120,16 +121,30 @@ module OpenWFE
     # It relies on an expression storage for actual persistence of the
     # expressions.
     #
-    class ExpressionPool < Service
-        include MonitorMixin, OwfeServiceLocator
+    class ExpressionPool
+        include ServiceMixin, MonitorMixin, OwfeServiceLocator, Stoppable
 
         @@last_given_instance_id = -1
             #
             # storing at class level the last workflow instance id given
 
-        def initialize (serviceName, applicationContext)
-            super(serviceName, applicationContext)
+        def initialize (service_name, application_context)
+
+            super()
+
+            service_init(service_name, application_context)
+
             @monitors = MonitorProvider.new(application_context)
+
+            reschedule_a_bit_later
+        end
+
+        #
+        # Makes sure to call the do_stop() method of the Stoppable mixin
+        #
+        def stop
+            # would an alias be better ?
+            do_stop
         end
 
         #
@@ -151,17 +166,28 @@ module OpenWFE
             wi = build_workitem(launchitem)
 
             rawExpression.apply(wi)
+
+            return wi.flow_expression_id
         end
 
         #
         # launches a subprocess
         #
         def launch_template \
-            (requesting_expression, template_fei, workitem, params=nil)
+            (requesting_expression, template, workitem, params=nil)
+
+            #ldebug { "launch_template() of class #{template.class}" }
 
-            ldebug { "launch() request for #{template_fei.to_debug_s}" }
+            rawexp = nil
+
+            if template.kind_of? FlowExpressionId
+                rawexp, fei = fetch(template)
+            else # template is of kind RawExpression
+                rawexp = template
+            end
+
+            ldebug { "launch_template() request for #{rawexp.fei.to_debug_s}" }
 
-            rawexp, fei = fetch(template_fei)
             rawexp = rawexp.dup()
             rawexp.fei = rawexp.fei.dup()
 
@@ -178,6 +204,14 @@ module OpenWFE
                 rawexp.fei.workflow_instance_id = \
                     "#{requesting_expression.fei.workflow_instance_id}.0"
             end
+
+            #ldebug do
+            #    p = ""
+            #    p = rawexp.parent_id.to_debug_s if rawexp.parent_id
+            #    "launch_template()\n"+
+            #    "    rawexp.fei is #{rawexp.fei.to_debug_s}\n"+
+            #    "    rawexp.parent_id is #{p}"
+            #end
             
             #ldebug do
             #    "launch_template() spawning wfid " +
@@ -193,6 +227,8 @@ module OpenWFE
             rawexp.store_itself()
 
             rawexp.apply(workitem)
+
+            return workitem.flow_expression_id
         end
 
         #
@@ -270,7 +306,13 @@ module OpenWFE
 
             workitem.last_expression_id = fei
 
-            remove(exp, workitem)
+            #remove(exp, workitem)
+            remove(exp)
+
+            #
+            # remove all the children of the expression
+
+            exp.clean_children()
 
             if not exp.parent_id
                 ldebug do 
@@ -325,6 +367,7 @@ module OpenWFE
         # 
         def fetch (exp)
             synchronize do
+
                 fei = exp
                 if exp.kind_of? FlowExpression
                     fei = exp.fei 
@@ -333,6 +376,9 @@ module OpenWFE
                         "Cannot fetch expression with key : "+
                         "'#{fei}' (#{fei.class})"
                 end
+
+                ldebug { "fetch() for  #{fei.to_debug_s}" }
+
                 return get_expression_storage()[fei], fei
             end
         end
@@ -360,8 +406,6 @@ module OpenWFE
                     ee.store_itself()
                 end
 
-                ldebug { "fetch_engine_environment() stored new ee" }
-                
                 return ee
             end
         end
@@ -370,7 +414,7 @@ module OpenWFE
         # Removes a flow expression from the pool
         # (This method is mainly called from the pool itself)
         #
-        def remove (exp, workitem=nil)
+        def remove (exp)
 
             exp, fei = fetch(exp)
 
@@ -382,8 +426,8 @@ module OpenWFE
 
                 @monitors.delete(fei)
 
-                #get_expression_storage().delete(fei)
-                get_expression_storage().remove(fei, workitem)
+                #get_expression_storage().remove(fei, workitem)
+                get_expression_storage().delete(fei)
 
                 if exp.owns_its_environment?
                     remove_environment(exp.environment_id)
@@ -392,6 +436,44 @@ module OpenWFE
             end
         end
 
+        #
+        # This method is called at each expool (engine) [re]start.
+        # It roams through the previously saved (persisted) expressions
+        # to reschedule ones like 'sleep' or 'cron'.
+        #
+        def reschedule
+            synchronize do
+
+                #if is_stopped?
+                #    linfo { "reschedule() skipped as expool is stopped" }
+                #    return
+                #end
+                #if get_scheduler.is_stopped?
+                #    linfo do 
+                #        "reschedule() skipped as scheduler "+
+                #        "#{get_scheduler.object_id} is stopped"
+                #    end
+                #    return
+                #end
+
+                ldebug { "reschedule() initiating..." }
+
+                get_expression_storage.each_of_kind(Schedulable) do |fe|
+
+                    ldebug { "reschedule() for  #{fe.fei.to_debug_s}..." }
+
+                    fe.reschedule(get_scheduler)
+                end
+
+                ldebug { "reschedule() done." }
+            end
+        end
+
+        #
+        # Returns the unique engine_environment FlowExpressionId instance.
+        # There is only one such environment in an engine, hence this 
+        # 'singleton' method.
+        #
         def engine_environment_id ()
             synchronize do
                 return @eei if @eei
@@ -411,6 +493,25 @@ module OpenWFE
 
         protected
 
+            def reschedule_a_bit_later
+                Thread.new do
+                    #
+                    # Just leaving some time for the initialize() to finish
+                    # and let the expression pool get registered in
+                    # the application context
+                    #
+                    begin
+                        sleep(0.001)
+                        reschedule()
+                    rescue
+                        lwarn do 
+                            "reschedule() failed\n"+ 
+                            OpenWFE::exception_to_s($!)
+                        end
+                    end
+                end
+            end
+
             def evaluate_definition (raw_definition, workitem)
                 expression = raw_definition.instantiate(workitem)
             end
@@ -418,7 +519,7 @@ module OpenWFE
             def remove_environment (environment_id)
                 env, fei = fetch(environment_id)
                 env.unbind()
-                get_expression_storage().remove(environment_id, nil)
+                get_expression_storage().delete(environment_id)
             end
 
             def build_workitem (launchitem)
@@ -498,6 +599,7 @@ module OpenWFE
             end
 
             def new_workflow_instance_id ()
+
                 synchronize do
                     wfid = OpenWFE::current_time_millis()
                     wfid = wfid + 1 if wfid == @@last_given_instance_id