openwferu 0.9.10.653 → 0.9.11

data/README.txt

@@ -1,7 +1,7 @@
 = OpenWFEru, Standard Library Documentation
 
 == Prerequisites
-Ruby 1.8.4 or later
+Ruby 1.8.5 or later
 
 == Supported platforms
 TODO
@@ -32,27 +32,70 @@ These are mostly stolen from the unit tests
 
 Creating an workflow engine instance
 
-  require 'pp'
-  require 'openwferu'
+    require 'rubygems'
+    require 'openwfe/def'
+    require 'openwfe/workitem'
+    require 'openwfe/engine/engine'
+    
+    #
+    # instantiating an engine
+    
+    engine = OpenWFE::Engine.new
+    
+    #
+    # adding some participants
+    
+    engine.register_participant :alice do |workitem|
+        puts "alice got a workitem..."
+        workitem.alice_comment = "this thing looks interesting"
+    end
+    
+    engine.register_participant :bob do |workitem|
+        puts "bob got a workitem..."
+        workitem.bob_comment = "not for me, I prefer VB"
+        workitem.bob_comment2 = "Bob rules"
+    end
+    
+    engine.register_participant :summarize do |workitem|
+        puts 
+        puts "summary of process #{workitem.fei.workflow_instance_id}"
+        workitem.attributes.each do |k, v|
+            next unless k.match ".*_comment$"
+            puts " - #{k} : '#{v}'"
+        end
+    end
+    
+    #
+    # a process definition
+    
+    class TheProcessDefinition0 < OpenWFE::ProcessDefinition
+        sequence do
+            concurrence do
+                participant :alice
+                participant :bob
+            end
+            participant :summarize
+        end
+    end
+    
+    #
+    # launching the process
+    
+    li = OpenWFE::LaunchItem.new(TheProcessDefinition0)
+    
+    li.initial_comment = "please give your impressions about http://ruby-lang.org"
+    
+    fei = engine.launch li
+        #
+        # 'fei' means FlowExpressionId, the fei returned here is the
+        # identifier for the root expression of the newly launched process
+    
+    puts "started process '#{fei.workflow_instance_id}'"
+    
+    engine.wait_for fei
+        #
+        # blocks until the process terminates
 
-  # Create an engine to launch the flow
-  engine = OpenWFEru::Engine.new
-  engine.register_participant('test-.*', OpenWFEru::PrintParticipant.new())
-
-  # Create a flow definition and assign to a new instance
-  flow = '''<process-definition name="equals_0" revision="0">
-    <if>
-        <equals value="a" other-value="a" />
-        <print>${field:__result__}</print>
-    </if>
-  </process-definition>'''
-  li = OpenWFE::LaunchItem.new(flow)
-
-  # Launch the instance
-  engine.launch(li)
-
-  # Examine it
-  pp engine.get_expression_storage
 
 == How to help
 
@@ -69,19 +112,11 @@ tedious by hand.
 
 === Prerequisites
 
-You'll need libxml2-dev in order to compile the native libraries
-for libxml.  Please check your your packaging system for the appropriate
-name.
-
-On Ubuntu you can install libxml2 with:
-  sudo apt-get install libxml2-dev
-
 === Ruby Libraries Install
 
 1. gem install -r rake
 2. gem install -r rote redcloth 
 3. gem install -r tidy    
-4. gem install -r libxml-ruby
 
 == Documentation
 
@@ -90,8 +125,5 @@ http://rubyforge.org/projects/openwferu
 or
 http://openwferu.rubyforge.org
 
-In the meantime the old site hosted at openwfe.org is at:
-http://www.openwfe.org/openwfe-ruby.html
-
-If you're interested in helping :  http://groups.google.com/group/openwferu-users/topics
+The users mailing list is at : http://groups.google.com/group/openwferu-users
 

data/examples/README.txt

