openwferu 0.9.11 → 0.9.12

data/lib/openwfe/expool/errorjournal.rb

@@ -0,0 +1,379 @@
+#
+#--
+# 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$
+#
+
+#
+# "made in Japan"
+#
+# John Mettraux at openwfe.org
+#
+
+require 'find'
+require 'fileutils'
+
+require 'openwfe/service'
+require 'openwfe/omixins'
+
+
+module OpenWFE
+
+    #
+    # Encapsulating process error information.
+    #
+    # Instances of this class may be used to replay_at_error
+    #
+    class ProcessError
+
+        #
+        # When did the error occur.
+        #
+        attr_reader :date
+
+        #
+        # The FlowExpressionId instance uniquely pointing at the expression
+        # which 'failed'.
+        #
+        attr_reader :fei 
+
+        #
+        # Generally something like :apply or :reply
+        #
+        attr_reader :message 
+
+        #
+        # The workitem accompanying the message (apply(workitem) / 
+        # reply (workitem)).
+        #
+        attr_reader :workitem 
+
+        #
+        # The String stack trace of the error.
+        #
+        attr_reader :stacktrace
+
+        def initialize (*args)
+
+            @date = Time.new
+            @fei, @message, @workitem, @stacktrace = args
+        end
+
+        #
+        # Returns the parent workflow instance id (process id) of this
+        # ProcessError instance.
+        #
+        def wfid
+            @fei.parent_wfid
+        end
+
+        alias :parent_wfid :wfid
+
+        #
+        # Produces a human readable version of the information in the
+        # ProcessError instance.
+        #
+        def to_s
+            s = ""
+            s << "-- #{self.class.name} --\n"
+            s << "     date :       #{@date}\n"
+            s << "     fei :        #{@fei}\n"
+            s << "     message :    #{@message}\n"
+            s << "     workitem :   ...\n"
+            s << "     stacktrace : #{@stacktrace[0, 80]}\n"
+            s
+        end
+    end
+
+    #
+    # This is a base class for all error journal, don't instantiate,
+    # work rather with InMemoryErrorJournal (only for testing envs though),
+    # or YamlErrorJournal.
+    #
+    class ErrorJournal < Service
+        include OwfeServiceLocator
+        include FeiMixin
+
+        def initialize (service_name, application_context)
+
+            super
+
+            get_expression_pool.add_observer(:error) do |event, *args|
+                #
+                # logs each error occuring in the expression pool
+                
+                record_error(ProcessError.new(*args))
+            end
+        end
+
+        #
+        # Returns true if the given wfid (or fei) (process instance id)
+        # has had errors.
+        #
+        def has_errors? (wfid)
+
+            get_error_log(wfid).size > 0
+        end
+
+        #
+        # Replays the given process instance (wfid or fei) at its last
+        # recorded error.
+        #
+        # There is an optional 'offset' parameter. Its default value is '0'.
+        # Which means that the replay will occur at the last error.
+        # 
+        #     ejournal.replay_at_last_error('20070630-hiwakuzara', 1)
+        #
+        # Will replay a given process instance at its 1 to last error.
+        #
+        def replay_at_last_error (wfid, offset=0)
+
+            wfid = to_wfid(wfid)
+
+            log = get_error_log(wfid)
+
+            index = (-1 - offset)
+
+            error = log[index]
+
+            raise "no error for process '#{wfid}' at offset #{offset}" \
+                unless error
+
+            replay_at_error error
+        end
+
+        #
+        # Replays at a specific error (fetched with read_error_log()).
+        #
+        def replay_at_error (error)
+
+            get_expression_pool.queue_work(
+                error.message,
+                error.fei,
+                error.workitem)
+        end
+
+        #
+        # A utility method : given a list of errors, will make sure that for 
+        # each flow expression only one expression (the most recent) will get 
+        # listed.
+        # Returns a list of errors, from the oldest to the most recent.
+        #
+        # Could be useful when considering a process where multiple replay
+        # attempts failed.
+        #
+        def ErrorJournal.reduce_error_list (errors)
+
+            h = {}
+
+            errors.each do |e|
+                h[e.fei] = e
+                    #
+                    # last errors do override previous errors for the
+                    # same fei
+            end
+
+            h.values.sort do |error_a, error_b|
+                error_a.date <=> error_b.date
+            end
+        end
+    end
+
+    #
+    # Stores all the errors in a hash... For testing purposes only, like
+    # the InMemoryExpressionStorage.
+    #
+    class InMemoryErrorJournal < ErrorJournal
+
+        def initialize (service_name, application_context)
+
+            super
+
+            @per_processes = {}
+        end
+
+        #
+        # Returns a list (older first) of the errors for a process
+        # instance identified by its fei or wfid.
+        #
+        # Will return an empty list if there a no errors for the process
+        # instances.
+        #
+        def get_error_log (wfid)
+
+            wfid = to_wfid(wfid)
+            @per_processes[wfid] or []
+        end
+
+        #
+        # Removes the error log for a process instance.
+        #
+        def remove_error_log (wfid)
+
+            wfid = to_wfid(wfid)
+            @per_processes.delete(wfid)
+        end
+
+        #
+        # Reads all the error logs currently stored.
+        # Returns a hash wfid --> error list.
+        #
+        def get_error_logs
+
+            @per_processes
+        end
+
+        protected
+
+            def record_error (error)
+
+                (@per_processes[error.wfid] ||= []) << error
+                    # not that unreadable after all...
+            end
+    end
+    
+    #
+    # A Journal that only keep track of error in process execution.
+    #
+    class YamlErrorJournal < ErrorJournal
+
+        attr_reader :workdir
+
+        def initialize (service_name, application_context)
+
+            require 'openwfe/storage/yamlextras'
+
+            super
+
+            @workdir = OpenWFE::get_work_directory + "/ejournal"
+
+            FileUtils.makedirs(@workdir) unless File.exist?(@workdir)
+        end
+
+        #
+        # Returns a list (older first) of the errors for a process
+        # instance identified by its fei or wfid.
+        #
+        # Will return an empty list if there a no errors for the process
+        # instances.
+        #
+        def get_error_log (wfid)
+
+            path = get_path(wfid)
+
+            return [] unless File.exist?(path)
+
+            read_error_log_from path
+        end
+
+        #
+        # Copies the error log of a process instance to a give path (and
+        # filename).
+        #
+        # Could be useful when one has to perform replay operations and wants
+        # to keep a copy of the original error[s].
+        #
+        def copy_error_log_to (wfid, path)
+
+            original_path = get_path wfid
+            FileUtils.copy_file original_path, path
+        end
+
+        #
+        # Reads an error log from a specific file (possibly as copied over
+        # via copy_error_log_to()).
+        #
+        def read_error_log_from (path)
+
+            raise "no error log file at #{path}" unless File.exist?(path)
+
+            File.open(path) do |f|
+                s = YAML.load_stream f
+                s.documents
+            end
+        end
+
+        #
+        # Removes the error log of a specific process instance.
+        # Could be a good idea after a succesful replay operation.
+        #
+        # 'wfid' may be either a workflow instance id (String) either
+        # a FlowExpressionId instance.
+        #
+        def remove_error_log (wfid)
+
+            File.delete(get_path(wfid))
+        end
+
+        #
+        # Reads all the error logs currently stored.
+        # Returns a hash wfid --> error list.
+        #
+        def get_error_logs
+
+            result = {}
+
+            Find.find(@workdir) do |path|
+                next unless path.endswith(".ejournal")
+                wfid = path[0..-9]
+                log = read_error_log wfid
+                result[wfid] = log
+            end
+
+            result
+        end
+
+        protected
+
+            #
+            # logs the error as a yaml string in an error log file
+            # (there is one error log file per workflow instance).
+            #
+            def record_error (error)
+
+                path = get_path error.fei
+
+                File.open(path, "a+") do |f|
+                    f.puts error.to_yaml
+                end
+            end
+
+            #
+            # Returns the path to the error log file of a specific process
+            # instance.
+            #
+            def get_path (fei_or_wfid)
+
+                @workdir + "/" + to_wfid(fei_or_wfid) + ".ejournal"
+            end
+    end
+end

