ruote 0.9.18

data/lib/openwfe/participants.rb

@@ -0,0 +1,38 @@
+#
+#--
+# 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.
+#++
+#
+
+# just for nicer looking examples
+
+#require 'openwfe/participants/participants'
+require 'openwfe/participants/storeparticipants'
+

data/lib/openwfe/participants/enoparticipants.rb

@@ -0,0 +1,230 @@
+#
+#--
+# Copyright (c) 2007, Alain Hoang 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"
+#
+# Alain Hoang at openwfe.org
+# John Mettraux at openwfe.org
+#
+
+require 'net/smtp'
+
+require 'openwfe/participants/participant'
+require 'openwfe/participants/participants'
+
+
+module OpenWFE
+
+    #
+    # MailParticipant is a simplification of EmailNotificationParticipant.
+    #
+    # It's initialized in this way :
+    #
+    #     p = MailParticipant.new(
+    #         :smtp_server => "mailhost.ourcompany.co.jp",
+    #         :from_address => "bpms@our.ourcompany.co.jp",
+    #         :template => "Dear ${f:name}, you've got mail")
+    #
+    # or
+    #
+    #     p = MailParticipant.new(
+    #         :smtp_server => "mailhost.ourcompany.co.jp",
+    #         :smtp_port => 25,
+    #         :from_address => "bpms@our.ourcompany.co.jp"
+    #     ) do |workitem|
+    #         s = ""
+    #         s << "Dear #{workitem.name},\n"
+    #         s << "\n"
+    #         s << "it's #{Time.new.to_s} and you've got mail"
+    #         s
+    #     end
+    #
+    # As with EmailNotificationParticipant, the "to" address for your email
+    # is taken from the workitem's <tt>email_target</tt> field. So, to have 
+    # the email sent to "foo@nowhere.com", set your workitem's
+    # <tt>email_target</tt> field to "foo@nowhere.com" prior to feeding it
+    # to the mail participant.
+    #
+    # Likewise, you can also override the :from_address value by setting the
+    # workitems <tt>email_from</tt> field.
+    #
+    # When passing the mail template as a block, you have 
+    # four possible arities :
+    #     { |workitem| ... }
+    #     { |participant_expression, workitem| ... }
+    #     { |participant_expression, participant_instance, workitem| ... }
+    #     { ... }
+    #
+    # The smtp server and host default to "127.0.0.1" / 25.
+    #
+    class MailParticipant
+        include LocalParticipant
+        include TemplateMixin
+
+        def initialize (params, &block)
+
+            @smtp_server = params[:smtp_server]
+            @smtp_port = params[:smtp_port]
+            @from_address = params[:from_address]
+            @template = params[:template]
+
+            @block_template = block
+
+            # some defaults
+
+            @smtp_server = "127.0.0.1" unless @smtp_server
+            @smtp_port = 25 unless @smtp_port
+        end
+
+        #
+        # The method called each time a workitem reaches this participant
+        #
+        def consume (workitem)
+
+            fe = get_flow_expression(workitem)
+            to_address = workitem.email_target
+
+            #
+            # 1. Expand variables
+
+            msg  = eval_template workitem
+
+            from_address = workitem.email_from rescue @from_address
+
+            #puts "msg >>>\n#{msg}<<<"
+
+            #
+            # 2. Send message
+
+            Net::SMTP.start(@smtp_server, @smtp_port) do |smtp|
+                smtp.send_message(msg, from_address, to_address)
+            end
+
+            #
+            # 3. Reply to engine
+
+            reply_to_engine(workitem)
+        end
+    end
+
+    #
+    # This participant is used to send an email notification.
+    #
+    # It's perhaps better to use MailParticipant which is simpler to 
+    # initialize. This class is anyway an extension of MailParticipant.
+    #
+    #     @engine.register_participant(
+    #         'eno', 
+    #         EmailNotificationParticipant.new(
+    #             "googlemail.l.google.com",
+    #             25,
+    #             "eno@outoftheblue.co.jp",
+    #             """Subject: test 0
+    #
+    #     0 : ${r:Time.new}
+    #     1 : ${f:customer_name}
+    #             """))
+    #
+    # And then, from the process definition :
+    #
+    #     class TestDefinition0 < OpenWFE::ProcessDefinition
+    #         def make
+    #             process_definition :name => "test0", :revision => "0" do
+    #                 sequence do
+    #                     set :field => 'email_target' do
+    #                         "whatever56x56@gmail.com"
+    #                     end
+    #                     set :field => 'customer_name' do
+    #                         "Monsieur Toto"
+    #                     end
+    #                     participant :ref => 'eno'
+    #                 end
+    #             end
+    #         end
+    #     end
+    #
+    # The 'template' parameter may contain an instance of File instead of
+    # an instance of String.
+    #
+    #     @engine.register_participant(
+    #         'eno', 
+    #         EmailNotificationParticipant.new(
+    #             "googlemail.l.google.com",
+    #             25,
+    #             "eno@outoftheblue.co.jp",
+    #             File.new("path/to/my/mail/template.txt")))
+    #
+    # You can also define the email template as a Ruby block :
+    #
+    #     p = EmailNotificationParticipant.new("googlemail.l.google.com", 25, "eno@co.co.jp") do | flowexpression, participant, workitem |
+    #
+    #         # generally, only the workitem is used within a template
+    #
+    #         s = ""
+    #
+    #         # the header of the message
+    #
+    #         s << "Subject: #{workitem.subject}\n\n"
+    #
+    #         # then, the body
+    #
+    #         workitem.attributes.each do |key, value|
+    #             s << "- '#{k}' => '#{value}'\n"
+    #         end
+    #         s << "\ndone.\n"
+    #     end
+    #
+    # Note that the template integrates the subject and requires then a double
+    # newline before the message body.
+    #
+    class EmailNotificationParticipant < MailParticipant
+
+        #
+        # Create a new email notification participant.  Requires
+        # a mail server, port, a from address, and a mail message template
+        #
+        def initialize (
+            smtp_server, smtp_port, from_address, template=nil, &block)
+
+            params = {}
+            params[:smtp_server] = smtp_server
+            params[:smtp_port] = smtp_port
+            params[:from_address] = from_address
+
+            params[:template] = template if template
+
+            super(params, &block)
+        end
+    end
+end

