ruote 0.9.19 → 0.9.20

data/lib/openwfe/engine/listener_methods.rb

@@ -0,0 +1,128 @@
+#--
+# 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
+
+  #
+  # Adding the register_listener method to the Engine.
+  #
+  module ListenerMethods
+
+    #
+    # Adds a workitem listener to this engine.
+    #
+    # This method takes 2 arguments, a listener (or a listener Class) and an
+    # optional option list.
+    #
+    #   engine.register_listener(
+    #     OpenWFE::FileListener, :freq => "3m10s")
+    #
+    # or
+    #
+    #   engine.register_listener(
+    #     OpenWFE::Extras::JabberListener,
+    #     :jabber_id => 'jbot', :password => 'wyvern')
+    #
+    # It's OK to pass an instance of a listener instead of a class.
+    #
+    #   l = MyCustomListener.new(:a, :b, :c)
+    #   engine.register_listener(l)
+    #
+    # == frequency
+    #
+    # The :freq or :frequency option if present might indicate how frequently
+    # the resource should be polled for incoming workitems.
+    #
+    #   engine.register_listener(listener, :frequency => "3m10s")
+    #    # every 3 minutes and 10 seconds
+    #
+    #   engine.register_listener(listener, :freq => "0 22 * * 1-5")
+    #    # every weekday at 10pm
+    #
+    # If the frequency is set, this method will return the job_id of the
+    # listener in the engine's scheduler. When no frequency is given, nil is
+    # returned.
+    #
+    # TODO : block handling...
+    #
+    def register_listener (listener, opts={})
+
+      name = get_listener_name(opts)
+
+      l = listener.is_a?(Class) ? listener.new(name, opts) : listener
+
+      l.application_context = @application_context \
+        if l.respond_to?(:application_context=) # even if already set
+
+      @application_context[name] = l
+        # just to be sure.
+
+      job_id = if freq = opts[:frequency] || opts[:freq]
+
+        freq = freq.to_s.strip
+
+        raise(
+          "cannot schedule listener of class '#{l.class}', "+
+          "it doesn't have a trigger() method"
+        ) unless l.respond_to?(:trigger)
+
+        m = Rufus::Scheduler.is_cron_string(freq) ? :cron : :every
+        get_scheduler.send(m, freq, l)
+
+      else
+
+        nil
+      end
+
+      linfo { "register_listener() added '#{name}' (#{l.class})" }
+
+      job_id
+    end
+
+    alias :add_workitem_listener :register_listener
+    alias :add_listener :register_listener
+
+    protected
+
+    def get_listener_name (opts) #:nodoc#
+
+      if name = opts[:name]
+        return name
+      end
+
+      name = ''
+      i = 0
+
+      loop do
+        name = "listener_#{i}"
+        break unless @application_context[name]
+        i += 1
+      end
+      name
+    end
+
+  end
+end
+

data/lib/openwfe/engine/lookup_methods.rb

