ruote 0.9.18

data/lib/openwfe/engine/expool_methods.rb

@@ -0,0 +1,172 @@
+#
+#--
+# 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
+#
+
+module OpenWFE
+
+    #
+    # ExpressionPool methods available via the engine.
+    #
+    module ExpoolMethods
+
+        #--
+        # METHODS FROM THE EXPRESSION POOL
+        #
+        # These methods are 'proxy' to method found in the expression pool.
+        # They are made available here for a simpler model.
+        #++
+
+        #
+        # Returns the list of applied expressions belonging to a given
+        # workflow instance.
+        # May be used to determine where a process instance currently is.
+        #
+        # This method returns all the expressions (the stack) a process
+        # went through to reach its current state.
+        #
+        # If the unapplied optional parameter is set to true, all the
+        # expressions (even those not yet applied) that compose the process
+        # instance will be returned.
+        #
+        def process_stack (workflow_instance_id, unapplied=false)
+
+            get_expression_pool.process_stack workflow_instance_id, unapplied
+        end
+        alias :get_process_stack :process_stack
+        alias :get_flow_stack :process_stack
+
+        #
+        # A shortcut for process_stack(wfid, true).representation
+        #
+        # Returns the representation (tree) for the actual version of the
+        # given process instance (returns the tree as running, modifications
+        # included).
+        #
+        def process_representation (workflow_instance_id)
+
+          process_stack(workflow_instance_id, true).representation
+        end
+
+        #
+        # Lists all workflow (process) instances currently in the expool (in
+        # the engine).
+        # This method will return a list of "process-definition" expressions
+        # (i.e. OpenWFE::DefineExpression objects -- each representing the root
+        # element of a flow).
+        #
+        # :wfid ::
+        #     will list only one process,
+        #     <tt>:wfid => '20071208-gipijiwozo'</tt>
+        # :parent_wfid ::
+        #     will list only one process, and its subprocesses,
+        #     <tt>:parent_wfid => '20071208-gipijiwozo'</tt>
+        # :consider_subprocesses ::
+        #     if true, "process-definition" expressions
+        #     of subprocesses will be returned as well.
+        # :wfid_prefix ::
+        #     allows your to query for specific workflow instance
+        #     id prefixes. for example :
+        #     <tt>:wfid_prefix => "200712"</tt>
+        #     for the processes started in December.
+        # :wfname ::
+        #     will return only the process instances who belongs to the given
+        #     workflow [name].
+        # :wfrevision ::
+        #     usued in conjuction with :wfname, returns only the process
+        #     instances of a given workflow revision.
+        #
+        def list_processes (options={})
+
+            get_expression_pool.list_processes options
+        end
+        alias :list_workflows :list_processes
+
+        #
+        # Given any expression of a process, cancels the complete process
+        # instance.
+        #
+        def cancel_process (exp_or_wfid)
+
+            get_expression_pool.cancel_process exp_or_wfid
+        end
+        alias :cancel_flow :cancel_process
+        alias :abort_process :cancel_process
+
+        #
+        # Cancels the given expression (and its children if any)
+        # (warning : advanced method)
+        #
+        # Cancelling the root expression of a process is equivalent to
+        # cancelling the process.
+        #
+        def cancel_expression (exp_or_fei)
+
+            get_expression_pool.cancel_expression exp_or_fei
+        end
+
+        #
+        # Forgets the given expression (make it an orphan)
+        # (warning : advanced method)
+        #
+        def forget_expression (exp_or_fei)
+
+            get_expression_pool.forget exp_or_fei
+        end
+
+        protected
+
+            #
+            # In case of wfid, returns the root expression of the process,
+            # in case of fei, returns the expression itself.
+            #
+            def fetch_exp (fei_or_wfid)
+
+                exp = if fei_or_wfid.is_a?(String)
+
+                    get_expression_pool.fetch_root fei_or_wfid
+
+                else
+
+                    get_expression_pool.fetch_expression fei_or_wfid
+                end
+
+                exp or raise "no expression found for '#{fei_or_wfid.to_s}'"
+            end
+    end
+end
+

