ruote 2.2.0 → 2.3.0

data/lib/ruote/part/rev_participant.rb

@@ -0,0 +1,178 @@
+#--
+# Copyright (c) 2005-2012, 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 'open-uri'
+
+require 'ruote/part/local_participant'
+
+
+module Ruote
+
+  #
+  # This participant was born out of a suggestion from Jan Topiński in
+  # http://groups.google.com/group/openwferu-users/browse_thread/thread/be20a5d861556fd8
+  #
+  # This participant is a gateway to code placed in a directory.
+  #
+  #   engine.register do
+  #     toto, Ruote::RevParticipant, :dir => 'participants/toto/'
+  #   end
+  #
+  # Then in the participants/toto/ dir :
+  #
+  #     /my_workflow__0.1__toto_0.6.rb
+  #       # participant toto, workflow 'my_workflow' with revision '0.1'
+  #     /my_workflow__toto.rb
+  #       # participant toto, workflow 'my_workflow' any revision
+  #     /toto_0.6.rb
+  #       # participant toto with rev '0.6', any workflow
+  #     /toto.rb
+  #       # participant toto, any rev, any workflow
+  #       # ...
+  #
+  # The scheme goes like :
+  #
+  #    /wf-name__wf-revision__participant-name__p-revision.rb
+  #
+  # The files themselves look like :
+  #
+  #   def consume(workitem)
+  #     workitem.fields['kilroy'] = 'was here'
+  #     reply_to_engine(workitem)
+  #   end
+  #
+  # The file directly contains the classical participant methods defined at the
+  # top level. #cancel, #accept?, #on_reply and of course #consume are OK.
+  #
+  #
+  # Maybe, look at the tests for more clues :
+  #
+  #   https://github.com/jmettraux/ruote/blob/master/test/functional/ft_57_rev_participant.rb
+  #
+  # *Note* : It's probably not the best participant in a distributed context, it
+  # grabs the code to execute from a directory. If you use it in a distributed
+  # context, you'll have to make sure to synchronize the directory to each host
+  # running a worker.
+  #
+  # *Warning* : this participant trusts the code it deals with, there is no
+  # security check.
+  #
+  class RevParticipant
+
+    include LocalParticipant
+
+    # TODO : how to deal with >= and ~> ?
+
+    def initialize(opts=nil)
+
+      @dir = opts['dir']
+
+      raise ArgumentError.new(
+        "missing option :dir for #{self.class}"
+      ) unless @dir
+    end
+
+    def on_workitem
+
+      Ruote.participant_send(
+        lookup_code,
+        [ :on_workitem, :consume ],
+        'workitem' => workitem)
+    end
+
+    def on_cancel
+
+      Ruote.participant_send(
+        lookup_code,
+        [ :on_cancel, :cancel ],
+        'fei' => fei, 'flavour' => flavour)
+    end
+
+    #--
+    #def accept?(workitem)
+    #  part = lookup_code
+    #  part.respond_to?(:accept?) ? part.accept?(workitem) : true
+    #end
+    #
+    # Can't do this at this level, since it isn't the rev_participant's
+    # own accept?, it has to go in lookup_code
+    #++
+
+    def on_reply
+
+      part = lookup_code
+
+      if part.respond_to?(:on_reply)
+        Ruote.participant_send(part, :on_reply, 'workitem' => workitem)
+      end
+    end
+
+    def rtimeout(workitem)
+
+      part = lookup_code
+
+      part.respond_to?(:rtimeout) ? part.rtimeout(workitem) : nil
+    end
+
+    protected
+
+    # Maybe "lookup_real_participant_code" would be a better name...
+    #
+    def lookup_code
+
+      wi = workitem
+
+      rev = wi.params['revision'] || wi.params['rev']
+
+      [
+        [ wi.wf_name, wi.wf_revision, wi.participant_name, rev ],
+        [ wi.wf_name, wi.wf_revision, wi.participant_name ],
+        [ wi.wf_name, '', wi.participant_name ],
+        [ wi.participant_name, rev ],
+        [ wi.participant_name ],
+      ].each do |fname|
+
+        fname = File.join(@dir, "#{fname.compact.join('__')}.rb")
+        next unless File.exist?(fname)
+
+        cpart = Class.new
+        cpart.send(:include, Ruote::LocalParticipant)
+        cpart.module_eval(File.read(fname))
+        part = cpart.new
+        part.context = @context
+
+        next if part.respond_to?(:accept?) and (not part.accept?(wi))
+
+        return part
+      end
+
+      raise ArgumentError.new(
+        "couldn't find code for participant #{wi.participant_name} " +
+        "in dir #{@dir}"
+      )
+    end
+  end
+end
+

