openwferu 0.9.7 → 0.9.8

data/examples/engine_template.rb

@@ -0,0 +1,182 @@
+
+require 'rubygems'
+    #
+    # if OpenWFEru was installed via 'gem'
+
+#
+# setting up an OpenWFEru engine, step by step
+
+require 'openwfe/engine/engine'
+require 'openwfe/engine/file_persisted_engine'
+require 'openwfe/expool/history'
+require 'openwfe/expool/journal'
+require 'openwfe/listeners/listeners'
+require 'openwfe/participants/participants'
+
+
+#
+# === the ENGINE itself
+#
+
+#application_context = {}
+#application_context[:work_directory] = "work"
+    #
+    # OpenWFEru engines take one optional argument : application_context
+    # 
+    # the following engine constructions do not use this argument,
+    # but you can make them use it
+    #
+    #     engine = OpenWFE::Engine.new(application_context)
+    #
+    # ...
+    #
+
+
+#engine = OpenWFE::Engine.new
+    #
+    # an in-memory, totally transient engine
+    #
+    # might be ideal for an embedded workflow engine with short lived
+    # process definitions to run
+
+#engine = OpenWFE::FilePersistedEngine.new
+    #
+    # a file persisted engine, slow, used only within unit tests
+    # do not use
+
+engine = OpenWFE::CachedFilePersistedEngine.new
+    #
+    # a file persisted engine, with an in-memory cache.
+    # use that
+    #
+    # persistence is done by default under ./work/
+
+# -- a console
+
+#engine.enable_irb_console
+    #
+    # by enabling the IRB console, you can jump into the engine object
+    # with a CTRL-C hit on the terminal that runs hit.
+    #
+    # Hit CTRL-D to get out of the IRB console.
+
+# -- process history
+
+#engine.init_service("history", InMemoryHistory)
+    #
+    # keeps all process history in an arry in memory
+    # use only for test purposes !
+
+#engine.init_service("history", FileHistory)
+    #
+    # dumps all the process history in a file name "history.log"
+    # in the work directory
+
+# -- process journaling
+
+#engine.init_service("journal", Journal)
+    #
+    # activates 'journaling',
+    #
+    # see http://openwferu.rubyforge.org/journal.html
+    #
+#engine.application_context[:keep_journals] = true
+    #
+    # if set to true, the journal of terminated processes will be kept
+    # (but moved by default to ./work/journal/done/)
+
+
+#
+# === some LISTENERS
+#
+# listeners 'receive' incoming workitems (InFlowWorkItem coming back from
+# participants or LaunchItem requesting the launch of a particular flow)
+#
+
+#sl = OpenWFE::SocketListener.new(
+#    "socket_listener", @engine.application_context, 7008)
+#engine.add_workitem_listener(sl)
+    #
+    # adding a simple SocketListener on port 7008
+
+#require 'openwfe/listeners/socketlisteners'
+#
+#engine.add_workitem_listener(OpenWFE::SocketListener)
+    #
+    # adding a SocketListener on the default port 7007
+
+#engine.add_workitem_listener(OpenWFE::FileListener, "500")
+    #
+    # listening for workitems (coming as within YAML files dropped in the
+    # default ./work/in directory)
+    #
+    # check for new files every 500 ms
+
+#require 'openwfe/listeners/sqslisteners'
+#
+#engine.add_workitem_listener(
+#    OpenWFE::SqsListener.new(:wiqueue, engine.application_context), 
+#    "2s")
+    #
+    # adds a listener polling an Amazon Simple Queue Service (SQS) 
+    # named 'wiqueue' every 2 seconds
+    #
+    # http://jmettraux.wordpress.com/2007/03/13/openwferu-over-amazon-sqs/
+    # http://aws.amazon.com/sqs
+
+
+#
+# === the PARTICIPANTS
+#
+# to learn more about participants : 
+# http://openwferu.rubyforge.org/participants.html
+#
+
+# you can use indifferently symbols or strings for participant names
+
+# It's perhaps better to separate the participant registration and put
+# it in its own .rb file, but anyway, here are some participant registration 
+# examples :
+
+engine.register_participant(:toto) do |workitem|
+    puts "toto received a workitem..."
+    puts "lots of work..." if workitem.attributes.size > 3 
+    sleep 4
+    puts "done."
+end
+    #
+    # an example of a "block participant", binding Ruby code to a 
+    # participant in a business process
+
+#require 'openwfe/participants/sqsparticipants'
+#
+#engine.register_participant(:sqs, OpenWFE::SqsParticipant.new(:wiqueue2))
+    #
+    # registers a participant named 'sqs', workitems for it will get placed
+    # on the SQS queue named "wiqueue2"
+
+#require 'openwfe/participants/socketparticipants'
+#
+#engine.register_participant(
+#    "away", OpenWFE::SocketParticipant.new("target.host.co.jp", 7009))
+    #
+    # the participant "away" listens for workitems on port 7009 of
+    # host 'target.host.co.jp', our SocketParticipant will dispatch
+    # the workitem to it over TCP
+
+
+#
+# === joining the engine's scheduler thread
+#
+# (preventing the Ruby interpreting from prematurely (immediately) exiting)
+#
+
+engine.join
+    #
+    # you don't need to 'join' if the engine uses a listener, the thread of
+    # the listener will prevent the Ruby interpreter from exiting.
+    #
+    # hit CTRL-C to quit (or maybe engine.enable_irb_console has been called,
+    # in which case CTRL-C will bring you into a IRB console within the
+    # engine itself).
+