data/lib/openwfe/engine/file_persisted_engine.rb

@@ -0,0 +1,105 @@
+#
+#--
+# Copyright (c) 2006-2008, Nicolas Modryzk and 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"
+#
+# Nicolas Modrzyk at openwfe.org
+# John Mettraux at openwfe.org
+#
+
+require 'openwfe/engine/engine'
+require 'openwfe/expool/yamlexpstorage'
+
+
+module OpenWFE
+
+    #
+    # An engine persisted to a tree of yaml files.
+    #
+    # Remember that once you have added the participants to a persisted
+    # engine, you should call its reload method, to reschedule expressions
+    # like 'sleep', 'cron', ... But if you do it before registering the
+    # participants you'll end up with broken processes.
+    #
+    class FilePersistedEngine < Engine
+
+        protected
+
+            #
+            # Overrides the method already found in Engine with a persisted 
+            # expression storage
+            #
+            def build_expression_storage ()
+
+                init_service S_EXPRESSION_STORAGE, YamlFileExpressionStorage
+            end
+
+            #
+            # Uses a file persisted error journal.
+            #
+            def build_error_journal ()
+
+                init_service S_ERROR_JOURNAL, YamlErrorJournal
+            end
+    end
+
+    #
+    # An engine with a cache in front of its file persisted expression storage.
+    #
+    # Remember that once you have added the participants to a persisted
+    # engine, you should call its reload method, to reschedule expressions
+    # like 'sleep', 'cron', ... But if you do it before registering the
+    # participants you'll end up with broken processes.
+    #
+    class CachedFilePersistedEngine < FilePersistedEngine
+
+        protected
+
+            def build_expression_storage ()
+
+                @application_context[:expression_cache_size] ||= 1000
+
+                init_service(
+                    S_EXPRESSION_STORAGE, 
+                    CacheExpressionStorage)
+
+                #init_service(
+                #    S_EXPRESSION_STORAGE + ".1",
+                #    YamlFileExpressionStorage)
+                init_service(
+                    S_EXPRESSION_STORAGE + ".1",
+                    ThreadedYamlFileExpressionStorage)
+            end
+    end
+end

data/lib/openwfe/engine/participant_methods.rb

@@ -0,0 +1,133 @@
+#
+#--
+# 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
+#
+
+module OpenWFE
+
+    #
+    # The methods of the engine about participants (register, unregister,
+    # lookup, ...)
+    #
+    module ParticipantMethods
+
+        #
+        # Registers a participant in this [embedded] engine.
+        # This method is a shortcut to the ParticipantMap method
+        # with the same name.
+        #
+        #    engine.register_participant "user-.*", HashParticipant
+        #
+        # or
+        #
+        #    engine.register_participant "user-.*" do |wi|
+        #        puts "participant '#{wi.participant_name}' received a workitem"
+        #        #
+        #        # and did nothing with it
+        #        # as a block participant implicitely returns the workitem
+        #        # to the engine
+        #    end
+        #
+        # Returns the participant instance.
+        #
+        # The participant parameter can be set to hash like in
+        #
+        #     engine.register_participant(
+        #         "alpha", 
+        #         { :participant => HashParticipant, :position => :first })
+        #
+        # or
+        #
+        #     engine.register_participant("alpha", :position => :first) do
+        #         puts "first !"
+        #     end
+        #
+        # There are some times where you have to position a participant first
+        # (especially with the regex technique).
+        #
+        # see ParticipantMap#register_participant
+        #
+        def register_participant (regex, participant=nil, &block)
+
+            #get_participant_map.register_participant(
+            #    regex, participant, &block)
+
+            params = if participant.class == Hash
+                participant
+            else
+                { :participant => participant }
+            end
+
+            get_participant_map.register_participant regex, params, &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
+
+        #
+        # Removes the first participant matching the given name from the
+        # participant map kept by the engine.
+        #
+        # If 'participant_name' is an integer, will remove the participant
+        # at that position in the participant list.
+        #
+        def unregister_participant (participant_name)
+
+            get_participant_map.unregister_participant participant_name
+        end
+
+        #
+        # Returns the list of participants registered in the engine.
+        # In the resolution order.
+        #
+        # Returns a list of [ regex, participant ] pairs.
+        #
+        def list_participants
+
+            get_participant_map.participants
+        end
+    end
+
+end
+