data/lib/ruote/part/smtp_participant.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2011, Alain Hoang and John Mettraux.
+# Copyright (c) 2005-2012, Alain Hoang and John Mettraux.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -82,7 +82,7 @@ module Ruote
 
     def initialize(opts)
 
-      @opts = opts.inject({}) { |h, (k, v)| h[k.to_s] = v; h }
+      @opts = Ruote.keys_to_s(opts)
     end
 
     def consume(workitem)

data/lib/ruote/part/storage_participant.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2012, 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
@@ -55,8 +55,6 @@ module Ruote
     include LocalParticipant
     include Enumerable
 
-    attr_accessor :context
-
     def initialize(engine_or_options={}, options=nil)
 
       if engine_or_options.respond_to?(:context)
@@ -76,7 +74,10 @@ module Ruote
     #
     def do_not_thread; true; end
 
-    def consume(workitem)
+    # This is the method called by ruote when passing a workitem to
+    # this participant.
+    #
+    def on_workitem
 
       doc = workitem.to_h
 
@@ -90,19 +91,39 @@ module Ruote
 
       @context.storage.put(doc)
     end
-    alias :update :consume
 
-    # Removes the document/workitem from the storage
+    # Used by client code when "saving" a workitem (fields may have changed).
+    # Calling #update won't proceed the workitem.
+    #
+    # Returns nil in case of success, true if the workitem is already gone and
+    # the newer version of the workitem if the workitem changed in the mean
+    # time.
+    #
+    def update(workitem)
+
+      r = @context.storage.put(workitem.h)
+
+      r.is_a?(Hash) ? Ruote::Workitem.new(r) : r
+    end
+
+    # Removes the document/workitem from the storage.
+    #
+    # Warning: this method is called by the engine (worker), i.e. not by you.
     #
-    def cancel(fei, flavour)
+    def on_cancel
 
       doc = fetch(fei)
 
+      return unless doc
+
       r = @context.storage.delete(doc)
 
-      cancel(fei, flavour) if r != nil
+      on_cancel(fei, flavour) if r != nil
     end
 
+    # Given a fei (or its string version, a sid), returns the corresponding
+    # workitem (or nil).
+    #
     def [](fei)
 
       doc = fetch(fei)
@@ -110,31 +131,46 @@ module Ruote
       doc ? Ruote::Workitem.new(doc) : nil
     end
 
-    def fetch(fei)
+    alias by_fei []
 
-      hfei = Ruote::FlowExpressionId.extract_h(fei)
+    # Removes the workitem from the storage and replies to the engine.
+    #
+    def proceed(workitem)
 
-      @context.storage.get('workitems', to_id(hfei))
+      r = remove_workitem('proceed', workitem)
+
+      return proceed(workitem) if r != nil
+
+      workitem.h.delete('_rev')
+
+      reply_to_engine(workitem)
     end
 
-    # Removes the workitem from the in-memory hash and replies to the engine.
+    # Removes the workitem and hands it back to the flow with an error to
+    # raise for the participant expression that emitted the workitem.
     #
-    # TODO : should it raise if the workitem can't be found ?
-    # TODO : should it accept just the fei ?
-    #
-    def reply(workitem)
+    def flunk(workitem, err_class_or_instance, *err_arguments)
 
-      # TODO: change method name (receiver mess cleanup)
+      r = remove_workitem('reject', workitem)
 
-      doc = fetch(Ruote::FlowExpressionId.extract_h(workitem))
+      return flunk(workitem) if r != nil
 
-      r = @context.storage.delete(doc)
+      workitem.h.delete('_rev')
 
-      return reply(workitem) if r != nil
+      super(workitem, err_class_or_instance, *err_arguments)
+    end
 
-      workitem.h.delete('_rev')
+    # (soon to be removed)
+    #
+    def reply(workitem)
 
-      reply_to_engine(workitem)
+      puts '-' * 80
+      puts '*** WARNING : please use the Ruote::StorageParticipant#proceed(wi)'
+      puts '              instead of #reply(wi) which is deprecated'
+      #caller.each { |l| puts l }
+      puts '-' * 80
+
+      proceed(workitem)
     end
 
     # Returns the count of workitems stored in this participant.
@@ -155,7 +191,9 @@ module Ruote
     #
     def all(opts={})
 
-      fetch_all(opts).map { |hwi| Ruote::Workitem.new(hwi) }
+      res = fetch_all(opts)
+
+      res.is_a?(Array) ? res.map { |hwi| Ruote::Workitem.new(hwi) } : res
     end
 
     # A convenience method (especially when testing), returns the first