data/examples/openwferu.rb

@@ -36,14 +36,12 @@ end
 # a process definition
 
 class TheProcessDefinition0 < OpenWFE::ProcessDefinition
-    def make
-        sequence do
-            concurrence do
-                participant :alice
-                participant :bob
-            end
-            participant :summarize
+    sequence do
+        concurrence do
+            participant :alice
+            participant :bob
         end
+        participant :summarize
     end
 end
 
@@ -55,3 +53,4 @@ li = OpenWFE::LaunchItem.new(TheProcessDefinition0)
 li.initial_comment = "please give your impressions about http://ruby-lang.org"
 
 engine.launch(li)
+

data/lib/openwfe/contextual.rb

@@ -58,13 +58,15 @@ module OpenWFE
         # class is returned.
         #
         def lookup (key)
+
             if key.kind_of? Class
                 @application_context.each do |k, value|
                     return value if value.class == key
                 end
                 return nil
             end
-            return @application_context[key]
+
+            @application_context[key]
         end
         
         #
@@ -77,12 +79,12 @@ module OpenWFE
 
             s = service_class.new(service_name, @application_context)
 
-            s.service_name = "#{service_class.name}::#{s.object_id}" \
-                unless service_name
-
-            @application_context[s.service_name.to_s] = s
+            unless service_name
+                s.service_name = "#{service_class.name}::#{s.object_id}"
+                @application_context[s.service_name.to_s] = s
+            end
 
-            return s
+            s
         end
 
     end

data/lib/openwfe/engine/engine.rb

@@ -45,6 +45,7 @@ require 'logger'
 require 'openwfe/workitem'
 require 'openwfe/rudefinitions'
 require 'openwfe/service'
+require 'openwfe/util/irb'
 require 'openwfe/util/scheduler'
 require 'openwfe/util/schedulers'
 require 'openwfe/expool/wfidgen'
@@ -66,11 +67,12 @@ module OpenWFE
         #
         # Builds an OpenWFEru engine.
         #
-        def initialize ()
-
-            super(S_ENGINE, {})
+        # Accepts an optional initial application_context (containing
+        # initialization params for services for example).
+        #
+        def initialize (application_context={})
 