data/lib/openwfe/participants/participant.rb

@@ -0,0 +1,141 @@
+#
+#--
+# 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
+#
+
+require 'openwfe/logging'
+require 'openwfe/contextual'
+require 'openwfe/rudefinitions'
+
+
+module OpenWFE
+
+    #
+    # The 'participant' concept is displayed as a module, so that 
+    # other pieces of code may easily 'mix it in'.
+    #
+    # Participant extensions should at least provide a consume(workitem)
+    # method.
+    # As an option, it can provide a cancel(cancelitem) method.
+    #
+    # The engine will transmit instances of OpenWFE:WorkItem via the
+    # consume method.
+    #
+    # If there is a cancel method available and an OpenWFE::CancelItem instance
+    # is emitted (cancelling a process or part of it), it will be fed to
+    # the participant only via the cancel method.
+    #
+    # If there is no cancel method, the participant will not get notified
+    # of the cancellation.
+    #
+    module Participant
+
+        #
+        # A Participant will be receiving OpenWFE::WorkItem's via this method.
+        #
+        def consume (workitem)
+
+            raise NotImplementedError.new(
+                "implementation for method consume() "+
+                "is missing in class '#{self.class}'")
+        end
+
+        #--
+        # (optional)
+        #
+        #def cancel (cancelitem)
+        #end
+        #++
+    end
+
+    #
+    # Local participants provide handy methods like reply_to_engine() to
+    # further implementations of the Participant concept.
+    #
+    module LocalParticipant
+        include Participant, Contextual, Logging, OwfeServiceLocator
+
+        #
+        # Returns the FlowExpression instance that triggered this
+        # participant. 
+        # A ParticipantExpression instance will most likely be returned.
+        #
+        def get_flow_expression (workitem)
+
+            return nil if not @application_context
+
+            get_expression_pool.fetch_expression(workitem.flow_expression_id)
+        end
+
+        #
+        # A convenience method for calling block passed to participants
+        # for templates (mail participants) or execution (BlockParticipant).
+        #
+        # Allows for such blocks :
+        #
+        #     { |workitem| ... }
+        #     { |participant_expression, workitem| ... }
+        #     { |participant_expression, participant, workitem| ... }
+        #
+        # For 0 or more than 3 arguments, the block will be called without
+        # arguments.
+        #
+        def call_block (block, workitem)
+
+            if block.arity == 1
+                block.call workitem
+            elsif block.arity == 2
+                block.call get_flow_expression(workitem), workitem
+            elsif block.arity == 3
+                block.call get_flow_expression(workitem), self, workitem
+            else
+                block.call
+            end
+        end
+
+        #
+        # Participants use this method to reply to their engine when
+        # their job is done.
+        #
+        def reply_to_engine (workitem)
+
+            get_engine.reply(workitem)
+        end
+    end
+
+end
+

data/lib/openwfe/participants/participantmap.rb