data/lib/openwfe/expool/expressionpool.rb

@@ -64,44 +64,6 @@ include OpenWFE
 
 module OpenWFE
 
-    #
-    # a small help class for storing monitors provided on demand 
-    # to expressions that need them
-    #
-    class MonitorProvider
-        include MonitorMixin, Logging
-
-        MAX_MONITORS = 10000
-
-        def initialize (application_context=nil)
-            super()
-            @application_context = application_context
-            @monitors = LruHash.new(MAX_MONITORS)
-        end
-
-        def [] (key)
-            synchronize do
-                #ldebug { "[] caller :\n" + OpenWFE::caller_to_s(8) }
-                mon = @monitors[key]
-                if not mon
-                    #ldebug { "[] creating new Monitor for  #{key}" }
-                    mon = Monitor.new
-                    @monitors[key] = mon
-                else
-                    #ldebug { "[] already had Monitor for  #{key}" }
-                end
-                return mon
-            end
-        end
-
-        def delete (key)
-            synchronize do
-                #ldebug { "delete() removing Monitor for  #{key}" }
-                @monitors.delete(key)
-            end
-        end
-    end
-
     GONE = "gone"
 
     #
@@ -383,18 +345,40 @@ module OpenWFE
             inflowitem
         end
 
+        #
+        # Cancels the given expression and makes sure to resume the flow
+        # if the expression or one of its children were active.
+        #
+        # If the cancelled branch was not active, this method will take
+        # care of removing the cancelled expression from the parent
+        # expression.
+        #
+        def cancel_expression (exp)
+
+            exp = fetch_expression(exp)
+
+            wi = cancel(exp)
+
+            if wi
+                reply_to_parent(exp, wi, false)
+            else
+                parent_exp = fetch_expression(exp.parent_id)
+                parent_exp.remove_child(exp.fei) if parent_exp
+            end
+        end
+
         #
         # Given any expression of a process, cancels the complete process
         # instance.
         #