-            @application_context[@service_name] = self
+            super(S_ENGINE, application_context)
 
             $OWFE_LOG = Logger.new("engine.log") unless $OWFE_LOG
 
@@ -237,7 +239,7 @@ module OpenWFE
 
             if listener.kind_of? Class
 
-                listener = init_service(nil, listener)
+                listener = init_service nil, listener
 
                 name = listener.service_name
             else
@@ -285,6 +287,30 @@ module OpenWFE
             get_scheduler.join
         end
 
+        #
+        # Enabling the console means that hitting CTRL-C on the window /
+        # term / dos box / whatever does run the OpenWFEru engine will
+        # open an IRB interactive console for directly manipulating the
+        # engine instance.
+        #
+        # Hit CTRL-D to get out of the console.
+        #
+        def enable_irb_console
+
+            OpenWFE::trap_int_irb(binding)
+        end
+
+        #
+        # Makes sure that hitting CTRL-C will actually kill the engine VM and
+        # not open an IRB console.
+        #
+        #def disable_irb_console
+        #    $openwfe_irb = nil
+        #    trap 'INT' do
+        #        exit 0
+        #    end
+        #end
+
         #
         # Stopping the engine will stop all the services in the
         # application context.
@@ -307,6 +333,8 @@ module OpenWFE
                     end
                 end
             end
+
+            nil
         end
 
         #
@@ -377,7 +405,7 @@ module OpenWFE
             # see for example file_persisted_engine.rb
             #
 
-            def build_expression_map ()
+            def build_expression_map
 
                 @application_context[S_EXPRESSION_MAP] = ExpressionMap.new
                     #
@@ -391,29 +419,36 @@ module OpenWFE
                 #end
             end
 
-            def build_wfid_generator ()
+            def build_wfid_generator
+
+                #init_service S_WFID_GENERATOR, DefaultWfidGenerator
+                #init_service S_WFID_GENERATOR, UuidWfidGenerator
+                init_service S_WFID_GENERATOR, KotobaWfidGenerator
 
-                #init_service(S_WFID_GENERATOR, DefaultWfidGenerator)
-                #init_service(S_WFID_GENERATOR, UuidWfidGenerator)
-                init_service(S_WFID_GENERATOR, KotobaWfidGenerator)
+                #g = FieldWfidGenerator.new(
+                #    S_WFID_GENERATOR, @application_context, "wfid")
+                    #
+                    # showing how to initialize a FieldWfidGenerator that
+                    # will take as workflow instance id the value found in
+                    # the field "wfid" of the LaunchItem.
             end
 
-            def build_expression_pool ()
+            def build_expression_pool
 
                 init_service(S_EXPRESSION_POOL, ExpressionPool)
             end
 
-            def build_expression_storage ()
+            def build_expression_storage
 
                 init_service(S_EXPRESSION_STORAGE, InMemoryExpressionStorage)
             end
 
-            def build_participant_map ()
+            def build_participant_map
 
                 init_service(S_PARTICIPANT_MAP, ParticipantMap)
             end
             
-            def build_scheduler ()
+            def build_scheduler
 
                 init_service(S_SCHEDULER, SchedulerService)
             end

data/lib/openwfe/expool/expressionpool.rb

@@ -55,6 +55,7 @@ require 'openwfe/util/observable'
 require 'openwfe/expressions/environment'
 require 'openwfe/expressions/raw_xml'
 require 'openwfe/expressions/raw_prog'
+require 'openwfe/expressions/simplerep'
 
 include OpenWFE
 
@@ -190,7 +191,7 @@ module OpenWFE
             raise "didn't find process definition at '#{wfdurl}'" \
                 unless definition
 
-            raw_expression = build_raw_expression(wfdurl, definition)
+            raw_expression = build_raw_expression(launchitem, definition)
 
             raw_expression.check_parameters(launchitem)
                 #
