ruote 0.9.18

data/lib/openwfe/participants/socketparticipants.rb

@@ -0,0 +1,202 @@
+#
+#--
+# 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
+#
+
+require 'yaml'
+require 'socket'
+require 'timeout'
+
+require 'openwfe/orest/xmlcodec'
+require 'openwfe/participants/participant'
+
+
+module OpenWFE
+
+    #
+    # This participant implementation dispatches workitems over TCP sockets.
+    # By default the workitem are dumped as YAML strings, but you can override 
+    # the encode_workitem(wi) method.
+    #
+    # A small example :
+    #
+    #     require 'openwfe/particpants/socketparticipants'
+    #
+    #     sp = OpenWFE::SocketParticipant.new("target.host.xx", 7007)
+    #
+    #     engine.register_participant("Alfred", sp)
+    #
+    class SocketParticipant
+
+        attr_accessor :host, :port
+
+        #
+        # The constructor
+        #
+        def initialize (host, port)
+
+            @host = host
+            @port = port
+        end
+
+        #
+        # The method called by the engine for each incoming workitem.
+        # Will dispatch the workitem over a TCP connection.
+        #
+        def consume (workitem)
+
+            dispatch(workitem)
+        end
+
+        def dispatch (workitem)
+
+            socket = TCPSocket.new(@host, @port)
+            socket.puts encode_workitem(workitem)
+            socket.puts
+            socket.close_write
+
+            #print "\n__socket.closed? #{socket.closed?}"
+
+            reply = fetch_reply(socket)
+
+            socket.close
+
+            decode_reply(reply)
+        end
+
+        #
+        # A 'static' method for dispatching workitems, you can use it
+        # directly, without instantiating the SocketParticipant :
+        #
+        #     require 'openwfe/participants/socketparticipants'
+        #
+        #     SocketParticipant.dispatch("127.0.0.1", 7007, workitem)
+        #
+        def SocketParticipant.dispatch (host, port, workitem)
+
+            SocketParticipant.new(host, port).dispatch(workitem)
+        end
+
+        protected
+
+            #
+            # By default, uses YAML to serialize the workitem
+            # (of course you can override this method).
+            #
+            def encode_workitem (wi)
+                YAML.dump(wi)
+            end
+
+            #
+            # By default, will just return the reply without touching it
+            #
+            def decode_reply (r)
+                r
+            end
+
+            #
+            # The code that waits for the reply from the server, nicely
+            # wrapped inside a timeout and a rescue block.
+            #
+            def fetch_reply (socket)
+
+                reply = ""
+
+                begin
+
+                    timeout(7) do
+                        while true
+                            r = socket.gets
+                            break unless r
+                            reply << r
+                        end
+                    end
+
+                rescue Exception => e
+                    puts e
+                    raise "timeout while waiting for reply"
+                end
+
+                reply
+            end
+    end
+
+    #
+    # This extension of of SocketParticipant can be used to dispatch
+    # workitems towards an OpenWFEja instance, but OpenWFEru's SocketListener
+    # understands XML workitems as well.
+    #
+    class XmlSocketParticipant < SocketParticipant
+
+        #def initialize (host, port)
+        #    super
+        #end
+
+        #
+        # A 'static' method for dispatching workitems, you can use it
+        # directly, without instantiating the SocketParticipant :
+        #
+        #     require 'openwfe/participants/socketparticipants'
+        #
+        #     SocketParticipant.dispatch("127.0.0.1", 7007, workitem)
+        #
+        def XmlSocketParticipant.dispatch (host, port, workitem)
+
+            XmlSocketParticipant.new(host, port).consume(workitem)
+        end
+
+        protected
+
+            #
+            # This implementation encodes the workitem as an XML document.
+            # This is compatible with OpenWFEja.
+            #
+            def encode_workitem (wi)
+
+                sxml = OpenWFE::XmlCodec::encode(wi)
+
+                s = "xmlCoder #{sxml.length}\n"
+                s << "\n"
+                s << sxml
+                s << "\n"
+                s << "\n"
+                s
+            end
+    end
+
+end
+

data/lib/openwfe/participants/storeparticipants.rb

