ruote 0.9.20 → 2.1.1

data/examples/flickr_report.rb

@@ -0,0 +1,108 @@
+
+$:.unshift('lib')
+
+require 'rubygems'
+require 'ruote/engine' # sudo gem install ruote
+require 'atom/feed' # sudo gem install atom-tools
+require 'prawn' # sudo gem install prawn
+
+#
+# starting a transient engine (no need to make it persistent)
+
+engine = Ruote::Engine.new(:definition_in_launchitem_allowed => true)
+
+#
+# a process that fetches the latest pictures from flickr.com and submits
+# them concurrently to three users for review
+
+pdef = Ruote.process_definition :name => 'picture_acquisition' do
+  sequence do
+
+    get_pictures
+
+    concurrence :merge_type => 'mix' do
+      # pass the picture list to three users concurrently
+      # make sure to let their choice appear in the final workitem
+      # at the end of the concurrence
+
+      user_alice
+      user_bob
+      user_charly
+      user_doug
+    end
+
+    generate_result_pdf
+  end
+end
+
+#
+# fetching the flickr.com pictures via Atom
+
+engine.register_participant :get_pictures do |workitem|
+
+  feed = Atom::Feed.new(
+    "http://api.flickr.com/services/feeds/photos_public.gne"+
+    "?tags=#{workitem.fields['tags'].join(',')}&format=atom")
+  feed.update!
+
+  workitem.fields['pictures'] = feed.entries.inject([]) do |a, entry|
+    a << [
+      entry.title,
+      entry.authors.first.name,
+      entry.links.last.href
+    ]
+  end
+end
+
+#
+# the users (well, here, just randomly picking a picture)
+
+engine.register_participant 'user_.*' do |workitem|
+
+  workitem.fields[workitem.participant_name] =
+    workitem.fields['pictures'][(rand * workitem.fields['pictures'].length).to_i]
+end
+
+#
+# the final participant, generates an "out.pdf" file in the current dir
+
+engine.register_participant :generate_result_pdf do |workitem|
+
+  entries = workitem.fields.inject([]) do |a, (k, v)|
+    a << [ k, v.last ] if k.match(/^user\_.+$/)
+    a
+  end
+
+  entries.each_with_index do |entry, i|
+    entry << "pic#{i}.jpg"
+    `curl #{entry[1]} > #{entry[2]}`
+    puts "..got #{entry[0]} / #{entry[2]}"
+  end
+
+  Prawn::Document.generate('out.pdf') do
+    font 'Helvetica'
+    entries.each do |entry|
+      text entry[0]
+      image entry[2], :width => 200
+    end
+  end
+  puts ".generated out.pdf"
+
+  `rm pic*.jpg`
+end
+
+#
+# launching the process, requesting pictures tagged 'cat' and 'fish'
+
+li = Ruote::Launchitem.new(pdef)
+li.fields['tags'] = [ 'cat', 'fish' ]
+
+fei = engine.launch(li)
+
+#
+# workflow engines are asynchronous beasts, have to wait for them
+# (here we wait for a particular process)
+
+outcome = engine.wait_for(fei)
+#p outcome
+

data/examples/ruote_quickstart.rb

@@ -0,0 +1,42 @@
+
+$:.unshift('lib') # running from ruote/ probably
+
+require 'rubygems'
+require 'ruote'
+require 'ruote/storage/fs_storage'
+
+# preparing the engine
+
+engine = Ruote::Engine.new(
+  Ruote::Worker.new(
+    Ruote::FsStorage.new("ruote_work")))
+    #Ruote::HashStorage.new))
+
+# registering participants
+
+engine.register_participant :alpha do |workitem|
+  workitem.fields['message'] = { 'text' => 'hello !', 'author' => 'Alice' }
+end
+
+engine.register_participant :bravo do |workitem|
+  puts "I received a message from #{workitem.fields['message']['author']}"
+end
+
+# defining a process
+
+pdef = Ruote.process_definition :name => 'test' do
+  sequence do
+    participant :alpha
+    participant :bravo
+  end
+end
+
+# launching, creating a process instance
+
+wfid = engine.launch(pdef)
+
+engine.wait_for(wfid)
+  # blocks current thread until our process instance terminates
+
+# => 'I received a message from Alice'
+

data/examples/web_first_page.rb