-        def cancel_flow (exp_or_wfid)
+        def cancel_process (exp_or_wfid)
 
-            #ldebug { "cancel_flow() from  #{exp_or_wfid}" }
+            ldebug { "cancel_process() from  #{exp_or_wfid}" }
 
             root = fetch_root(exp_or_wfid)
             cancel(root)
         end
-        alias :cancel_process :cancel_flow
+        alias :cancel_flow :cancel_process
 
         #
         # Forgets the given expression (makes sure to substitute its
@@ -515,9 +499,9 @@ module OpenWFE
 
                 #ldebug { "fetch() exp is of kind #{exp.class}" }
 
-                if exp.kind_of? FlowExpression
+                if exp.kind_of?(FlowExpression)
                     fei = exp.fei 
-                elsif not exp.kind_of? FlowExpressionId
+                elsif not exp.kind_of?(FlowExpressionId)
                     raise \
                         "Cannot fetch expression with key : "+
                         "'#{fei}' (#{fei.class})"
@@ -525,7 +509,7 @@ module OpenWFE
 
                 #ldebug { "fetch() for  #{fei.to_debug_s}" }
 
-                return get_expression_storage()[fei], fei
+                [ get_expression_storage()[fei], fei ]
             end
         end
 
@@ -536,6 +520,7 @@ module OpenWFE
         # has to be reloaded.
         #
         def fetch_expression (exp)
+
             exp, _fei = fetch(exp)
             exp
         end
@@ -551,6 +536,8 @@ module OpenWFE
 
             exp = fetch_expression(exp_or_wfid)
 
+            raise "did not find root for expression #{exp_or_wfid}" unless exp
+
             return exp unless exp.parent_id
 
             fetch_root(fetch_expression(exp.parent_id))
