ruote 0.9.19 → 0.9.20

data/lib/openwfe/engine/expool_methods.rb

@@ -1,41 +1,27 @@
-#
 #--
-# 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:
+# Copyright (c) 2006-2009, John Mettraux, jmettraux@gmail.com
 #
-# . Redistributions of source code must retain the above copyright notice, this
-#   list of conditions and the following disclaimer.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# . 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.
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# . 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.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
 #
-# 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.
 #++
-#
 
-#
-# "made in Japan"
-#
-# John Mettraux at openwfe.org
-#
 
 module OpenWFE
 
@@ -51,78 +37,13 @@ module OpenWFE
     # 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
+      get_expression_pool.cancel_process(exp_or_wfid)
     end
     alias :cancel_flow :cancel_process
     alias :abort_process :cancel_process
@@ -136,16 +57,7 @@ module OpenWFE
     #
     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
+      get_expression_pool.cancel_expression(exp_or_fei)
     end
 
     #
@@ -153,7 +65,7 @@ module OpenWFE
     #
     def pause_process (wfid)
 
-      get_expression_pool.pause_process wfid
+      get_expression_pool.pause_process(wfid)
     end
 
     #
@@ -163,7 +75,7 @@ module OpenWFE
     #
     def resume_process (wfid)
 
-      get_expression_pool.resume_process wfid
+      get_expression_pool.resume_process(wfid)
     end
 
     #
@@ -174,28 +86,28 @@ module OpenWFE
     #
     def replay_at_error (error)
 
-      get_error_journal.replay_at_error error
+      get_error_journal.replay_at_error(error)
     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)
+    #
+    # 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)
 
-          get_expression_pool.fetch_root fei_or_wfid
+      exp = if fei_or_wfid.is_a?(String)
 
-        else
+        get_expression_pool.fetch_root(fei_or_wfid)
 
-          get_expression_pool.fetch_expression fei_or_wfid
-        end
+      else
 
-        exp or raise "no expression found for '#{fei_or_wfid.to_s}'"
+        get_expression_pool.fetch_expression(fei_or_wfid)
       end
+
+      exp || raise("no expression found for '#{fei_or_wfid.to_s}'")
+    end
   end
 end
 

data/lib/openwfe/engine/file_persisted_engine.rb

@@ -1,45 +1,31 @@
-#
 #--
-# 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:
+# Copyright (c) 2006-2009, Nicolas Modryzk and John Mettraux, OpenWFE.org
 #
-# . Redistributions of source code must retain the above copyright notice, this
-#   list of conditions and the following disclaimer.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# . 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.
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# . 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.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
 #
-# 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.
 #++
-#
 
-#
-# "made in Japan"
-#
-# Nicolas Modrzyk at openwfe.org
-# John Mettraux at openwfe.org
-#
 
 require 'openwfe/engine/engine'
-require 'openwfe/expool/yamlexpstorage'
+require 'openwfe/expool/fs_expstorage'
+require 'openwfe/expool/yaml_errorjournal'
 
 
 module OpenWFE
@@ -52,26 +38,28 @@ module OpenWFE
   # like 'sleep', 'cron', ... But if you do it before registering the
   # participants you'll end up with broken processes.
   #
+  # DEPRECATED, use FsEngine instead
+  #
   class FilePersistedEngine < Engine
 
     protected
 
-      #
-      # Overrides the method already found in Engine with a persisted
-      # expression storage
-      #
-      def build_expression_storage
+    #
+    # Overrides the method already found in Engine with a persisted
+    # expression storage
+    #
+    def build_expression_storage
 
-        init_service :s_expression_storage, YamlFileExpressionStorage
-      end
+      init_storage(YamlFileExpressionStorage)
+    end
 
-      #
-      # Uses a file persisted error journal.
-      #
-      def build_error_journal
+    #
+    # Uses a file persisted error journal.
+    #
+    def build_error_journal
 
-        init_service :s_error_journal, YamlErrorJournal
-      end
+      init_service(:s_error_journal, YamlErrorJournal)
+    end
   end
 
   #
@@ -82,24 +70,15 @@ module OpenWFE
   # like 'sleep', 'cron', ... But if you do it before registering the
   # participants you'll end up with broken processes.
   #