@@ -0,0 +1,57 @@
+
+require 'ruote'
+
+pdef = Ruote.process_definition :name => 'work' do
+  cursor do
+    concurrence do
+      reviewer1
+      reviewer2
+    end
+    editor
+    rewind :if => '${not_ok}' # back to the reviewers if editor not happy
+    publish # the document
+  end
+end
+
+# engine
+
+require 'ruote/storage/fs_storage'
+
+engine = Ruote::Engine.new(Ruote::Worker.new(Ruote::FsStorage.new('work')))
+
+# participants
+
+engine.register_participant 'reviewer.+' do |workitem|
+  puts "reviewing document #{workitem.fields['doc_url']}"
+  print "approve ?"
+  workitem.fields["#{workitem.participant_name}_reply"] = gets
+end
+
+engine.register_participant 'editor' do |workitem|
+  puts "doc : #{workitem.fields['doc_url']}"
+  puts "reviewers approval :"
+  workitem.fields.entries.each do |k, v|
+    puts "#{k} : #{v}" if k.match(/\_reply$/)
+  end
+  print "should we publish ?"
+  workitem.fields['not_ok'] = (gets.strip == 'no')
+end
+
+engine.register_participant 'publish' do |workitem|
+  PublicationService.post(workitem.fields['doc_url'])
+end
+
+wfid0 = engine.launch(pdef, 'doc_url' => 'http://en.wikipedia.org/wiki/File:Bundesbrief.jpg')
+wfid1 = engine.launch(pdef, 'doc_url' => 'http://en.wikipedia.org/wiki/File:Constitution_Pg1of4_AC.jpg')
+
+# querying
+
+[ wfid0, wfid1 ].each do |wfid|
+  ps = engine.process(wfid)
+  puts "errors for #{wfid} ? #{ps.errors.size > 0}"
+end
+
+# cancelling a process instance
+
+engine.cancel_process(wfid1)
+

data/lib/ruote.rb

@@ -0,0 +1,6 @@
+
+require 'ruote/storage/hash_storage'
+require 'ruote/worker'
+require 'ruote/engine'
+require 'ruote/parser/ruby_dsl'
+

data/lib/ruote/context.rb

