ruote 2.1.9 → 2.1.10

data/lib/ruote/part/participant_list.rb

@@ -93,8 +93,9 @@ module Ruote
 
       else
 
-        return Ruote::StorageParticipant.new(@context) \
-          if entry.last.first == 'Ruote::StorageParticipant'
+        if entry.last.first == 'Ruote::StorageParticipant'
+          return Ruote::StorageParticipant.new(@context)
+        end
 
         nil
       end
@@ -110,8 +111,9 @@ module Ruote
       code = nil
       entry = nil
 
-      name_or_participant = name_or_participant.to_s \
-        if name_or_participant.is_a?(Symbol)
+      if name_or_participant.is_a?(Symbol)
+        name_or_participant = name_or_participant.to_s
+      end
 
       if name_or_participant.is_a?(String)
 
@@ -160,12 +162,12 @@ module Ruote
       end
     end
 
-    def lookup (participant_name)
+    def lookup (participant_name, opts={})
 
       pi = lookup_info(participant_name)
 
       return nil unless pi
-      return pi unless pi.is_a?(Array)
+      return opts[:on_reply] ? nil : pi unless pi.is_a?(Array)
 
       class_name, options = pi
 
@@ -173,8 +175,17 @@ module Ruote
         require(rp)
       end
 
-      pa = Ruote.constantize(class_name).new(options)
+      pa_class = Ruote.constantize(class_name)
+      pa_m = pa_class.instance_methods
+
+      return nil if opts[:on_reply] && ! (
+        pa_m.include?(:on_reply) || pa_m.include?('on_reply'))
 
+      pa = if pa_class.instance_method(:initialize).arity > 0
+        pa_class.new(options)
+      else
+        pa_class.new
+      end
       pa.context = @context if pa.respond_to?(:context=)
 
       pa

data/lib/ruote/part/storage_participant.rb

@@ -96,7 +96,7 @@ module Ruote
     #
     def cancel (fei, flavour)
 
-      doc = fetch(fei.to_h)
+      doc = fetch(fei)
 
       r = @context.storage.delete(doc)
 
@@ -112,16 +112,18 @@ module Ruote
 
     def fetch (fei)
 
-      fei = fei.to_h if fei.respond_to?(:to_h)
+      hfei = Ruote::FlowExpressionId.extract_h(fei)
 
-      @context.storage.get('workitems', to_id(fei))
+      @context.storage.get('workitems', to_id(hfei))
     end
 
     # Removes the workitem from the in-memory hash and replies to the engine.
     #
     def reply (workitem)
 
-      doc = fetch(workitem.fei.to_h)
+      # TODO: change method name (receiver mess cleanup)
+
+      doc = fetch(Ruote::FlowExpressionId.extract_h(workitem))
 
       r = @context.storage.delete(doc)
 
@@ -237,8 +239,9 @@ module Ruote
 
       cr = criteria.inject({}) { |h, (k, v)| h[k.to_s] = v; h }
 
-      return @context.storage.query_workitems(cr) \
-        if @context.storage.respond_to?(:query_workitems)
+      return @context.storage.query_workitems(cr).collect { |h|
+        Ruote::Workitem.new(h)
+      } if @context.storage.respond_to?(:query_workitems)
 
       offset = cr.delete('offset')
       limit = cr.delete('limit')

data/lib/ruote/receiver/base.rb

@@ -29,20 +29,19 @@ module Ruote
   # The core methods for the Receiver class (sometimes a Mixin is easier
   # to integrate).
   #
-  # (The engine itself includes this mixin)
+  # (The engine itself includes this mixin, the LocalParticipant module
+  # includes it as well).
   #
   module ReceiverMixin
 
-    def receive (item)
-
-      reply(item)
-    end
-
-    def reply (workitem)
+    # This method pipes back a workitem into the engine, letting it resume
+    # in its flow, hopefully.
+    #
+    def receive (workitem)
 
       workitem = workitem.to_h if workitem.respond_to?(:to_h)
 