@@ -6,3 +6,7 @@ you can run quotereporter.rb with
 
 It will fetch a few quotes for stocks and produce an atom feed file (atom_feed.xml)
 
+If openwferu was installed via rubygems, you can simply do
+
+   ruby quotereporter.rb
+

data/examples/flowtracing.rb

@@ -3,6 +3,8 @@
 # a little script that traces the flow given as input
 #
 
+require 'rubygems'
+
 require 'openwfe/expressions/raw_prog'
 require 'openwfe/tools/flowtracer'
 

data/examples/homeworkreview.rb

@@ -5,6 +5,8 @@
 # an OpenWFEru example
 #
 
+require 'rubygems'
+
 require 'openwfe/engine/engine'
 require 'openwfe/expressions/raw_prog'
 #require 'openwfe/participants/soapparticipants'

data/examples/mano_tracker.rb

@@ -45,6 +45,8 @@
 # for the context of this example
 #
 
+require 'rubygems'
+
 #require 'openwfe/engine/engine'
 require 'openwfe/engine/file_persisted_engine'
 require 'openwfe/expressions/raw_prog'

data/examples/openwferu.rb

@@ -52,5 +52,7 @@ li = OpenWFE::LaunchItem.new(TheProcessDefinition0)
 
 li.initial_comment = "please give your impressions about http://ruby-lang.org"
 
-engine.launch(li)
+fei = engine.launch(li)
+
+engine.wait_for fei
 

data/examples/quotereporter.rb

@@ -3,6 +3,8 @@
 # an OpenWFEru example
 #
 
+require 'rubygems'
+
 require 'openwfe/engine/engine'
 require 'openwfe/expressions/raw_prog'
 require 'openwfe/participants/soapparticipants'

data/examples/scheduler_cron_usage.rb

@@ -3,6 +3,8 @@
 # showing how to use the scheduler
 #
 
+require 'rubygems'
+
 require 'time'
 
 require 'openwfe/util/scheduler'
@@ -34,7 +36,7 @@ end
 
 scheduler.schedule_in("2m10s") do
     p "after 2 minutes and 10 seconds stopping the scheduler and exiting..."
-    scheduler.do_stop
+    scheduler.stop
 end
     #
     # using a regular "at" job to stop the scheduler after 4 minutes

data/examples/scheduler_usage.rb

@@ -3,6 +3,8 @@
 # showing how to use the scheduler
 #
 
+require 'rubygems'
+
 require 'time'
 
 require 'openwfe/util/scheduler'
@@ -35,7 +37,7 @@ end
 
 scheduler.schedule_in("5500") do
     p "after 5500 ms stopping the scheduler and exiting..."
-    scheduler.do_stop
+    scheduler.stop
 end
 
 #scheduler.schedule_at("x" do

data/lib/openwfe/engine/engine.rb

@@ -41,6 +41,7 @@
 # 
 
 require 'logger'
+require 'fileutils'
 
 require 'openwfe/workitem'
 require 'openwfe/rudefinitions'
@@ -70,11 +71,20 @@ module OpenWFE
         # Accepts an optional initial application_context (containing
         # initialization params for services for example).
         #
+        # The engine itself uses one param :logger, used to define
+        # where all the log output for OpenWFEru should go.
+        # By default, this output goes to logs/openwferu.log
+        #
         def initialize (application_context={})
 
             super(S_ENGINE, application_context)
 
-            $OWFE_LOG = Logger.new("engine.log") unless $OWFE_LOG
+            $OWFE_LOG = application_context[:logger]
+
+            unless $OWFE_LOG
+                FileUtils.mkdir("logs") unless File.exist?("logs")
+                $OWFE_LOG = Logger.new("logs/openwferu.log") 
+            end
 
             # build order matters.
             #
@@ -91,8 +101,6 @@ module OpenWFE
 
             build_participant_map()
 
-            #get_expression_pool.reschedule()
-
             linfo { "new() --- engine started --- #{self.object_id}" }
         end
 