@@ -255,7 +256,7 @@ module OpenWFE
             elsif template.is_a? FlowExpressionId
                 fetch_expression(template)
             else
-                build_raw_expression("no-url", template)
+                build_raw_expression(nil, template)
             end
 
             #raise "did not find expression at #{template.to_s}" \
@@ -387,7 +388,7 @@ module OpenWFE
             inflowitem = exp.cancel()
             remove(exp)
 
-            return inflowitem
+            inflowitem
         end
 
         #
@@ -422,7 +423,7 @@ module OpenWFE
         #
         # Replies to the parent of the given expression.
         #
-        def reply_to_parent (exp, workitem)
+        def reply_to_parent (exp, workitem, remove=true)
 
             ldebug { "reply_to_parent() for #{exp.fei.to_debug_s}" }
 
@@ -430,12 +431,27 @@ module OpenWFE
 
             onotify :reply_to_parent, exp.fei, workitem
 
-            remove(exp)
+            if remove
+
+                remove(exp)
+                    #
+                    # remove the expression itself
+
+                exp.clean_children()
+                    #
+                    # remove all the children of the expression
+            end
 
             #
-            # remove all the children of the expression
+            # manage tag, have to remove it so it can get 'redone' or 'undone'
+            # (preventing abuse)
+
+            tagname = exp.attributes["tag"] if exp.attributes
 
-            exp.clean_children()
+            exp.delete_variable(tagname) if tagname
+
+            #
+            # flow terminated ?
 
             if not exp.parent_id
                 ldebug do 
@@ -448,6 +464,9 @@ module OpenWFE
                 return
             end
 
+            #
+            # else, gone parent ?
+
             if exp.parent_id == GONE_PARENT_ID
                 ldebug do
                     "reply_to_parent() parent is gone for  " +
@@ -457,6 +476,9 @@ module OpenWFE
                 return
             end
 
+            #
+            # parent still present, reply to it
+
             reply(exp.parent_id, workitem)
         end
 
@@ -492,7 +514,10 @@ module OpenWFE
 
             onotify :update, flow_expression.fei, flow_expression
 
-            ldebug { "update() took #{t.duration} ms" }
+            ldebug do 
+                "update() took #{t.duration} ms  " +
+                "#{flow_expression.fei.to_debug_s}"
+            end
 
             flow_expression
         end
@@ -519,7 +544,7 @@ module OpenWFE
                         "'#{fei}' (#{fei.class})"
                 end
 
-                ldebug { "fetch() for  #{fei.to_debug_s}" }
+                #ldebug { "fetch() for  #{fei.to_debug_s}" }
 
                 return get_expression_storage()[fei], fei
             end
@@ -790,7 +815,7 @@ module OpenWFE
                 #    "param of class #{param.class.name}" 
                 #end
 
-                return param if param.is_a? ProgExpRepresentation
+                return param if param.is_a? SimpleExpRepresentation
                 return param.make if param.is_a? ProcessDefinition
                 return param.do_make if param.is_a? Class
 
@@ -829,17 +854,23 @@ module OpenWFE
             # Builds a FlowExpressionId instance for process being
             # launched.
             #
-            def new_fei (flow_url, flow_name, flow_revision, exp_name)
+            def new_fei (launchitem, flow_name, flow_revision, exp_name)
+
+                url = if launchitem
+                    launchitem.workflow_definition_url
+                else
+                    "no-url"
+                end
 
                 fei = FlowExpressionId.new
 
                 fei.owfe_version = OPENWFERU_VERSION
                 fei.engine_id = OpenWFE::stu get_engine.service_name
                 fei.initial_engine_id = OpenWFE::stu fei.engine_id
-                fei.workflow_definition_url = OpenWFE::stu flow_url
+                fei.workflow_definition_url = OpenWFE::stu url
                 fei.workflow_definition_name = OpenWFE::stu flow_name
                 fei.workflow_definition_revision = OpenWFE::stu flow_revision