-      @storage.put_msg(
+      @context.storage.put_msg(
         'receive',
         'fei' => workitem['fei'],
         'workitem' => workitem,
@@ -50,10 +49,108 @@ module Ruote
         'receiver' => sign)
     end
 
+    # Given a process definitions and optional initial fields and variables,
+    # launches a new process instance.
+    #
+    # This method is mostly used from the Ruote::Engine class (which includes
+    # this mixin).
+    #
+    def launch (process_definition, fields={}, variables={})
+
+      wfid = @context.wfidgen.generate
+
+      @context.storage.put_msg(
+        'launch',
+        'wfid' => wfid,
+        'tree' => @context.parser.parse(process_definition),
+        'workitem' => { 'fields' => fields },
+        'variables' => variables)
+
+      wfid
+    end
+
+    # Wraps a call to receive(workitem)
+    #
+    # Not aliasing so that if someone changes the receive implementation,
+    # reply is affected as well.
+    #
+    def reply (workitem)
+
+      receive (workitem)
+    end
+
+    # Wraps a call to receive(workitem)
+    #
+    # Not aliasing so that if someone changes the receive implementation,
+    # reply_to_engine is affected as well.
+    #
+    def reply_to_engine (workitem)
+
+      receive (workitem)
+    end
+
+    # A receiver signs a workitem when it comes back.
+    #
+    # Not used much as of now.
+    #
     def sign
 
       self.class.to_s
     end
+
+    protected
+
+    # Convenience method, fetches the flow expression (ParticipantExpression)
+    # that emitted that workitem.
+    #
+    def fetch_flow_expression (workitem)
+
+      Ruote::Exp::FlowExpression.fetch(@context, workitem.fei.to_h)
+    end
+
+    # Stashes values in the participant expression (in the storage).
+    #
+    #   put(workitem.fei, 'key' => 'value', 'colour' => 'blue')
+    #
+    # Remember that keys/values must be serializable in JSON.
+    #
+    # put & get are useful for a participant that needs to communicate
+    # between its consume and its cancel.
+    #
+    # See the thread at
+    # http://groups.google.com/group/openwferu-users/t/2e6a95708c10847b for the
+    # justification.
+    #
+    def put (fei, hash)
+
+      fexp = Ruote::Exp::FlowExpression.fetch(@context, fei.to_h)
+
+      (fexp.h['stash'] ||= {}).merge!(hash)
+
+      fexp.persist_or_raise
+    end
+
+    # Fetches back a stashed value.
+    #
+    #   get(fei, 'colour')
+    #     # => 'blue'
+    #
+    # To return the whole stash
+    #
+    #   get(fei)
+    #     # => { 'colour' => 'blue' }
+    #
+    # put & get are useful for a participant that needs to communicate
+    # between its consume and its cancel.
+    #
+    def get (fei, key=nil)
+
+      fexp = Ruote::Exp::FlowExpression.fetch(@context, fei.to_h)
+
+      stash = fexp.h['stash'] rescue {}
+
+      key ? stash[key] : stash
+    end
   end
 
   #
@@ -63,9 +160,11 @@ module Ruote
   class Receiver
     include ReceiverMixin
 
-    def initialize (storage, options={})
+    # Accepts context, worker, engine or storage as first argument.
+    #
+    def initialize (cwes, options={})
 
-      @storage = storage
+      @context = cwes.context
       @options = options
     end
   end

data/lib/ruote/storage/base.rb

@@ -32,6 +32,24 @@ module Ruote
   #
   module StorageBase
 
+    def context
+
+      @context ||= Ruote::Context.new(self)
+    end
+
+    def context= (c)
+
+      @context = c
+    end
+
+    # Attempts to delete a document, returns true if the deletion
+    # succeeded. This is used with msgs to reserve work on them.
+    #
+    def reserve (doc)
+
+      delete(doc).nil?
+    end
+
     #--
     # configurations
     #++
@@ -47,28 +65,16 @@ module Ruote
 
     def put_msg (action, options)
 
-      # merge! is way faster than merge (no object creation probably)
-
-      @counter ||= 0
-
-      t = Time.now.utc
-      ts = "#{t.strftime('%Y-%m-%d')}!#{t.to_i}.#{'%06d' % t.usec}"
-      _id = "#{$$}!#{Thread.current.object_id}!#{ts}!#{'%03d' % @counter}"
-
-      @counter = (@counter + 1) % 1000
-        # some platforms (windows) have shallow usecs, so adding that counter...
-
-      msg = options.merge!('type' => 'msgs', '_id' => _id, 'action' => action)
-
-      msg.delete('_rev')
-        # in case of message replay
+      msg = prepare_msg_doc(action, options)
 
       put(msg)
+
       #put(msg, :update_rev => true)
-      #(@local_msgs ||= []) << options
+      #(@local_msgs ||= []) << Ruote.fulldup(msg)
     end
 
     #def get_local_msgs
+    #  p @local_msgs
     #  if @local_msgs
     #    r = @local_msgs
     #    @local_msgs = nil
@@ -87,6 +93,11 @@ module Ruote
       }
     end
 
