openwferu-extras 0.9.12.863

data/lib/openwfe/extras/listeners/sqslisteners.rb

@@ -0,0 +1,151 @@
+#
+#--
+# 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.
+#++
+#
+# $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
+#
+
+#
+# "made in Japan"
+#
+# John Mettraux at openwfe.org
+#
+
+require 'yaml'
+require 'base64'
+require 'monitor'
+
+require 'openwfe/service'
+require 'openwfe/util/scheduler'
+require 'openwfe/listeners/listener'
+
+require 'openwfe/extras/util/sqs'
+
+
+#
+# some base listener implementations
+#
+module OpenWFE
+module Extras
+
+    #
+    # Polls an Amazon SQS queue for workitems
+    #
+    # Workitems can be instances of InFlowWorkItem or LaunchItem.
+    #
+    #     require 'openwfe/extras/listeners/sqslisteners'
+    #
+    #     ql = OpenWFE::SqsListener("workqueue1", engine.application_context)
+    #
+    #     engine.add_workitem_listener(ql, "2m30s")
+    #         #
+    #         # thus, the engine will poll our "workqueue1" SQS queue
+    #         # every 2 minutes and 30 seconds
+    #
+    class SqsListener < Service
+        include MonitorMixin
+        include WorkItemListener
+        include Schedulable
+
+        #
+        # The name of the Amazon SQS whom this listener cares for
+        #
+        attr_reader :queue_name
+
+        def initialize (queue_name, application_context)
+
+            @queue_name = queue_name.to_s
+
+            service_name = "#{self.class}::#{@queue_name}"
+
+            super(service_name, application_context)
+
+            linfo { "new() queue is '#{@queue_name}'" }
+        end
+
+        #
+        # Will 'find' files in the work directory (by default ./work/in/),
+        # extract the workitem in them and feed it back to the engine.
+        #
+        def trigger (params)
+            synchronize do
+
+                ldebug { "trigger()" }
+
+                qs = SQS::QueueService.new
+
+                qs.create_queue(@queue_name)
+                    # just to be sure it is there
+
+                while true
+
+                    l = qs.get_messages(
+                        @queue_name, :timeout => 0, :count => 255)
+
+                    break if l.length < 1
+
+                    l.each do |msg|
+
+                        o = decode_object(msg)
+
+                        handle_object(o)
+
+                        msg.delete
+
+                        ldebug do 
+                            "trigger() " +
+                            "handled successfully msg #{msg.message_id}" 
+                        end
+                    end
+                end
+            end
+        end
+
+        #
+        # Extracts a workitem from the message's body.
+        #
+        # By default, this listeners assumes the workitem is stored in
+        # its "hash form" (not directly as a Ruby InFlowWorkItem instance).
+        #
+        # LaunchItem instances (as hash as well) are also accepted.
+        #
+        def decode_object (message)
+
+            o = Base64.decode64(message.message_body)
+            o = YAML.load(o)
+            o = OpenWFE::workitem_from_h(o)
+            o
+        end
+    end
+
+end
+end
+

data/lib/openwfe/extras/participants/activeparticipants.rb