@@ -634,7 +621,9 @@ module OpenWFE
         #
         def engine_environment_id ()
             synchronize do
+
                 return @eei if @eei
+
                 @eei = FlowExpressionId.new
                 @eei.owfe_version = OPENWFERU_VERSION
                 @eei.engine_id = get_engine.service_name
@@ -645,7 +634,7 @@ module OpenWFE
                 @eei.workflow_instance_id = '0'
                 @eei.expression_name = EN_ENVIRONMENT
                 @eei.expression_id = '0'
-                return @eei
+                @eei
             end
         end
 
@@ -653,11 +642,13 @@ module OpenWFE
         # Returns the list of applied expressions belonging to a given
         # workflow instance.
         #
-        def get_flow_position (wfid)
+        def get_process_stack (wfid)
 
             raise "please provide a non-nil workflow instance id" \
                 unless wfid
 
+            wfid = to_wfid wfid
+
             result = []
 
             get_expression_storage.real_each do |fei, fexp|
@@ -666,21 +657,21 @@ module OpenWFE
                 next if fexp.kind_of?(RawExpression)
                 next unless fexp.apply_time
 
-                pi = fei.parent_wfid
-
-                next if pi != wfid
+                next if fei.parent_wfid != wfid
 
                 result << fexp
             end
 
             ldebug do 
-                "get_flow_position() " +
+                "process_stack() " +
                 "found #{result.size} exps for flow #{wfid}" 
             end
 
             result
         end
 
+        alias :get_flow_stack :get_process_stack
+
         #
         # Lists all workflows (processes) currently in the expool (in
         # the engine).
@@ -693,31 +684,32 @@ module OpenWFE
         # "wfid_prefix" allows your to query for specific workflow instance
         # id prefixes.
         #
-        def list_workflows (consider_subprocesses=false, wfid_prefix=nil)
+        def list_processes (consider_subprocesses=false, wfid_prefix=nil)
 
             result = []
 
-            get_expression_storage.real_each do |fei, fexp|
+            # collect() would look better
+
+            get_expression_storage.real_each(wfid_prefix) do |fei, fexp|
 
                 next unless fexp.is_a? DefineExpression
 
                 next if not consider_subprocesses and fei.wfid.index(".")
 
-                next unless fei.wfid.match("^#{wfid_prefix}") if wfid_prefix
+                #next unless fei.wfid.match("^#{wfid_prefix}") if wfid_prefix
 
                 result << fexp
             end
 
             result
         end
-        alias :list_processes :list_workflows
 
         #
         # Returns the first expression found with the given wfid.
         #
         def fetch_expression_with_wfid (wfid)
 
-            list_workflows(false, wfid)[0]
+            list_processes(false, wfid)[0]
         end
 
         protected
@@ -955,7 +947,44 @@ module OpenWFE
                 procdef.raw_expression_class.new(
                     fei, nil, nil, @application_context, procdef)
             end
+    end
+
+    #
+    # a small help class for storing monitors provided on demand 
+    # to expressions that need them
+    #
+    class MonitorProvider
+        include MonitorMixin, Logging
 
+        MAX_MONITORS = 10000
+
+        def initialize (application_context=nil)
+            super()
+            @application_context = application_context
+            @monitors = LruHash.new(MAX_MONITORS)
+        end
+
+        def [] (key)
+            synchronize do
+                #ldebug { "[] caller :\n" + OpenWFE::caller_to_s(8) }
+                mon = @monitors[key]
+                if not mon
+                    #ldebug { "[] creating new Monitor for  #{key}" }
+                    mon = Monitor.new
+                    @monitors[key] = mon
+                else
+                    #ldebug { "[] already had Monitor for  #{key}" }
+                end
+                return mon
+            end
+        end
+
+        def delete (key)
+            synchronize do
+                #ldebug { "delete() removing Monitor for  #{key}" }
+                @monitors.delete(key)
+            end
+        end
     end
 
 end