@@ -163,36 +201,31 @@ module Ruote
     #
     def first
 
-      hwi = fetch_all.first
-
-      hwi ? Ruote::Workitem.new(hwi) : nil
+      wi(fetch_all({}).first)
     end
 
     # Return all workitems for the specified wfid
     #
-    def by_wfid(wfid)
+    def by_wfid(wfid, opts={})
 
-      @context.storage.get_many('workitems', wfid).collect { |hwi|
-        Ruote::Workitem.new(hwi)
-      }
+      if @context.storage.respond_to?(:by_wfid)
+        return @context.storage.by_wfid('workitems', wfid, opts)
+      end
+
+      wis(@context.storage.get_many('workitems', wfid, opts))
     end
 
     # Returns all workitems for the specified participant name
     #
     def by_participant(participant_name, opts={})
 
-      hwis = if @context.storage.respond_to?(:by_participant)
+      return @context.storage.by_participant(
+        'workitems', participant_name, opts
+      ) if @context.storage.respond_to?(:by_participant)
 
-        @context.storage.by_participant('workitems', participant_name, opts)
-
-      else
-
-        fetch_all(opts).select { |wi|
-          wi['participant_name'] == participant_name
-        }
+      do_select(opts) do |hwi|
+        hwi['participant_name'] == participant_name
       end
-
-      hwis.collect { |hwi| Ruote::Workitem.new(hwi) }
     end
 
     # field : returns all the workitems with the given field name present.
@@ -204,21 +237,18 @@ module Ruote
     # CouchStorage), the others will load all the workitems and then filter
     # them.
     #
-    def by_field(field, value=nil)
-
-      hwis = if @context.storage.respond_to?(:by_field)
+    def by_field(field, value=nil, opts={})
 
-        @context.storage.by_field('workitems', field, value)
+      (value, opts = nil, value) if value.is_a?(Hash)
 
-      else
-
-        fetch_all.select { |hwi|
-          hwi['fields'].keys.include?(field) &&
-          (value.nil? || hwi['fields'][field] == value)
-        }
+      if @context.storage.respond_to?(:by_field)
+        return @context.storage.by_field('workitems', field, value, opts)
       end
 
-      hwis.collect { |hwi| Ruote::Workitem.new(hwi) }
+      do_select(opts) do |hwi|
+        hwi['fields'].keys.include?(field) &&
+        (value.nil? || hwi['fields'][field] == value)
+      end
     end
 
     # Queries the store participant for workitems.
@@ -242,7 +272,7 @@ module Ruote
     #
     def query(criteria)
 
-      cr = criteria.inject({}) { |h, (k, v)| h[k.to_s] = v; h }
+      cr = Ruote.keys_to_s(criteria)
 
       if @context.storage.respond_to?(:query_workitems)
         return @context.storage.query_workitems(cr)
@@ -254,25 +284,29 @@ module Ruote
       opts[:count] = cr.delete('count')
 
       wfid = cr.delete('wfid')
+
+      count = opts[:count]
+
       pname = cr.delete('participant_name') || cr.delete('participant')
+      opts.delete(:count) if pname
 
       hwis = wfid ?
         @context.storage.get_many('workitems', wfid, opts) : fetch_all(opts)
 
-      return hwis if opts[:count]
+      return hwis unless hwis.is_a?(Array)
 