@@ -0,0 +1,334 @@
+#
+#--
+# 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.
+#++
+#
+
+#
+# "made in Japan"
+#
+# John Mettraux at openwfe.org
+# 
+
+require 'rubygems'
+require_gem 'activerecord'
+
+
+require 'openwfe/workitem'
+require 'openwfe/flowexpressionid'
+require 'openwfe/participants/participant'
+
+
+module OpenWFE
+module Extras
+
+    #
+    # The migration for ActiveParticipant and associated classes.
+    #
+    # There are two tables 'workitems' and 'fields'. As its name implies,
+    # the latter table stores the fields (also called attributes in OpenWFE
+    # speak) of the workitems.
+    #
+    # See Workitem and Field for more details.
+    #
+    # For centralization purposes, the migration and the model are located
+    # in the same source file. It should be quite easy for the Rails hackers
+    # among you to sort that out for a Rails based usage.
+    #
+    class OwfeTables < ActiveRecord::Migration
+        def self.up
+            create_table :workitems do |t|
+                t.column :fei, :string
+                t.column :wfid, :string
+                t.column :wf_name, :string
+                t.column :wf_revision, :string
+                t.column :participant_name, :string
+                t.column :store, :string
+            end
+            create_table :fields do |t|
+                t.column :key, :string, :null => false
+                t.column :value, :text
+                t.column :workitem_id, :integer, :null => false
+            end
+            add_index :fields, [ :workitem_id, :key], :unique => true
+        end
+        def self.down
+            drop_table :workitems
+            drop_table :fields
+        end
+    end
+
+    #
+    # The ActiveRecord version of an OpenWFEru workitem (InFlowWorkItem).
+    #
+    # One can very easily build a worklist based on a participant name via :
+    #
+    #     wl = OpenWFE::Extras::Workitem.find_all_by_participant_name("toto")
+    #     puts "found #{wl.size} workitems for participant 'toto'"
+    #
+    # These workitems are not OpenWFEru workitems directly. But the conversion 
+    # is pretty easy.
+    # Note that you probaly won't need to do the conversion by yourself, 
+    # except for certain advanced scenarii.
+    #
+    #     awi = OpenWFE::Extras::Workitem.find_by_participant_name("toto")
+    #         # 
+    #         # returns the first workitem in the database whose participant
+    #         # name is 'toto'.
+    #
+    #     owi = awi.as_owfe_workitem
+    #         # 
+    #         # Now we have a copy of the reference as a OpenWFEru 
+    #         # InFlowWorkItem instance.
+    #
+    #     awi = OpenWFE::Extras::Workitem.from_owfe_workitem(owi)
+    #         #
+    #         # turns an OpenWFEru InFlowWorkItem instance into an
+    #         # 'active workitem'.
+    #
+    class Workitem < ActiveRecord::Base
+
+        has_many :fields, :dependent => :destroy
+
+        #
+        # Returns the flow expression id of this work (its unique OpenWFEru
+        # identifier) as a FlowExpressionId instance.
+        # (within the Workitem it's just stored as a String).
+        #
+        def full_fei
+
+            OpenWFE::FlowExpressionId.from_s(fei)
+        end
+
+        #
+        # Generates a (new) Workitem from an OpenWFEru InFlowWorkItem instance.
+        #
+        # This is a 'static' method :
+        #
+        #     awi = OpenWFE::Densha::Workitem.from_owfe_workitem(wi)
+        #
+        # (This method will not save the 'ActiveWorkitem').
+        #
+        def self.from_owfe_workitem (wi)
+
+            i = Workitem.new
+            i.fei = wi.fei.to_s
+            i.wfid = wi.fei.wfid
+            i.wf_name = wi.fei.workflow_definition_name
+            i.wf_revision = wi.fei.workflow_definition_revision
+            i.participant_name = wi.participant_name
+
+            wi.attributes.each do |k, v|
+                f = Field.new
+                f.key = k
+                f.value = v
+                i.fields << f
+            end
+            i
+        end
+
+        #
+        # Turns the densha Workitem into an OpenWFEru InFlowWorkItem.
+        #
+        def as_owfe_workitem
+
+            wi = OpenWFE::InFlowWorkItem.new
+            wi.fei = full_fei
+            wi.participant_name = participant_name
+            wi.attributes = fields_hash
+            wi
+        end
+
+        #
+        # Returns a hash version of the 'fields' of this workitem.
+        #
+        # (Each time this method is called, it returns a new hash).
+        #
+        def fields_hash
+
+            h = {}
+            fields.each do |f|
+                h[f.key] = f.value
+            end
+            h
+        end
+
+        #
+        # Returns the Field instance with the given key. This method accept
+        # symbols as well as strings as its parameter.
+        #
+        #     wi.field("customer_name")
+        #     wi.field :customer_name
+        #
+        def field (key)
+
+            fields.find_by_key(key.to_s)
+        end
+
+        #
+        # A shortcut method, replies to the workflow engine and removes self
+        # from the database.
+        # Handy for people who don't want to play with an ActiveParticipant
+        # instance when just consuming workitems (that an active participant
+        # pushed in the database).
+        #
+        def reply (engine)
+
+            engine.reply self.as_owfe_workitem
+            self.destroy
+        end
+
+        alias :forward :reply
+        alias :proceed :reply
+    end
+
+    #
+    # A Field (Attribute) of a Workitem.
+    #
+    class Field < ActiveRecord::Base
+
+        belongs_to :workitem
+        serialize :value
+
+        #
+        # A quick method for doing
+        #
+        #     f = Field.new
+        #     f.key = key
+        #     f.value = value
+        #
+        # One can then quickly add fields to an [active] workitem via :
+        #
+        #     wi.fields << Field.new_field("toto", "b")
+        #
+        def self.new_field (key, value)
+            f = Field.new
+            f.key = key
+            f.value = value
+            f
+        end
+    end
+
+
+    #
+    # A basic 'ActiveParticipant'.
+    # A store participant whose store is a set of ActiveRecord tables.
+    #
+    # Sample usage :
+    #
+    #     class MyDefinition < OpenWFE::ProcessDefinition
+    #         sequence do
+    #             active0
+    #             active1
+    #         end
+    #     end
+    #
+    #     def play_with_the_engine
+    #
+    #         engine = OpenWFE::Engine.new
+    #
+    #         engine.register_participant(
+    #             :active0, OpenWFE::Extras::ActiveParticipant)
+    #         engine.register_participant(
+    #             :active1, OpenWFE::Extras::ActiveParticipant)
+    #
+    #         li = OpenWFE::LaunchItem.new(MyDefinition)
+    #         li.customer_name = 'toto'
+    #         engine.launch li
+    #
+    #         sleep 0.500
+    #             # give some slack to the engine, it's asynchronous after all
+    #
+    #         wi = OpenWFE::Extras::Workitem.find_by_participant_name("active0")
+    #         
+    #         # ...
+    #    end
+    #
+    class ActiveParticipant
+        include OpenWFE::LocalParticipant
+
+        #
+        # This is the method called by the OpenWFEru engine to hand a 
+        # workitem to this participant.
+        #
+        def consume (workitem)
+
+            awi = Workitem.from_owfe_workitem(workitem)
+                #
+                # turns the workitem into an 'active' one
+
+            awi.save
+                #
+                # and saves it in the db.
+        end
+
+        #
+        # Called by the engine when the whole process instance (or just the
+        # segment of it that sports this participant) is cancelled.
+        # Will removed the workitem with the same fei as the cancelitem
+        # from the database.
+        #
+        # No expression will be raised if there is no corresponding workitem.
+        #
+        def cancel (cancelitem)
+
+            Workitem.delete_all([ "fei = ?", cancelitem.fei.to_s ])
+        end
+
+        #
+        # When the activity/work/operation whatever is over and the flow
+        # should resume, this is the method to use to hand back the [modified]
+        # workitem to the [local] engine.
+        #
+        def reply_to_engine (workitem)
+
+            super workitem.as_owfe_workitem
+                #
+                # replies to the workflow engine
+
+            workitem.destroy
+                #
+                # removes the workitem from the database
+        end
+    end
+
+    #
+    # TODO : please document me
+    #
+    class ActiveStoreParticipant < ActiveParticipant
+        include Enumerable
+
+        def each (&block)
+        end
+    end
+
+end
+end
+