@@ -0,0 +1,249 @@
+#
+#--
+# 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
+#
+
+require 'openwfe/workitem'
+require 'openwfe/service'
+require 'openwfe/util/observable'
+require 'openwfe/participants/participants'
+
+
+module OpenWFE
+
+    #
+    # A very simple directory of participants
+    #
+    class ParticipantMap < Service
+        include OwfeObservable
+
+        attr_accessor :participants
+
+        def initialize (service_name, application_context)
+
+            super
+
+            @participants = []
+            @observers = {}
+        end
+
+        #
+        # Returns how many participants are currently registered here.
+        #
+        def size
+
+            @participants.size
+        end
+
+        #
+        # Adds a participant to this map.
+        # This method is called by the engine's own register_participant()
+        # method.
+        #
+        # The participant instance is returned by this method call.
+        #
+        # The know params are :participant (a participant instance or
+        # class) and :position (which can be null or :first).
+        #
+        # By default (if :position is not set to :first), the participant
+        # will appear at the bottom of the participant list.
+        #
+        def register_participant (regex, params, &block)
+
+            participant = params[:participant]
+            position = params[:position]
+
+            if not participant
+
+                raise "please provide a participant instance or a block" \
+                    if not block
+
+                participant = BlockParticipant.new block
+            end
+
+            ldebug do 
+                "register_participant() "+
+                "participant class is #{participant.class}"
+            end
+
+            if participant.is_a?(Class)
+
+                ldebug { "register_participant() class #{participant}" }
+
+                begin
+
+                    participant = participant.new(regex, @application_context)
+
+                rescue Exception => e
+                    #ldebug do 
+                    #    "register_participant() " +
+                    #    "falling back to no param constructor because of \n" +
+                    #    OpenWFE::exception_to_s(e)
+                    #end
+
+                    participant = participant.new
+                end
+            end
+
+            original_string = regex.to_s
+
+            unless regex.kind_of?(Regexp)
+
+                regex = regex.to_s
+                regex = "^" + regex unless regex[0, 1] == "^"
+                regex = regex  + "$" unless regex[-1, 1] == "$"
+
+                ldebug { "register_participant() '#{regex}'" }
+
+                regex = Regexp.new(regex)
+            end
+            
+            class << regex
+                attr_reader :original_string
+            end
+            regex.instance_variable_set '@original_string', original_string
+
+            participant.application_context = @application_context \
+                if participant.respond_to?(:application_context=)
+
+            # now add the participant to the list
+
+            entry = [ regex, participant ]
+
+            index = (position == :first) ? 0 : -1
+
+            @participants.insert index, entry
+
+            participant
+        end
+
+        #
+        # Looks up a participant given a participant_name.
+        # Will return the first participant whose name matches.
+        #
+        def lookup_participant (participant_name)
+
+            #ldebug { "lookup_participant() '#{participant_name}'" }
+
+            participant_name = participant_name.to_s
+
+            @participants.each do |tuple|
+                return tuple[1] if tuple[0].match(participant_name)
+            end
+
+            nil
+        end
+
+        #
+        # Deletes the first participant matching the given name.
+        #
+        # If 'participant_name' is an integer, will remove the participant
+        # at that position in the participant list.
+        #
+        def unregister_participant (participant_name)
+
+            return (@participants.delete_at(participant_name) != nil) \
+                if participant_name.is_a?(Integer)
+
+            participant_name = participant_name.to_s
+
+            p = @participants.find do |tuple|
+                tuple[0].original_string == participant_name
+            end
+            @participants.delete(p) if p
+            
+            (p != nil)
+        end
+
+        #
+        # Dispatches to the given participant (participant name (string) or
+        # The workitem will be fed to the consume() method of that participant.
+        # If it's a cancelitem and the participant has a cancel() method,
+        # it will get called instead.
+        #
+        def dispatch (participant, participant_name, workitem)
+
+            unless participant
+
+                participant = lookup_participant participant_name
+
+                raise "there is no participant named '#{participant_name}'" \
+                    unless participant
+            end
+
+            workitem.participant_name = participant_name
+
+            return cancel(participant, workitem) \
+                if workitem.is_a?(CancelItem)
+
+            onotify :dispatch, :before_consume, workitem
+
+            workitem.dispatch_time = Time.now
+
+            participant.consume workitem
+
+            onotify :dispatch, :after_consume, workitem
+        end
+
+        #
+        # The method onotify (from Osbservable) is made public so that
+        # ParticipantExpression instances may notify the pmap of applies
+        # and replies.
+        #
+        public :onotify
+
+        protected
+
+            #
+            # Will call the cancel method of the participant if it has
+            # one, or will simply discard the cancel item else.
+            #
+            def cancel (participant, cancel_item)
+
+                participant.cancel(cancel_item) \
+                    if participant.respond_to?(:cancel)
+
+                onotify :dispatch, :cancel, cancel_item
+                    #
+                    # maybe it'd be better to specifically log that
+                    # a participant has no cancel() method, but it's OK
+                    # like that for now.
+            end
+    end
+
+end
+