-      hwis.select { |hwi|
+      hwis = hwis.select { |hwi|
         Ruote::StorageParticipant.matches?(hwi, pname, cr)
-      }.collect { |hwi|
-        Ruote::Workitem.new(hwi)
       }
+
+      count ? hwis.size : wis(hwis)
     end
 
     # Cleans this participant out completely
     #
     def purge!
 
-      fetch_all.each { |hwi| @context.storage.delete(hwi) }
+      fetch_all({}).each { |hwi| @context.storage.delete(hwi) }
     end
 
     # Used by #query when filtering workitems.
@@ -295,7 +329,7 @@ module Ruote
     #
     def per_participant
 
-      inject({}) { |h, wi| (h[wi.participant_name] ||= []) << wi; h }
+      each_with_object({}) { |wi, h| (h[wi.participant_name] ||= []) << wi }
     end
 
     # Mostly a test method. Returns a Hash were keys are participant names
@@ -304,15 +338,95 @@ module Ruote
     #
     def per_participant_count
 
-      per_participant.inject({}) { |h, (k, v)| h[k] = v.size; h }
+      per_participant.remap { |(k, v), h| h[k] = v.size }
+    end
+
+    # Claims a workitem. Returns the [updated] workitem if successful.
+    #
+    # Returns nil if the workitem is already reserved.
+    #
+    # Fails if the workitem can't be found, is gone, or got modified
+    # elsewhere.
+    #
+    # Here is a mini-diagram explaining the reserve/delegate/proceed flow:
+    #
+    #    in    delegate(nil)    delegate(other)
+    #    |    +---------------+ +------+
+    #    v    v               | |      v
+    #   +-------+  reserve   +----------+  proceed
+    #   | ready | ---------> | reserved | ---------> out
+    #   +-------+            +----------+
+    #
+    def reserve(workitem_or_fei, owner)
+
+      hwi = fetch(workitem_or_fei)
+
+      fail ArgumentError.new("workitem not found") if hwi.nil?
+
+      return nil if hwi['owner'] && hwi['owner'] != owner
+
+      hwi['owner'] = owner
+
+      r = @context.storage.put(hwi, :update_rev => true)
+
+      fail ArgumentError.new("workitem is gone") if r == true
+      fail ArgumentError.new("workitem got modified meanwhile") if r != nil
+
+      Workitem.new(hwi)
+    end
+
+    # Delegates a currently owned workitem to a new owner.
+    #
+    # Fails if the workitem can't be found, belongs to noone, or if the
+    # workitem passed as argument is out of date (got modified in the mean
+    # time).
+    #
+    # It's OK to delegate to nil, thus freeing the workitem.
+    #
+    # See #reserve for an an explanation of the reserve/delegate/proceed flow.
+    #
+    def delegate(workitem, new_owner)
+
+      hwi = fetch(workitem)
+
+      fail ArgumentError.new(
+        "workitem not found"
+      ) if hwi == nil
+
+      fail ArgumentError.new(
+        "cannot delegate, workitem doesn't belong to anyone"
+      ) if hwi['owner'] == nil
+
+      fail ArgumentError.new(
+        "cannot delegate, " +
+        "workitem owned by '#{hwi['owner']}', not '#{workitem.owner}'"
+      ) if hwi['owner'] != workitem.owner
+
+      hwi['owner'] = new_owner
+
+      r = @context.storage.put(hwi, :update_rev => true)
+
+      fail ArgumentError.new("workitem is gone") if r == true
+      fail ArgumentError.new("workitem got modified meanwhile") if r != nil
+
+      Workitem.new(hwi)
     end
 
     protected
 
+    # Fetches a workitem in its raw form (Hash).
+    #
+    def fetch(workitem_or_fei)
+
+      hfei = Ruote::FlowExpressionId.extract_h(workitem_or_fei)
+
+      @context.storage.get('workitems', to_id(hfei))
+    end
+
     # Fetches all the workitems. If there is a @store_name, will only fetch
     # the workitems in that store.
     #
-    def fetch_all(opts={})
+    def fetch_all(opts)
 
       @context.storage.get_many(
         'workitems',
@@ -320,6 +434,26 @@ module Ruote
         opts)
     end
 
+    # Given a few options and a block, returns all the workitems that match
+    # the block
+    #
+    def do_select(opts, &block)
+
+      skip = opts[:offset] || opts[:skip]
+      limit = opts[:limit]
+      count = opts[:count]
+
+      hwis = fetch_all({})
+      hwis = hwis.select(&block)
+
+      hwis = hwis[skip..-1] if skip
+      hwis = hwis[0, limit] if limit
+
+      return hwis.size if count
+
+      hwis.collect { |hwi| Ruote::Workitem.new(hwi) }
+    end
+
     # Computes the id for the document representing the document in the storage.
     #
     def to_id(fei)
@@ -332,6 +466,40 @@ module Ruote
 
       a.join('!')
     end
+
+    def wi(hwi)
+
+      hwi ? Ruote::Workitem.new(hwi) : nil
+    end
+
+    def wis(workitems_or_count)
+
+      workitems_or_count.is_a?(Array) ?
+        workitems_or_count.collect { |wi| Ruote::Workitem.new(wi) } :
+        workitems_or_count
+    end
+
+    def remove_workitem(action, workitem)
+
+      hwi = fetch(workitem)
+
+      fail ArgumentError.new(
+        "cannot #{action}, workitem not found"
+      ) if hwi == nil
+
+      fail ArgumentError.new(
+        "cannot #{action}, " +
+        "workitem is owned by '#{hwi['owner']}', not '#{workitem.owner}'"
+      ) if hwi['owner'] && hwi['owner'] != workitem.owner
+
+      r = @context.storage.delete(hwi)
+
+      fail ArgumentError.new(
+        "cannot #{action}, workitem is gone"
+      ) if r == true
+
+      r
+    end
   end
 end