-                fei.workflow_instance_id = get_wfid_generator.generate
+                fei.wfid = get_wfid_generator.generate launchitem
                 fei.expression_id = "0"
                 fei.expression_name = exp_name
                 return fei
@@ -849,10 +880,10 @@ module OpenWFE
             # Builds the RawExpression instance at the root of the flow
             # being launched.
             #
-            # The param can be a LaunchItem, an URI, anything accepted
-            # by the determine_representation() method.
+            # The param can be a template or a definition (anything
+            # accepted by the determine_representation() method).
             #
-            def build_raw_expression (url, param)
+            def build_raw_expression (launchitem, param)
 
                 procdef = determine_representation(param)
 
@@ -862,7 +893,7 @@ module OpenWFE
                 flow_revision = procdef.attributes['revision']
                 exp_name = procdef.name
 
-                fei = new_fei(url, flow_name, flow_revision, exp_name)
+                fei = new_fei(launchitem, flow_name, flow_revision, exp_name)
 
                 #puts procdef.raw_expression_class
                 #puts procdef.raw_expression_class.public_methods

data/lib/openwfe/expool/history.rb

@@ -48,7 +48,7 @@ require 'openwfe/rudefinitions'
 module OpenWFE
     
     #
-    # The base implementation for History modules
+    # A Mixin for history modules
     #
     module HistoryMixin
         include ServiceMixin, OwfeServiceLocator
@@ -69,14 +69,9 @@ module OpenWFE
     end
 
     #
-    # The simplest implementation, stores all history entries in memory.
-    #
-    # DO NOT USE IN PRODUCTION, it will trigger an 'out of memory' error
-    # sooner or later.
-    #
-    # Is only used for unit testing purposes.
+    # A base implementation for InMemoryHistory and FileHistory.
     #
-    class InMemoryHistory 
+    class BaseHistory 
         include HistoryMixin
 
         attr_reader :entries
@@ -85,15 +80,14 @@ module OpenWFE
 
             super()
 
-            @entries = []
-
             service_init(service_name, application_context)
         end
 
         def log (event, *args)
 
-            return if event == :stop
+            return if event == :update
             return if event == :reschedule
+            return if event == :stop
 
             msg = "#{Time.now.to_s} -- "
 
@@ -105,18 +99,74 @@ module OpenWFE
             #msg << " #{args[1].to_s}" \
             #    if args.length > 1
 
-            @entries << msg
+            @output << msg + "\n"
         end
+    end
 
+    #
+    # The simplest implementation, stores all history entries in memory.
+    #
+    # DO NOT USE IN PRODUCTION, it will trigger an 'out of memory' error
+    # sooner or later.
+    #
+    # Is only used for unit testing purposes.
+    #
+    class InMemoryHistory < BaseHistory
+
+        def initialize (service_name, application_context)
+            super
+
+            @output = []
+        end
+
+        #
+        # Returns the array of entries.
+        #
+        def entries
+            @output
+        end
+
+        #
+        # Returns all the entries as a String.
+        #
         def to_s
             s = ""
-            @entries.each do |entry|
+            @output.each do |entry|
                 s << entry.to_s
-                s << "\n"
             end
             s
         end
     end
 
+    #
+    # Simply dumps the history in the work directory in a file named 
+    # "history.log"
+    # Warning : no fancy rotation or compression implemented here.
+    #
+    class FileHistory < BaseHistory
+
+        def initialize (service_name, application_context)
+
+            super
+
+            @output = OpenWFE::get_work_directory + "/history.log"
+            @output = File.open(@output, "w+")
+
+            linfo { "new() outputting history to #{@output.path}" }
+        end
+
+        #
+        # Returns a handle on the output file instance used by this 
+        # FileHistory.
+        #
+        def output_file
+            @output
+        end
+
+        def stop
+            @output.close
+        end
+    end
+
 end