@@ -255,10 +263,10 @@ module OpenWFE
 
                 result = if Scheduler.is_cron_string(freq)
 
-                    get_scheduler.schedule(freq, nil, listener, nil)
+                    get_scheduler.schedule(freq, listener)
                 else
 
-                    get_scheduler.schedule_every(freq, listener, nil)
+                    get_scheduler.schedule_every(freq, listener)
                 end
             end
 
@@ -332,6 +340,8 @@ module OpenWFE
                 end
             end
 
+            linfo { "stop() stopped engine '#{@service_name}'" }
+
             nil
         end
 

data/lib/openwfe/expool/expressionpool.rb

@@ -47,6 +47,7 @@ require 'rexml/document'
 require 'openwfe/utils'
 require 'openwfe/service'
 require 'openwfe/logging'
+require 'openwfe/omixins'
 require 'openwfe/rudefinitions'
 require 'openwfe/flowexpressionid'
 require 'openwfe/util/lru'
@@ -132,7 +133,8 @@ module OpenWFE
             MonitorMixin, 
             OwfeServiceLocator, 
             Observable,
-            WorkqueueMixin
+            WorkqueueMixin,
+            FeiMixin
 
         SAFETY_LEVEL = 2
             #
@@ -155,7 +157,7 @@ module OpenWFE
         end
 
         #
-        # Makes sure to call the do_stop() method of the Stoppable mixin
+        # Stops this expression pool (especially its workqueue).
         #
         def stop
             @stopped = true
@@ -186,6 +188,9 @@ module OpenWFE
 
             wfdurl = launchitem.workflow_definition_url
 
+            raise "launchitem.workflow_definition_url not set, cannot launch" \
+                unless wfdurl
+
             definition = if wfdurl.match "^field:"
                 wfdfield = wfdurl[6..-1]
                 launchitem.attributes.delete wfdfield
@@ -717,10 +722,31 @@ module OpenWFE
 
         protected
 
+            #
+            # This method is called by the workqueue when processing
+            # the atomic work operations.
+            #
             def do_process_workelement elt
 
-                message, fei, workitem = elt
-                send message, fei, workitem
+                begin
+
+                    message, fei, workitem = elt
+                    send message, fei, workitem
+
+                rescue Exception => e
+
+                    se = OpenWFE::exception_to_s(e)
+
+                    onotify :error, fei, message, workitem, se
+
+                    fei = extract_fei fei
+
+                    lwarn do
+                        "#{self.service_name} " +
+                        "operation :#{message.to_s} on #{fei.to_s} " +
+                        "failed with\n" + se
+                    end
+                end
             end
 
             #

data/lib/openwfe/expool/journal.rb

@@ -107,11 +107,12 @@ module OpenWFE
             def queue_event (event, *args)
                 synchronize do
 
+                    #ldebug { "queue_event() :#{event}" }
+
                     return if event == :stop
                     return if event == :launch
                     return if event == :reschedule
 
-                    #wfid = args[0].parent_wfid
                     wfid = extract_fei(args[0]).parent_wfid
                         #
                         # maybe args[0] could be a FlowExpression instead
@@ -123,6 +124,8 @@ module OpenWFE
                     bucket = get_bucket(wfid) 
                     bucket << e
 
+                    #ldebug { "queue_event() bucket : #{bucket.object_id}" }
+
                     if event == :terminate
 
                         bucket.flush
@@ -133,11 +136,11 @@ module OpenWFE
                             # 'move' journal to the done/ subdir of journal/
                             #
                             FileUtils.cp(
-                                bucket.get_path,
-                                @donedir + "/" + bucket.get_file_name)
+                                bucket.path,
+                                @donedir + "/" + File.basename(bucket.path))
                         end
 
-                        FileUtils.rm bucket.get_path
+                        FileUtils.rm bucket.path
                     end
                 end
             end
