participant_methods.rb in ruote-0.9.20

- old
+ new

@@ -1,43 +1,29 @@
-#
 #--
-# Copyright (c) 2006-2008, John Mettraux, OpenWFE.org
-# All rights reserved.
+# Copyright (c) 2006-2009, John Mettraux, jmettraux@gmail.com
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# 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 of source code must retain the above copyright notice, this
-#   list of conditions and the following disclaimer.
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# . 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 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.
 #
-# . 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.
 #++
-#
 
-#
-# "made in Japan"
-#
-# John Mettraux at openwfe.org
-#
 
 module OpenWFE
 
   #
   # The methods of the engine about participants (register, unregister,
@@ -48,22 +34,40 @@
     #
     # 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
+    #   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
+    #   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
+    #
     # Returns the participant instance.
     #
     # The participant parameter can be set to hash like in
     #
     #   engine.register_participant(
@@ -77,34 +81,36 @@
     #   end
     #
     # 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
     #
-    def register_participant (regex, participant=nil, &block)
+    #   engine.register_participant(
+    #     "investors",
+    #     InvestorParticipant,
+    #     { :money => 'lots of it', :clues => 'none' })
+    #
+    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
 
     #
     # 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
+      get_participant_map.lookup_participant(participant_name)
     end
 
     #
     # Removes the first participant matching the given name from the
     # participant map kept by the engine.
@@ -112,22 +118,24 @@
     # 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
+      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
+    def participants
 
       get_participant_map.participants
     end
+    #alias :list_participants :participants
+      # deprecated
   end
 
 end
 