data/lib/openwfe/engine/status_methods.rb

@@ -0,0 +1,353 @@
+#
+#--
+# 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
+#
+
+module OpenWFE
+
+    #
+    # ProcessStatus represents information about the status of a workflow
+    # process instance.
+    #
+    # The status is mainly a list of expressions and a hash of errors.
+    #
+    # Instances of this class are obtained via Engine.process_status().
+    #
+    class ProcessStatus
+
+        #
+        # the String workflow instance id of the Process.
+        #
+        attr_reader :wfid
+
+        #
+        # The list of the expressions currently active in the process instance.
+        #
+        # For instance, if your process definition is currently in a
+        # concurrence, more than one expressions may be listed here.
+        #
+        attr_reader :expressions
+
+        #
+        # A hash whose values are ProcessError instances, the keys
+        # are FlowExpressionId instances (fei) (identifying the expressions
+        # that are concerned with the error)
+        #
+        attr_reader :errors
+
+        #
+        # The time at which the process got launched.
+        #
+        attr_reader :launch_time
+
+        #
+        # The variables hash as set in the process environment (the process
+        # scope).
+        #
+        attr_reader :variables
+
+        #
+        # Is the process currently in pause ?
+        #
+        attr_accessor :paused
+
+        #
+        # Builds an empty ProcessStatus instance.
+        #
+        def initialize
+
+            @wfid = nil
+            @expressions = []
+            @errors = {}
+            @launch_time = nil
+            @variables = nil
+        end
+
+        #
+        # Returns the workflow definition name for this process.
+        #
+        def wfname
+
+            @expressions.first.fei.wfname
+        end
+
+        alias :workflow_definition_name :wfname
+
+        #
+        # Returns the workflow definition revision for this process.
+        #
+        def wfrevision
+
+            @expressions.first.fei.wfrevision
+        end
+
+        alias :workflow_definition_revision :wfrevision
+
+        #
+        # Returns the count of concurrent branches currently active for
+        # this process. The typical 'sequential only' process will
+        # have a return value of 1 here.
+        #
+        def branches
+
+            @expressions.size
+        end
+
+        #
+        # Returns the tags currently set in this process.
+        #
+        def tags
+
+            return [] unless @variables
+
+            @variables.keys.select do |k|
+                @variables[k].is_a?(OpenWFE::RawExpression::Tag)
+            end
+        end
+
+        #
+        # Returns true if the process is in pause.
+        #
+        def paused?
+
+            #@expressions.first.paused?
+            @paused
+        end
+
+        #
+        # this method is used by Engine.get_process_status() when
+        # it prepares its results.
+        #
+        def << (item)
+
+            if item.kind_of?(FlowExpression)
+                add_expression item
+            else
+                add_error item
+            end
+        end
+
+        #
+        # A String representation, handy for debugging, quick viewing.
+        #
+        def to_s
+
+            s = []
+
+            s << "-- #{self.class.name} --"
+            s << "      wfid :        #{@wfid}"
+            s << "      launch_time : #{launch_time}"
+            s << "      tags :        #{tags.join(", ")}"
+            s << "      errors :      #{@errors.size}"
+            s << "      paused :      #{paused?}"
+
+            s << "      expressions :"
+            @expressions.each do |fexp|
+                s << "         #{fexp.fei.to_s}"
+            end
+
+            s.join "\n"
+        end
+
+        protected
+
+            def add_expression (fexp)
+
+                if fexp.is_a?(Environment)
+                    @variables = fexp.variables if fexp.fei.expid == "0"
+                    return
+                end
+
+                @wfid ||= fexp.fei.parent_wfid
+
+                @launch_time = fexp.apply_time if fexp.fei.expid == '0'
+
+                exps = @expressions
+                @expressions = []
+
+                added = false
+                @expressions = exps.collect do |fe|
+                    if added or fe.fei.wfid != fexp.fei.wfid
+                        fe
+                    else
+                        if OpenWFE::starts_with(fexp.fei.expid, fe.fei.expid)
+                            added = true
+                            fexp
+                        elsif OpenWFE::starts_with(fe.fei.expid, fexp.fei.expid)
+                            added = true
+                            fe
+                        else
+                            fe
+                        end
+                    end
+                end
+                @expressions << fexp unless added
+            end
+
+            def add_error (error)
+
+                @errors[error.fei] = error
+            end
+    end
+
+    #
+    # Renders a nice, terminal oriented, representation of an
+    # Engine.get_process_status() result.
+    #
+    # You usually directly benefit from this when doing
+    #
+    #     puts engine.get_process_status.to_s
+    #
+    def OpenWFE.pretty_print_process_status (ps)
+
+        # TODO : include launch_time and why is process_id so long ?
+
+        s = ""
+        s << "process_id          | name              | rev     | brn | err | paused? \n"
+        s << "--------------------+-------------------+---------+-----+-----+---------\n"
+
+        ps.keys.sort.each do |wfid|
+
+            status = ps[wfid]
+            fexp = status.expressions.first
+            ffei = fexp.fei
+
+            s << "%-19s" % wfid[0, 19]
+            s << " | "
+            s << "%-17s" % ffei.workflow_definition_name[0, 17]
+            s << " | "
+            s << "%-7s" % ffei.workflow_definition_revision[0, 7]
+            s << " | "
+            s << "%3s" % status.expressions.size.to_s[0, 3]
+            s << " | "
+            s << "%3s" % status.errors.size.to_s[0, 3]
+            s << " | "
+            s << "%5s" % status.paused?.to_s
+            s << "\n"
+        end
+        s
+    end
+
+    #
+    # This mixin is only included by the Engine class. It contains all
+    # the methods about ProcessStatus.
+    #
+    module StatusMethods
+
+        #
+        # Returns a hash of ProcessStatus instances. The keys of the hash
+        # are workflow instance ids.
+        #
+        # A ProcessStatus is a description of the state of a process instance.
+        # It enumerates the expressions where the process is currently
+        # located (waiting certainly) and the errors the process currently
+        # has (hopefully none).
+        #
+        def process_statuses (options={})
+
+            options = { :wfid_prefix => options } if options.is_a?(String)
+
+            result = {}
+
+            expressions = get_expression_storage.find_expressions options
+
+            expressions.each do |fexp|
+
+                next unless (fexp.apply_time or fexp.is_a?(Environment))
+
+                next if fexp.fei.wfid == "0" # skip the engine env
+
+                #(result[fexp.fei.parent_wfid] ||= ProcessStatus.new) << fexp
+
+                parent_wfid = fexp.fei.parent_wfid
+
+                ps = result[parent_wfid]
+
+                if not ps
+
+                    ps = ProcessStatus.new
+
+                    ps.paused =
+                        (get_expool.paused_instances[parent_wfid] != nil)
+
+                    result[parent_wfid] = ps
+                end
+
+                ps << fexp
+            end
+
+            result.values.each do |ps|
+                get_error_journal.get_error_log(ps.wfid).each do |error|
+                    ps << error
+                end
+            end
+
+            class << result
+                def to_s
+                    OpenWFE::pretty_print_process_status(self)
+                end
+            end
+
+            result
+        end
+
+        #
+        # list_process_status() will be deprecated at release 1.0.0
+        #
+        alias :list_process_status :process_statuses
+
+        #
+        # Returns the process status of one given process instance.
+        #
+        def process_status (wfid)
+
+            wfid = extract_wfid wfid, true
+
+            process_statuses(:wfid => wfid).values[0]
+        end
+
+        #
+        # Returns true if the process is in pause.
+        #
+        def is_paused? (wfid)
+
+            (get_expression_pool.paused_instances[wfid] != nil)
+        end
+    end
+
+end
+