@@ -0,0 +1,156 @@
+#--
+# 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
+
+  #
+  # Engine methods for looking up variables and fields (workitem attributes)
+  #
+  module LookupMethods
+
+    #
+    # Looks up a process variable in a process.
+    # If fei_or_wfid is not given, will simply look in the
+    # 'engine environment' (where the top level variables '//' do reside).
+    #
+    def lookup_variable (var_name, fei_or_wfid=nil)
+
+      return get_expression_pool.fetch_engine_environment[var_name] \
+        unless fei_or_wfid
+
+      fetch_exp(fei_or_wfid).lookup_variable(var_name)
+    end
+
+    #
+    # Returns the variables set for a process or an expression.
+    #
+    # If a process (wfid) is given, variables of the process environment
+    # will be returned, else variables in the environment valid for the
+    # expression (fei) will be returned.
+    #
+    # If nothing (or nil) is given, the variables set in the engine
+    # environment will be returned.
+    #
+    def get_variables (fei_or_wfid=nil)
+
+      return get_expression_pool.fetch_engine_environment.variables \
+        unless fei_or_wfid
+
+      fetch_exp(fei_or_wfid).get_environment.variables
+    end
+
+    #
+    # A method for looking up process instances. It expects some options /
+    # parameters. The scope is rather wide, it may look among fields
+    # (attributes) of workitems and variables of processes.
+    #
+    # Returns an array of wfid (workflow instance ids)
+    #
+    # :value or :val ::
+    #   matches processes with a field or variable with the given value
+    # :name ::
+    #   matches processes containing a field or a variable with that name
+    # :variable_name or :var_name or :v_name ::
+    #   matches processes with a variable with that name
+    # :field_name or :f_name ::
+    #   matches processes with a workitem field named like this
+    # :wfid_prefix ::
+    #   matches processes whose wfid (process instance id) begins with the given
+    #   value
+    # :wfid ::
+    #   matches the process instance whose wfid (process instance id) is given
+    #   here
+    #
+    def lookup_processes (options)
+
+      val = options[:value] || options[:val]
+
+      vf = options[:vf]
+      var = options[:variable] || options[:var] || options[:v] || vf
+      field = options[:field] || options[:f] || vf
+
+      raise "specify at least :variable or :field" \
+        if (var == nil) and (field == nil)
+
+      opts = {
+        :wfid => options[:wfid],
+        :wfid_prefix => options[:wfid_prefix]
+      }
+
+      # do look up...
+
+      opts[:include_classes] = Environment if field == nil
+
+      exps = get_expression_storage.find_expressions(opts)
+
+      result = exps.find_all do |exp|
+        v_match?(exp, var, val) || f_match?(exp, field, val)
+      end
+
+      result.collect { |exp| exp.fei.wfid }
+    end
+
+    protected
+
+      def f_match? (exp, field, value)
+
+        return false unless field
+        return false unless exp.respond_to?(:applied_workitem)
+
+        h_match?(exp.applied_workitem.attributes, field, value, true)
+      end
+
+      def v_match? (exp, var, value)
+
+        return false unless var
+        return false unless exp.is_a?(Environment)
+        return false if exp.fei.wfid == '0' # (engine environment)
+
+        h_match?(exp.variables, var, value)
+      end
+
+      def h_match? (h, k, v, recursive=false)
+
+        val = h[k]
+
+        if val != nil
+          case v
+            when nil then return true
+            when Regexp then return true if v.match(val)
+            else return true if v == val
+          end
+        end
+
+        return false unless recursive
+
+        h.values.each do |val|
+          return true if val.is_a?(Hash) and h_match?(val, k, v, true)
+        end
+
+        false
+      end
+  end
+end
+

data/lib/openwfe/engine/participant_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
 
@@ -50,17 +36,35 @@ module OpenWFE
     # This method is a shortcut to the ParticipantMap method
     # with the same name.
     #
-    #  engine.register_participant "user-.*", HashParticipant
+    #   engine.register_participant "user-.*", HashParticipant
+    #
+    # or
+    #
+    #   require 'openwfe/participants/mail_participants'
+    #
+    #   engine.register_participant(
+    #     'user-toto',
+    #     OpenWFE::MailParticipant.new(
+    #       :smtp_server => "mailhost.ourcompany.co.jp",
+    #       :smtp_port => 25,
+    #       :from_address => "bpms@our.ourcompany.co.jp"
+    #     ) { |workitem|
+    #       s = ""
+    #       s << "Dear #{workitem.name},\n"
+    #       s << "\n"
+    #       s << "it's #{Time.new.to_s} and you've got mail"
+    #       s
+    #     })
     #
     # 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
+    #   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.
     #
@@ -79,20 +83,22 @@ module OpenWFE
     # There are some times where you have to position a participant first
     # (especially with the regex technique).
     #
-    # see ParticipantMap#register_participant
+    # some participants have an 'initialize' method whose unique parameter
+    # is a option hash
+    #
+    #   engine.register_participant(
+    #     "investors",
+    #     InvestorParticipant,
+    #     { :money => 'lots of it', :clues => 'none' })
     #
-    def register_participant (regex, participant=nil, &block)
+    def register_participant (regex, participant=nil, options={}, &block)
 
-      #get_participant_map.register_participant(
-      #  regex, participant, &block)
+      params = participant.class == Hash ?
+        participant : { :participant => participant }
 
-      params = if participant.class == Hash
-        participant
-      else
-        { :participant => participant }
-      end
+      params = params.merge(options)
 
-      get_participant_map.register_participant regex, params, &block
+      get_participant_map.register_participant(regex, params, &block)
     end
 
     #
@@ -102,7 +108,7 @@ module OpenWFE
     #
     def get_participant (participant_name)
 
-      get_participant_map.lookup_participant participant_name
+      get_participant_map.lookup_participant(participant_name)
     end
 
     #
@@ -114,7 +120,7 @@ module OpenWFE
     #
     def unregister_participant (participant_name)
 
-      get_participant_map.unregister_participant participant_name
+      get_participant_map.unregister_participant(participant_name)
     end
 
     #
@@ -123,10 +129,12 @@ module OpenWFE
     #
     # Returns a list of [ regex, participant ] pairs.
     #
-    def list_participants
+    def participants
 
       get_participant_map.participants
     end
+    #alias :list_participants :participants
+      # deprecated
   end
 
 end