@@ -0,0 +1,136 @@
+#--
+# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+#
+# 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:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# 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.
+#
+# Made in Japan.
+#++
+
+require 'ruote/util/misc'
+
+
+module Ruote
+
+  #
+  # A sort of internal registry, via a shared instance of this class, the worker
+  # and the engine can access subservices like parser, treechecker,
+  # wfid_generator and so on.
+  #
+  class Context
+
+    attr_reader :storage
+    attr_accessor :worker
+    attr_accessor :engine
+
+    def initialize (storage, worker_or_engine)
+
+      @storage = storage
+      @conf = default_conf.merge(@storage.get_configuration('engine') || {})
+
+      @worker, @engine = if worker_or_engine.kind_of?(Ruote::Engine)
+        [ worker_or_engine.worker, worker_or_engine ]
+      else
+        [ worker_or_engine, nil ]
+      end
+
+      initialize_services
+    end
+
+    def [] (key)
+
+      @conf[key]
+    end
+
+    def []= (key, value)
+
+      @conf[key] = value
+    end
+
+    def keys
+
+      @conf.keys
+    end
+
+    def add_service (key, *args)
+
+      path, klass, opts = args
+
+      key = "s_#{key}" unless key.match(/^s\_/)
+
+      if klass
+
+        require(path)
+
+        aa = [ self ]
+        aa << opts if opts
+
+        @conf[key] = Ruote.constantize(klass).new(*aa)
+      else
+
+        @conf[key] = path
+      end
+
+      self.class.class_eval %{ def #{key[2..-1]}; @conf['#{key}']; end }
+    end
+
+    def shutdown
+
+      @storage.shutdown if @storage.respond_to?(:shutdown)
+      @worker.shutdown if @worker
+
+      @conf.values.each do |s|
+
+        s.shutdown if s.respond_to?(:shutdown)
+      end
+    end
+
+    protected
+
+    def initialize_services
+
+      @conf.keys.each do |key|
+
+        next unless key.match(/^s\_/)
+
+        add_service(key, *@conf[key])
+      end
+    end
+
+    def default_conf
+
+      { 's_wfidgen' => [
+          'ruote/id/mnemo_wfid_generator', 'Ruote::MnemoWfidGenerator' ],
+        's_parser' => [
+          'ruote/parser', 'Ruote::Parser' ],
+        's_treechecker' => [
+          'ruote/util/treechecker', 'Ruote::TreeChecker' ],
+        's_expmap' => [
+           'ruote/exp/expression_map', 'Ruote::ExpressionMap' ],
+        's_tracker' => [
+          'ruote/evt/tracker', 'Ruote::Tracker' ],
+        's_plist' => [
+          'ruote/part/participant_list', 'Ruote::ParticipantList' ],
+        's_dispatch_pool' => [
+          'ruote/part/dispatch_pool', 'Ruote::DispatchPool' ],
+        's_logger' => [
+          'ruote/log/wait_logger', 'Ruote::WaitLogger' ] }
+    end
+  end
+end
+

data/lib/ruote/engine.rb

@@ -0,0 +1,339 @@
+#--
+# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+#
+# 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:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# 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.
+#
+# Made in Japan.
+#++
+
+require 'ruote/context'
+require 'ruote/engine/process_status'
+require 'ruote/receiver/base'
+
+
+module Ruote
+
+  class Engine
+
+    include ReceiverMixin
+
+    attr_reader :storage
+    attr_reader :worker
+    attr_reader :context
+    attr_reader :variables
+
+    def initialize (worker_or_storage, run=true)
+
+      if worker_or_storage.respond_to?(:context)
+
+        @worker = worker_or_storage
+        @storage = @worker.storage
+        @context = @worker.context
+        @context.engine = self
+      else
+
+        @worker = nil
+        @storage = worker_or_storage
+        @context = Ruote::Context.new(self)
+      end
+
+      @variables = EngineVariables.new(@storage)
+
+      @worker.run_in_thread if @worker && run
+    end
+
+    def launch (process_definition, fields={}, variables={})
+
+      wfid = @context.wfidgen.generate
+
+      @storage.put_msg(
+        'launch',
+        'wfid' => wfid,
+        'tree' => @context.parser.parse(process_definition),
+        'workitem' => { 'fields' => fields },
+        'variables' => variables)
+
+      wfid
+    end
+
+    def cancel_process (wfid)
+
+      @storage.put_msg('cancel_process', 'wfid' => wfid)
+    end
+
+    def kill_process (wfid)
+
+      @storage.put_msg('kill_process', 'wfid' => wfid)
+    end
+
+    def cancel_expression (fei)
+
+      fei = fei.to_h if fei.respond_to?(:to_h)
+      @storage.put_msg('cancel', 'fei' => fei)
+    end
+
+    def kill_expression (fei)
+
+      fei = fei.to_h if fei.respond_to?(:to_h)
+      @storage.put_msg('cancel', 'fei' => fei, 'flavour' => 'kill')
+    end
+
+    # Replays at a given error (hopefully you fixed the cause of the error
+    # before replaying...)
+    #
+    def replay_at_error (err)
+
+      msg = err.msg.dup
+      action = msg.delete('action')
+
+      msg['replay_at_error'] = true
+        # just an indication
+
+      if msg['tree'] && fei = msg['fei']
+        #
+        # nukes the expression in case of [re]apply
+        #
+        exp = Ruote::Exp::FlowExpression.fetch(@context, fei)
+        exp.unpersist_or_raise if exp
+      end
+
+      #@storage.delete(err.to_h) # remove error
+        #
+        # done when the expression gets deleted
+        #
+        # but
+        #
+        # is there a case, 5 lines above, where there is no expression
+        # to delete ?
+
+      @storage.put_msg(action, msg) # trigger replay
+    end
+
+    # Re-applies an expression (given via its FlowExpressionId).
+    #
+    # That will cancel the expression and, once the cancel operation is over
+    # (all the children have been cancelled), the expression will get
+    # re-applied.
+    #
+    def re_apply (fei)
+
+      @context.storage.put_msg('cancel', 'fei' => fei.to_h, 're_apply' => true)
+    end
+
+    # Returns a ProcessStatus instance describing the current status of
+    # a process instance.
+    #
+    def process (wfid)
+
+      exps = @storage.get_many('expressions', /#{wfid}$/)
+
+      return nil if exps.size < 1
+
+      ProcessStatus.new(
+        @context, exps, @storage.get_many('errors', /#{wfid}$/))
+    end
+
+    # Returns an array of ProcessStatus instances.
+    #
+    # WARNING : this is an expensive operation.
+    #
+    def processes
+
+      exps = @storage.get_many('expressions')
+      errs = @storage.get_many('errors')
+
+      by_wfid = {}
+
+      exps.each do |exp|
+        (by_wfid[exp['fei']['wfid']] ||= [ [], [] ]).first << exp
+      end
+      errs.each do |err|
+        (by_wfid[err['msg']['fei']['wfid']] ||= [ [], [] ]).last << err
+      end
+
+      by_wfid.values.collect { |xs, rs| ProcessStatus.new(@context, xs, rs) }
+    end
+
+    def shutdown
+
+      @context.shutdown
+    end
+
+    # This method expects there is a logger with a wait_for method in the
+    # context, else it will raise an exception.
+    #
+    # This method is only useful for test/quickstart/examples environments.
+    #
+    #   engine.wait_for(:alpha)
+    #     # will make the current thread block until a workitem is delivered
+    #     # to the participant named 'alpha'
+    #
+    #   engine.wait_for('123432123-9043')
+    #     # will make the current thread block until the processed whose
+    #     # wfid is given (String) terminates or produces an error.
+    #
+    #   engine.wait_for(5)
+    #     # will make the current thread block until 5 messages have been
+    #     # processed on the workqueue...
+    #
+    def wait_for (item)
+
+      logger = @context['s_logger']
+
+      raise(
+        "can't wait_for, there is no logger that responds to that call"
+      ) unless logger.respond_to?(:wait_for)
+
+      logger.wait_for(item)
+    end
+
+    # Loads and parses the process definition at the given path.
+    #
+    def load_definition (path)
+
+      @context.parser.parse(path)
+    end
+
+    # Registers a participant in the engine. Returns the participant instance.
+    #
+    # Some examples :
+    #
+    #   require 'ruote/part/hash_participant'
+    #   alice = engine.register_participant 'alice', Ruote::HashParticipant
+    #     # register an in-memory (hash) store for Alice's workitems
+    #
+    #   engine.register_participant 'compute_sum' do |wi|
+    #     wi.fields['sum'] = wi.fields['articles'].inject(0) do |s, (c, v)|
+    #       s + c * v # sum + count * value
+    #     end
+    #     # a block participant implicitely replies to the engine immediately
+    #   end
+    #
+    #   class MyParticipant
+    #     def initialize (name)
+    #       @name = name
+    #     end
+    #     def consume (workitem)
+    #       workitem.fields['rocket_name'] = @name
+    #       send_to_the_moon(workitem)
+    #     end
+    #     def cancel (fei, flavour)
+    #       # do nothing
+    #     end
+    #   end
+    #   engine.register_participant /^moon-.+/, MyParticipant.new('Saturn-V')
+    #
+    #
+    # == passing a block to a participant
+    #
+    # Usually only the BlockParticipant cares about being passed a block :
+    #
+    #   engine.register_participant 'compute_sum' do |workitem|
+    #     workitem.fields['kilroy'] = 'was here'
+    #   end
+    #
+    # But it's OK to pass a block to a custom participant :
+    #
+    #   require 'ruote/part/local_participant'
+    #
+    #   class MyParticipant
+    #     include Ruote::LocalParticipant
+    #     def initialize (opts)
+    #       @name = opts[:name]
+    #       @block = opts[:block]
+    #     end
+    #     def consume (workitem)
+    #       workitem.fields['prestamp'] = Time.now
+    #       workitem.fields['author'] = @name
+    #       @block.call(workitem)
+    #       reply_to_engine(workitem)
+    #     end
+    #   end
+    #
+    #   engine.register_participant 'al', MyParticipant, :name => 'toto' do |wi|
+    #     wi.fields['nada'] = surf
+    #   end
+    #
+    # The block is available under the :block option.
+    #
+    def register_participant (regex, participant=nil, opts={}, &block)
+
+      pa = @context.plist.register(regex, participant, opts, block)
+
+      @context.storage.put_msg(
+        'participant_registered',
+        'regex' => regex.to_s,
+        'engine_worker_only' => (pa != nil))
+
+      pa
+    end
+
+    # Removes/unregisters a participant from the engine.
+    #
+    def unregister_participant (name_or_participant)
+
+      re = @context.plist.unregister(name_or_participant)
+
+      raise(ArgumentError.new('participant not found')) unless re
+
+      @context.storage.put_msg(
+        'participant_unregistered',
+        'regex' => re.to_s)
+    end
+
+    # Adds a service locally (will not get propagated to other workers).
+    #
+    #   tracer = Tracer.new
+    #   @engine.add_service('tracer', tracer)
+    #
+    # or
+    #
+    #   @engine.add_service('tracer', 'ruote/exp/tracer', 'Ruote::Exp::Tracer')
+    #
+    def add_service (name, path_or_instance, classname=nil, opts=nil)
+
+      @context.add_service(name, path_or_instance, classname, opts)
+    end
+  end
+
+  #
+  # A wrapper class giving easy access to engine variables.
+  #
+  # There is one instance of this class for an Engine instance. It is
+  # returned when calling Engine#variables.
+  #
+  class EngineVariables
+
+    def initialize (storage)
+
+      @storage = storage
+    end
+
+    def [] (k)
+
+      @storage.get_engine_variable(k)
+    end
+
+    def []= (k, v)
+
+      @storage.put_engine_variable(k, v)
+    end
+  end
+end
+