+  # DEPRECATED, use FsEngine instead
+  #
   class CachedFilePersistedEngine < FilePersistedEngine
 
     protected
 
-      def build_expression_storage
-
-        @application_context[:expression_cache_size] ||= 1000
-
-        init_service(
-          :s_expression_storage,
-          CacheExpressionStorage)
+    def build_expression_storage
 
-        #init_service(
-        #  :s_expression_storage__1,
-        #  YamlFileExpressionStorage)
-        init_service(
-          :s_expression_storage__1,
-          ThreadedYamlFileExpressionStorage)
-      end
+      init_storage(ThreadedYamlFileExpressionStorage)
+    end
   end
 end

data/lib/openwfe/engine/fs_engine.rb

@@ -0,0 +1,54 @@
+#--
+# Copyright (c) 2009, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Japan.
+#++
+
+
+require 'openwfe/engine/engine'
+require 'openwfe/expool/fs_expstorage'
+require 'openwfe/expool/yaml_errorjournal'
+
+
+module OpenWFE
+
+  #
+  # An engine persisted to the file system (work/expool/ by default).
+  #
+  class FsPersistedEngine < Engine
+
+    protected
+
+    #
+    # Overrides the method already found in Engine with a persisted
+    # expression storage
+    #
+    def build_expression_storage
+
+      init_storage(FsExpressionStorage)
+    end
+
+    def build_error_journal
+
+      init_service(:s_error_journal, YamlErrorJournal)
+    end
+  end
+end

data/lib/openwfe/engine/launch_methods.rb