+    def empty? (type)
+
+      (get_many(type) == [])
+    end
+
     #--
     # expressions
     #++
@@ -116,6 +127,9 @@ module Ruote
 
     def get_schedules (delta, now)
 
+      # TODO : bring that 'optimization' back in,
+      #        maybe every minute, if min != last_min ...
+
       #if delta < 1.0
       #  at = now.strftime('%Y%m%d%H%M%S')
       #  get_many('schedules', /-#{at}$/)
@@ -133,33 +147,12 @@ module Ruote
 
     def put_schedule (flavour, owner_fei, s, msg)
 
-      at = if s.is_a?(Time) # at or every
-        s
-      elsif Ruote.is_cron_string(s) # cron
-        Rufus::CronLine.new(s).next_time(Time.now + 1)
-      else # at or every
-        Ruote.s_to_at(s)
-      end
-      at = at.utc
-
-      if at <= Time.now.utc && flavour == 'at'
-        put_msg(msg.delete('action'), msg)
-        return
+      if doc = prepare_schedule_doc(flavour, owner_fei, s, msg)
+        put(doc)
+        return doc['_id']
       end
 
-      sat = at.strftime('%Y%m%d%H%M%S')
-      i = "#{flavour}-#{Ruote.to_storage_id(owner_fei)}-#{sat}"
-
-      put(
-        '_id' => i,
-        'type' => 'schedules',
-        'flavour' => flavour,
-        'original' => s,
-        'at' => Ruote.time_to_utc_s(at),
-        'owner' => owner_fei,
-        'msg' => msg)
-
-      i
+      nil
     end
 
     def delete_schedule (schedule_id)
@@ -185,8 +178,92 @@ module Ruote
       put_engine_variable(k, v) unless put(vars).nil?
     end
 
+    #--
+    # migrations
+    #++
+
+    # Copies the content of this storage into a target storage.
+    #
+    # Of course, the target storage may be a different implementation.
+    #
+    def copy_to (target, opts={})
+
+      counter = 0
+
+      %w[
+        configurations errors expressions msgs schedules variables workitems
+      ].each do |type|
+
+        get_many(type).each do |item|
+
+          item.delete('_rev')
+          target.put(item)
+
+          counter += 1
+          puts("  #{type}/#{item['_id']}") if opts[:verbose]
+        end
+      end
+
+      counter
+    end
+
     protected
 
+    # Used by put_msg
+    #
+    def prepare_msg_doc (action, options)
+
+      # merge! is way faster than merge (no object creation probably)
+
+      @counter ||= 0
+
+      t = Time.now.utc
+      ts = "#{t.strftime('%Y-%m-%d')}!#{t.to_i}.#{'%06d' % t.usec}"
+      _id = "#{$$}!#{Thread.current.object_id}!#{ts}!#{'%03d' % @counter}"
+
+      @counter = (@counter + 1) % 1000
+        # some platforms (windows) have shallow usecs, so adding that counter...
+
+      msg = options.merge!('type' => 'msgs', '_id' => _id, 'action' => action)
+
+      msg.delete('_rev')
+        # in case of message replay
+
+      msg
+    end
+
+    # Used by put_schedule
+    #
+    def prepare_schedule_doc (flavour, owner_fei, s, msg)
+
+      at = if s.is_a?(Time) # at or every
+        s
+      elsif Ruote.is_cron_string(s) # cron
+        Rufus::CronLine.new(s).next_time(Time.now + 1)
+      else # at or every
+        Ruote.s_to_at(s)
+      end
+      at = at.utc
+
+      if at <= Time.now.utc && flavour == 'at'
+        put_msg(msg.delete('action'), msg)
+        return false
+      end
+
+      sat = at.strftime('%Y%m%d%H%M%S')
+      i = "#{flavour}-#{Ruote.to_storage_id(owner_fei)}-#{sat}"
+
+      {
+        '_id' => i,
+        'type' => 'schedules',
+        'flavour' => flavour,
+        'original' => s,
+        'at' => Ruote.time_to_utc_s(at),
+        'owner' => owner_fei,
+        'msg' => msg
+      }
+    end
+
     def get_engine_variables
 
       get('variables', 'variables') || {