@@ -163,7 +166,7 @@ module OpenWFE
             end
 
             def get_bucket (wfid)
-                @buckets[wfid] ||= Bucket.new(@workdir, wfid)
+                @buckets[wfid] ||= Bucket.new(get_path(wfid))
             end
 
             def serialize_event (event, *args)
@@ -172,18 +175,21 @@ module OpenWFE
                 args.to_yaml
             end
 
+            def get_path (wfid)
+                @workdir + "/" + wfid.to_s + ".journal"
+            end
+
             #
             # for each process instance, there is one bucket holding the
             # events waiting to get written in the journal
             #
             class Bucket
 
-                attr_reader :wfid, :events
+                attr_reader :path, :events
 
-                def initialize (workdir, wfid)
+                def initialize (path)
                     super()
-                    @workdir = workdir
-                    @wfid = wfid
+                    @path = path
                     @events = []
                 end
 
@@ -197,21 +203,13 @@ module OpenWFE
                 alias :length :size
 
                 def flush
-                    File.open(get_path, "w+") do |f|
+                    File.open(@path, "a+") do |f|
                         @events.each do |e|
                             f.puts e
                         end
                     end
                     @events.clear
                 end
-
-                def get_path
-                    @workdir + "/" + get_file_name
-                end
-
-                def get_file_name
-                    @wfid.to_s + ".journal"
-                end
             end
 
     end

data/lib/openwfe/expool/journal_replay.rb

@@ -136,6 +136,60 @@ module OpenWFE
             do_decompose(load_events(file_path), [], nil, 0)
         end
 
+        #
+        # Loads a journal file and return the content as a list of 
+        # events. This method is made available for unit tests, as
+        # a public method it has not much interest.
+        #
+        def load_events (file_path)
+
+            File.open(file_path) do |f|
+                s = YAML.load_stream f
+                s.documents
+            end
+        end
+
+        #
+        # Takes an error event (as stored in the journal) and replays it
+        # (usually you'd have to fix the engine conf before replaying
+        # the error trigger)
+        #
+        # (Make sure to fix the cause of the error before triggering this
+        # method)
+        #
+        def replay_at_error (error_source_event)
+
+            get_expression_pool.queue_work \
+                error_source_event[3], # message (:do_apply for example)
+                error_source_event[2], # fei or exp
+                error_source_event[4]  # workitem
+
+            # 0 is :error and 1 is the date and time of the error
+
+            linfo do
+                fei = extract_fei(error_source_event[2])
+                "replay_at_error() #{error_source_event[3]} #{fei}"
+            end
+        end
+
+        #
+        # Detects the last error that ocurred for a workflow instance
+        # and replays at that point (see replay_at_error).
+        #
+        # (Make sure to fix the cause of the error before triggering this
+        # method)
+        #
+        def replay_at_last_error (wfid)
+
+            events = load_events(get_path(wfid))
+
+            error_event = events.reverse.find do |evt|
+                evt[0] == :error
+            end
+
+            replay_at_error(error_event)
+        end
+
         protected
 
             def do_decompose (events, result, previous_state, offset)
@@ -149,14 +203,6 @@ module OpenWFE
                 do_decompose(events, result, current_state, offset + 1)
             end
 
-            def load_events (file_path)
-
-                File.open(file_path) do |f|
-                    s = YAML.load_stream f
-                    s.documents
-                end
-            end
-
             def extract_state (file, offset)
 
                 events = if file.is_a?(String)
@@ -189,6 +235,7 @@ module OpenWFE
                     next if etype == :apply
                     next if etype == :reply
                     next if etype == :reply_to_parent
+                    next if etype == :error
                     next if seen[fei]
 
                     seen[fei] = true
@@ -208,6 +255,7 @@ module OpenWFE
                     fei = extract_fei e[2]
                     next if etype == :update
                     next if etype == :remove
+                    next if etype == :error
                     #next if etype == :reply_to_parent
                     next if seen[fei]
                     next unless participants[fei]