@@ -0,0 +1,254 @@
+#
+#--
+# 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
+#
+
+require 'openwfe/utils'
+require 'openwfe/omixins'
+require 'openwfe/storage/yamlfilestorage'
+require 'openwfe/participants/participant'
+
+
+module OpenWFE
+
+    #
+    # A mixin gathering the methods a workitem store participant needs.
+    #
+    # Two kinds of methods are involved here, the ones used by the engine
+    # (its participant map) and the ones used by 'workflow clients'.
+    # Thus consume() and cancel() are triggered by the engine, and
+    # save() and forward() are at the disposal of 'workflow clients'.
+    #
+    # A 'workflow client' is supposed to use methods similar to hash methods
+    # to retrieve workitems, like in
+    #
+    #     storeparticipant.each do |fei, workitem|
+    #         puts "workitem : #{fei.to_s}"
+    #         do_some_work(workitem)
+    #     end
+    #
+    #
+    module StoreParticipantMixin
+        include LocalParticipant
+        include FeiMixin
+
+        #
+        # optional field (only used by the old rest interface for now)
+        #
+        attr_accessor :store_name
+
+        #
+        # Called by the engine (the participant expression) when handing
+        # out a workitem (to this participant).
+        #
+        # This method can also be used when delegating a workitem from
+        # one store participant to the other.
+        #
+        def consume (workitem)
+
+            self[workitem.flow_expression_id] = workitem
+        end
+        alias :push :consume
+
+        #
+        # Called by the participant expression when this participant is
+        # 'cancelled' within a flow. The workitem then gets removed.
+        #
+        def cancel (cancelitem)
+
+            ldebug do 
+                "cancel() removing workitem  #{cancelitem.flow_expression_id}"
+            end
+
+            self.delete(cancelitem.flow_expression_id)
+        end
+
+        #
+        # The workitem is to be stored again within the store participant,
+        # it will probably be reused later. Don't send back to engine yet.
+        #
+        def save (workitem)
+
+            raise "Workitem not found in #{self.class}, cannot save." \
+                unless self.has_key? workitem.flow_expression_id
+
+            self[workitem.flow_expression_id] = workitem
+        end
+
+        #
+        # The workflow client is done with the workitem, send it back to
+        # the engine and make sure it's not in the store participant anymore.
+        #
+        def forward (workitem)
+
+            raise "Workitem not found in #{self.class}, cannot forward." \
+                unless self.has_key? workitem.flow_expression_id
+
+            #self.delete(workitem.flow_expression_id)
+            self.delete(workitem)
+
+            reply_to_engine(workitem)
+        end
+
+        #
+        # 'proceed' is just an alias for 'forward'
+        #
+        alias :proceed :forward
+
+        #
+        # This delete() method accepts a workitem or simply its FlowExpressionId
+        # identifier.
+        #
+        def delete (wi_or_fei)
+            #fei = wi_or_fei
+            #fei = fei.fei if fei.is_a? InFlowWorkItem
+            #super fei
+            super extract_fei(wi_or_fei)
+        end
+
+        #
+        # A convenience method for delegating a workitem to another
+        # store participant.
+        #
+        def delegate (wi_or_fei, other_store_participant)
+            wi = delete(wi_or_fei)
+            other_store_participant.push(wi)
+        end
+
+        #
+        # Returns all the workitems for a given workflow instance id.
+        # If no workflow_instance_id is given, all the workitems will be
+        # returned.
+        #
+        def list_workitems (workflow_instance_id=nil)
+
+            result = []
+            self.each_value do |workitem|
+                result << workitem \
+                    if (not workflow_instance_id) or workitem.fei.parent_wfid == workflow_instance_id
+            end
+
+            result
+        end
+
+        #
+        # Returns the first workitem at hand.
+        # As a StoreParticipant is usually implemented with a hash, two
+        # consecutive calls to this method might not return the same workitem
+        # (except if the store is empty or contains 1! workitem).
+        #
+        def first_workitem
+
+            result = nil
+
+            self.each_value do |workitem|
+                result = workitem
+                break
+            end
+
+            return result
+        end
+    end
+
+    #
+    # The simplest workitem store possible, gathers the workitem in a 
+    # hash (this class is an extension of Hash).
+    #
+    # Some examples :
+    #
+    #     engine.register_participant(:alice, OpenWFE::HashParticipant)
+    #     engine.register_participant("bob", OpenWFE::HashParticipant)
+    #
+    #     hp = engine.register_participant(:charly, OpenWFE::HashParticipant)
+    #     #...
+    #     puts "there are currently #{hp.size} workitems for Charly"
+    #
+    #     hp = OpenWFE::HashParticipant.new
+    #     engine.register_participant("debbie", hp)
+    #
+    class HashParticipant < Hash
+        include StoreParticipantMixin
+
+        # that's all...
+    end
+
+    #
+    # Implementation of a store participant stores the workitems in
+    # yaml file in a dedicated directory.
+    #
+    # It's quite easy to register a YamlParticipant :
+    #
+    #     yp = engine.register_participant(:alex, YamlParticipant)
+    #
+    #     puts yp.dirname
+    #
+    # should yield "./work/participants/alex/" (if the key :work_directory
+    # in engine.application_context is unset)
+    #
+    class YamlParticipant < YamlFileStorage
+        include StoreParticipantMixin
+
+        attr_accessor :dirname
+
+        #
+        # The constructor for YamlParticipant awaits a dirname and an
+        # application_context.
+        # The dirname should be a simple name acceptable as a filename.
+        #
+        def initialize (dirname, application_context)
+
+            @dirname = OpenWFE::ensure_for_filename(dirname.to_s)
+
+            service_name = self.class.name + "__" + @dirname
+
+            path = "/participants/" + @dirname
+
+            super(service_name, application_context, path)
+        end
+
+        protected
+
+            def compute_file_path (fei)
+
+                @basepath +
+                fei.workflow_instance_id + "__" +
+                fei.workflow_definition_name + "_" +
+                fei.workflow_definition_revision + "__" +
+                fei.expression_id + ".yaml"
+            end
+    end
+end