@@ -0,0 +1,245 @@
+#--
+# Copyright (c) 2006-2009, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Japan.
+#++
+
+
+module OpenWFE
+
+  #
+  # The methods for ordering an engine to read a process definition and
+  # turn it into a process instance (launching).
+  #
+  module LaunchMethods
+
+    #
+    # Launches a [business] process.
+    # 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).
+    #
+    # The launch object can also be a String containing the XML process
+    # definition or directly a class extending OpenWFE::ProcessDefinition
+    # (Ruby process definition).
+    #
+    # Returns the FlowExpressionId instance of the expression at the
+    # root of the newly launched process.
+    #
+    # Options for scheduled launches like :at, :in and :cron are accepted
+    # via the 'options' optional parameter.
+    # For example :
+    #
+    #   engine.launch(launch_item)
+    #     # will launch immediately
+    #
+    #   engine.launch(launch_item, :in => "1d20m")
+    #     # will launch in one day and twenty minutes
+    #
+    #   engine.launch(launch_item, :at => "Tue Sep 11 20:23:02 +0900 2007")
+    #     # will launch at that point in time
+    #
+    #   engine.launch(launch_item, :cron => "0 5 * * *")
+    #     # will launch that same process every day,
+    #     # five minutes after midnight (see "man 5 crontab")
+    #
+    # === :wait_for
+    #
+    # If you really need that, you can launch a process and wait for its
+    # termination (or cancellation or error) as in :
+    #
+    #   engine.launch(launch_item, :wait_for => true)
+    #     # will launch and return only when the process is over
+    #
+    # Note that if you set the option :wait_for to true, a triplet will
+    # be returned instead of just a FlowExpressionId.
+    #
+    # This triplet is composed of [ message, info, fei ]
+    # where message is :terminate, :error or :cancel and info contains
+    # either the workitem, the error or a wfid, respectively.
+    #
+    # See http://groups.google.com/group/openwferu-users/browse_frm/thread/ffd0589bdc877765 for more about this triplet.
+    #
+    # (Note that the current implementation of this :wait_for will return if
+    # any error was found. Thus, if an error occurs in a concurrent branch
+    # and the other branch goes on, the launch() will return, even if the
+    # rest of the process is continuing).
+    #
+    def launch (launchobject, options={})
+
+      launchitem = to_launchitem(launchobject)
+
+      wait = (options.delete(:wait_for) == true)
+      initial_variables = options.delete(:vars) || options.delete(:variables)
+
+      #
+      # prepare raw expression
+
+      raw_expression = prepare_raw_expression(launchitem)
+        #
+        # will raise an exception if there are requirements
+        # and one of them is not met
+
+      raw_expression.new_environment(initial_variables)
+        #
+        # as this expression is the root of a new process instance,
+        # it has to have an environment for all the variables of
+        # the process instance
+        #
+        # (new_environment() calls store_itself on the new env)
+
+      raw_expression = wrap_in_schedule(raw_expression, options) \
+        if (options.keys & [ :in, :at, :cron, :every ]).size > 0
+
+      fei = raw_expression.fei
+
+      #
+      # apply prepared raw expression
+
+      wi = InFlowWorkItem.new
+      wi.attributes = launchitem.attributes.dup
+
+      if wait
+        get_expression_pool.wait_for(fei) {
+          get_expression_pool.launch(raw_expression, wi)
+        }
+      else
+        get_expression_pool.launch(raw_expression, wi)
+        fei.dup # returns a copy, not the real one
+      end
+    end
+
+    #
+    # When 'parameters' are used at the top of a process definition, this
+    # method can be used to assert a launchitem before launch.
+    # An expression will be raised if the parameters do not match the
+    # requirements.
+    #
+    # Note that the launch method will raise those exceptions as well.
+    # This method can be useful in some scenarii though.
+    #
+    def pre_launch_check (launchitem)
+
+      prepare_raw_expression(launchitem)
+    end
+
+    #
+    # Waits for a given process instance to terminate.
+    # The method only exits when the flow terminates, but beware : if
+    # the process already terminated, the method will never exit.
+    #
+    # The parameter can be a FlowExpressionId instance, for example the
+    # one given back by a launch(), or directly a workflow instance id
+    # (String).
+    #
+    # This method is mainly used in utests.
+    #
+    def wait_for (fei_or_wfid)
+
+      wfid = if fei_or_wfid.kind_of?(FlowExpressionId)
+        fei_or_wfid.workflow_instance_id
+      else
+        fei_or_wfid
+      end
+
+      get_expression_pool.wait_for(wfid)
+    end
+
+    protected
+
+    #
+    # This method is called by the launch method. It's actually the first
+    # stage of that method.
+    # It may be interessant to use to 'validate' a launchitem and its
+    # process definition, as it will raise an exception in case
+    # of 'parameter' mismatch.
+    #
+    # There is a 'pre_launch_check' alias for this method in the
+    # Engine class.
+    #
+    def prepare_raw_expression (launchitem)
+
+      wfdurl = launchitem.workflow_definition_url
+
+      definition, in_launchitem = if (not wfdurl)
+
+        [ launchitem.attributes.delete('__definition'), true ]
+
+      elsif wfdurl[0, 6] == 'field:'
+
+        [ launchitem.attributes.delete(wfdurl[6..-1]), true ]
+
+      else
+
+        [ get_def_parser.read_uri(wfdurl), false ]
+      end
+
+      raise(
+        "didn't find process definition at '#{wfdurl}'"
+      ) unless definition
+
+      raise(
+        ':definition_in_launchitem_allowed not set to true, cannot launch.'
+      ) if in_launchitem and ac[:definition_in_launchitem_allowed] != true
+
+      raw_expression = get_expression_pool.build_raw_expression(
+        definition, launchitem)
+
+      # grrr... I hate this parameter checking, feels like static typing
+
+      raw_expression.check_parameters(launchitem)
+        #
+        # will raise an exception if there are requirements
+        # and one of them is not met
+
+      raw_expression.store_itself
+
+      raw_expression
+    end
+
+    #
+    # Turns the raw launch request info into a LaunchItem instance.
+    #
+    def to_launchitem (o)
+
+      return o if o.is_a?(OpenWFE::LaunchItem)
+      return OpenWFE::LaunchItem.new(o) unless o.is_a?(String)
+
+      li = OpenWFE::LaunchItem.new
+
+      if %w{ < [ - }.include?(o.strip[0, 1]) or o.match(/\s/)
+        #
+        # XML, JSON or YAML or not a URI
+        #
+        li.definition = o
+      else
+        #
+        # it's a URI
+        #
+        li.definition_url = o
+      end
+
+      li
+    end
+
+  end
+end
+