data/lib/openwfe/expool/wfidgen.rb

@@ -65,14 +65,7 @@ module OpenWFE
 
             load_last()
 
-            begin
-                @last_f = File.open(@last_fn, "w+")
-            rescue Exception => e
-                lwarn do
-                    "new() failed to open #{@last_fn}, continuing anyway...\n"+
-                    OpenWFE::exception_to_s(e)
-                end
-            end
+            ensure_last_f
         end
 
         #
@@ -124,11 +117,26 @@ module OpenWFE
         # file is closed.
         #
         def stop
+            #linfo { "stop() stopping '#{@service_name}'" }
             @last_f.close if @last_f
         end
 
         protected
 
+            def ensure_last_f
+                if (not @last_f) or @last_f.closed?
+                    begin
+                        @last_f = File.open(@last_fn, "w+")
+                    rescue Exception => e
+                        lwarn do
+                            "new() failed to open #{@last_fn}, "+
+                            "continuing anyway...\n"+
+                            OpenWFE::exception_to_s(e)
+                        end
+                    end
+                end
+            end
+
             def now
                 wfid = Time.now.to_f * 1000 * 10
                 wfid.to_i
@@ -136,6 +144,7 @@ module OpenWFE
 
             def save_last
                 return unless @last_f
+                ensure_last_f()
                 @last_f.pos = 0
                 @last_f.puts @last
             end

data/lib/openwfe/expressions/condition.rb

@@ -65,37 +65,19 @@ module OpenWFE
         # This is the method brought to expression classes including this
         # mixin. Easy evaluation of a conditon expressed in an attribute.
         #
-        def eval_condition (attname, workitem)
+        def eval_condition (attname, workitem, nattname=nil)
 
-            #attname = pick_attribute(attname) \
-            #    if attname.is_a?(Array)
+            positive = nil
+            negative = nil
 
-            conditional = lookup_attribute(attname, workitem)
-            rconditional = lookup_attribute("r"+attname.to_s, workitem)
+            positive = do_eval_condition(attname, workitem)
+            negative = do_eval_condition(nattname, workitem) if nattname
 
-            return do_eval(rconditional) \
-                if rconditional and not conditional
+            negative = (not negative) if negative != nil
 
-            return nil \
-                unless conditional
+            return positive if positive != nil
 
-            ldebug { "eval_condition() 0 for  '#{conditional}'" }
-
-            conditional = from_xml conditional
-
-            ldebug { "eval_condition() 1 for  '#{conditional}'" }
-
-            begin
-                return to_boolean(do_eval(conditional))
-            rescue Exception => e
-                # probably needs some quoting...
-            end
-
-            conditional = do_quote(conditional)
-
-            ldebug { "eval_condition() 2 for  '#{conditional}'" }
-
-            to_boolean(do_eval(conditional))
+            negative
         end
 
         #
@@ -122,6 +104,39 @@ module OpenWFE
 
         protected
 
+            def do_eval_condition (attname, workitem)
+
+                #attname = pick_attribute(attname) \
+                #    if attname.is_a?(Array)
+
+                conditional = lookup_attribute(attname, workitem)
+                rconditional = lookup_attribute("r"+attname.to_s, workitem)
+
+                return do_eval(rconditional) \
+                    if rconditional and not conditional
+
+                return nil \
+                    unless conditional
+
+                ldebug { "do_eval_condition() 0 for  '#{conditional}'" }
+
+                conditional = from_xml conditional
+
+                ldebug { "do_eval_condition() 1 for  '#{conditional}'" }
+
+                begin
+                    return to_boolean(do_eval(conditional))
+                rescue Exception => e
+                    # probably needs some quoting...
+                end
+
+                conditional = do_quote(conditional)
+
+                ldebug { "do_eval_condition() 2 for  '#{conditional}'" }
+
+                to_boolean(do_eval(conditional))
+            end
+
         private
 
             #