ruote 2.2.0 → 2.3.0

data/lib/ruote/reader/ruby_dsl.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
@@ -22,6 +22,7 @@
 # Made in Japan.
 #++
 
+require 'sourcify'
 require 'ruote/util/ometa'
 
 
@@ -92,6 +93,10 @@ module Ruote
     RubyDsl.create_branch('x', {}, &block).last.first
   end
 
+  class << self
+    alias tree to_tree
+  end
+
   # :nodoc:
   #
   module RubyDsl
@@ -120,18 +125,18 @@ module Ruote
 
       name = name[1..-1] while name[0, 1] == '_'
 
-      h = attributes.inject({}) { |h1, a|
+      h = attributes.each_with_object({}) { |a, h1|
 
-        a.is_a?(Hash) ? h1.merge!(a) : h1[a] = nil
+        if a.is_a?(Hash)
+          h1.merge!(a)
+        else
+          h1[a] = nil
+        end
 
-        h1
-
-      }.inject({}) { |h1, (k, v)|
+      }.remap { |(k, v), h1|
 
         k = k.is_a?(Regexp) ? k.inspect : k.to_s
         h1[k] = to_json(v)
-
-        h1
       }
 
       c = BranchContext.new(name, h)
@@ -146,10 +151,40 @@ module Ruote
         when Symbol; v.to_s
         when Regexp; v.inspect
         when Array; v.collect { |e| to_json(e) }
-        when Hash; v.inject({}) { |h, (k, v)| h[k.to_s] = to_json(v); h }
+        when Hash; v.remap { |(k, v), h| h[to_json(k)] = to_json(v) }
+        when Proc; v.to_raw_source + "\n"
         else v
       end
     end
   end
+
+  #
+  # The same .read and .understands? method as the other readers are found here.
+  #
+  module RubyReader
+
+    # Returns true if s seems to contain a Ruby process definition
+    #
+    def self.understands?(s)
+
+      s.match(
+        /\bRuote\.(process_definition|workflow_definition|define)\b/
+      ) != nil
+    end
+
+    # Evaluates the ruby string in the code, but at fist, thanks to the
+    # treechecker, makes sure it doesn't code malicious ruby code (at least
+    # tries very hard).
+    #
+    def self.read(s, treechecker)
+
+      treechecker.definition_check(s)
+      eval(s)
+
+    rescue SyntaxError => se
+      #p se
+      raise ArgumentError.new("Ruby syntax error : #{se.message}")
+    end
+  end
 end
 

data/lib/ruote/reader/xml.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
@@ -33,6 +33,13 @@ module Ruote
   #
   module XmlReader
 
+    # Returns true if the string seems to be an XML string.
+    #
+    def self.understands?(s)
+
+      !! s.strip.match(/<.+>/)
+    end
+
     #
     # A helper class to store the temporary tree while it gets read.
     #
@@ -40,14 +47,11 @@ module Ruote
 
       attr_reader :parent, :attributes, :children
 
-      def initialize(parent, name, attributes)
+      def initialize(parent, name, atts)
 
         @parent = parent
         @name = name
-        @attributes = attributes.inject({}) { |h, (k, v)|
-          h[k.gsub(/-/, '_')] = v
-          h
-        }
+        @attributes = atts.remap { |(k, v), h| h[k.gsub(/-/, '_')] = v }
         @children = []
 
         parent.children << self if parent
@@ -59,10 +63,9 @@ module Ruote
       end
     end
 
-    #
     # Parses the XML string into a process definition tree (array of arrays).
     #
-    def self.read(s)
+    def self.read(s, opt=nil)
 
       parser = REXML::Parsers::SAX2Parser.new(s)
 

data/lib/ruote/receiver/base.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
@@ -29,7 +29,7 @@ module Ruote
   # The core methods for the Receiver class (sometimes a Mixin is easier
   # to integrate).
   #
-  # (The engine itself includes this mixin, the LocalParticipant module
+  # (The dashboard itself includes this mixin, the LocalParticipant module
   # includes it as well).
   #
   module ReceiverMixin
@@ -49,11 +49,68 @@ module Ruote
         'receiver' => sign)
     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
+
+    # Can be used to raise an error in the workflow instance.
+    #
+    # Can be called either with an error class and arguments, either with
+    # an error instance (and no arguments).
+    #
+    # The workitem can be either an instance of Ruote::Workitem or a workitem
+    # in its Hash representation.
+    #
+    #   receiver.flunk(workitem, ArgumentError, "not enough info")
+    #
+    #   rescue => e
+    #     receiver.flunk(workitem, e)
+    #   end
+    #
+    def flunk(workitem, error_class_or_instance_or_message, *err_arguments)
+
+      err = error_class_or_instance_or_message
+
+      if err.is_a?(String)
+        err = RuntimeError.new(err)
+        err.set_backtrace(caller)
+
+      elsif err.is_a?(Class)
+        err = err.new(*err_arguments)
+        err.set_backtrace(caller)
+      end
+
+      workitem = workitem.h if workitem.respond_to?(:h)
+
+      @context.storage.put_msg(
+        'raise',
+        'fei' => workitem['fei'],
+        'wfid' => workitem['wfid'],
+        'msg' => {
+          'action' => 'dispatch',
+          'fei' => workitem['fei'],
+          'participant_name' => workitem['participant_name'],
+          'participant' => nil,
+          'workitem' => workitem
+        },
+        'error' => {
+          'class' => err.class.name,
+          'message' => err.message,
+          'trace' => err.backtrace
+        })
+    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).
+    # This method is mostly used from the Ruote::Dashboard class (which
+    # includes this mixin).
     #
     # process_definition must be a result of Ruote.process_definition call
     # or XML or JSON serialized process definition, as accepted by
@@ -61,42 +118,30 @@ module Ruote
     #
     # fields are workflow parameters that will be placed in workitem.fields.
     #
-    # variables contain engine variables.
+    # Calls to this method returns the newly launched "workflow instance id"
+    # ("wfid" for short), the [hopefully] unique identifier for the
+    # process instance.
     #
-    def launch(process_definition, fields={}, variables={})
+    # == custom :wfid
+    #
+    # When calling this method, it's OK to pass a field named :wfid (Symbol,
+    # not String) that will be used as the identifier for the process instance.
+    #
+    def launch(process_definition, fields={}, variables={}, root_stash=nil)
 
-      wfid = @context.wfidgen.generate
+      wfid = fields[:wfid] || @context.wfidgen.generate
 
       @context.storage.put_msg(
         'launch',
         'wfid' => wfid,
         'tree' => @context.reader.read(process_definition),
         'workitem' => { 'fields' => fields },
-        'variables' => variables)
+        'variables' => variables,
+        'stash' => root_stash)
 
       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.
@@ -116,13 +161,8 @@ module Ruote
         Ruote::FlowExpressionId.extract_h(workitem_or_fei))
     end
 
-    # For example :
-    #
-    #   fexp = engine.fexp(fei)
-    #     # or
-    #   fexp = engine.fexp(workitem)
-    #
     alias fexp fetch_flow_expression
+    alias flow_expression fetch_flow_expression
 
     # A convenience methods for advanced users (like Oleg).
     #
@@ -140,11 +180,13 @@ module Ruote
     # on_terminate processes are not triggered for on_error processes.
     # on_error processes are triggered for on_terminate processes as well.
     #
-    def applied_workitem(fei)
+    def fetch_workitem(fexp_or_fei)
 
-      Ruote::Workitem.new(fexp(fei).h.applied_workitem)
+      Ruote::Workitem.new(flow_expression(fexp_or_fei).h.applied_workitem)
     end
-    alias workitem applied_workitem
+
+    alias workitem fetch_workitem
+    alias applied_workitem fetch_workitem
 
     protected
 
@@ -161,15 +203,25 @@ module Ruote
     # http://groups.google.com/group/openwferu-users/t/2e6a95708c10847b for the
     # justification.
     #
-    def put(fei, hash)
+    def stash_put(workitem_or_fei, key, value=nil)
 
-      fexp = Ruote::Exp::FlowExpression.fetch(@context, fei.to_h)
+      hash = key.is_a?(Hash) ? key : { key => value }
 
-      (fexp.h['stash'] ||= {}).merge!(hash)
+      exp = fetch_flow_expression(workitem_or_fei)
 
-      fexp.persist_or_raise
+      (exp.h['stash'] ||= {}).merge!(hash)
+
+      r = exp.try_persist
+
+      return hash if r == nil
+      return stash_put(workitem_or_fei, key, value) if r != true
+
+      fei = Ruote::FlowExpressionId.extract(workitem_or_fei).sid rescue 'xxx'
+      raise ArgumentError.new("failed to put, expression #{fei} is gone")
     end
 
+    alias put stash_put
+
     # Fetches back a stashed value.
     #
     #   get(fei, 'colour')
@@ -183,14 +235,15 @@ module Ruote
     # 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)
+    def stash_get(workitem_or_fei, key=nil)
 
-      stash = fexp.h['stash'] rescue {}
+      stash = fetch_flow_expression(workitem_or_fei).h['stash'] rescue nil
+      stash ||= {}
 
       key ? stash[key] : stash
     end
+
+    alias get stash_get
   end
 
   #

data/lib/ruote/storage/base.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
@@ -22,6 +22,7 @@
 # Made in Japan.
 #++
 
+require 'ostruct'
 require 'ruote/util/time'
 
 
@@ -32,6 +33,10 @@ module Ruote
   #
   module StorageBase
 
+    #--
+    # misc
+    #++
+
     def context
 
       @context ||= Ruote::Context.new(self)
@@ -50,6 +55,21 @@ module Ruote
       delete(doc).nil?
     end
 
+    # A helper for the #worker method, it returns that dummy worker
+    # when there is no reference to the calling worker in the current
+    # thread's local variables.
+    #
+    DUMMY_WORKER = OpenStruct.new(
+      :name => 'worker', :identity => 'unknown', :state => 'running')
+
+    # Warning, this is not equivalent to doing @context.worker, this method
+    # fetches the worker from the local thread variables.
+    #
+    def worker
+
+      Thread.current['ruote_worker'] || DUMMY_WORKER
+    end
+
     #--
     # configurations
     #++
@@ -59,6 +79,18 @@ module Ruote
       get('configurations', key)
     end
 
+    def replace_engine_configuration(options)
+
+      return if options.delete('preserve_configuration')
+
+      conf = get('configurations', 'engine')
+
+      doc = options.merge('type' => 'configurations', '_id' => 'engine')
+      doc['_rev'] = conf['_rev'] if conf
+
+      put(doc)
+    end
+
     #--
     # messages
     #++
@@ -68,29 +100,11 @@ module Ruote
       msg = prepare_msg_doc(action, options)
 
       put(msg)
-
-      #put(msg, :update_rev => true)
-      #(@local_msgs ||= []) << Ruote.fulldup(msg)
     end
 
-    #def get_local_msgs
-    #  p @local_msgs
-    #  if @local_msgs
-    #    r = @local_msgs
-    #    @local_msgs = nil
-    #    r
-    #  else
-    #    []
-    #  end
-    #end
-
     def get_msgs
 
-      get_many(
-        'msgs', nil, :limit => 300
-      ).sort { |a, b|
-        a['put_at'] <=> b['put_at']
-      }
+      get_many('msgs', nil, :limit => 300).sort_by { |d| d['put_at'] }
     end
 
     def empty?(type)
@@ -102,13 +116,27 @@ module Ruote
     # expressions
     #++
 
+    # Given a wfid, returns all the expressions of that process instance.
+    #
+    def find_expressions(wfid)
+
+      get_many('expressions', wfid)
+    end
+
+    # For a given wfid, returns all the expressions (array of Hash instances)
+    # that have a nil 'parent_id'.
+    #
+    def find_root_expressions(wfid)
+
+      find_expressions(wfid).select { |hexp| hexp['parent_id'].nil? }
+    end
+
+    # For a given wfid, fetches all the root expressions, sort by expid and
+    # return the first. Hopefully it's the right root_expression.
+    #
     def find_root_expression(wfid)
 
-      get_many('expressions', wfid).sort_by { |fexp|
-        fexp['fei']['expid']
-      }.select { |e|
-        e['parent_id'].nil?
-      }.first
+      find_root_expressions(wfid).sort_by { |hexp| hexp['fei']['expid'] }.first
     end
 
     # Given all the expressions stored here, returns a sorted list of unique
@@ -250,6 +278,38 @@ module Ruote
       end
     end
 
+    # Removes a process by removing all its schedules, expressions, errors,
+    # workitems and trackers.
+    #
+    # Warning: will not trigger any cancel behaviours at all, just removes
+    # the process.
+    #
+    def remove_process(wfid)
+
+      2.times do
+        # two passes
+
+        Thread.pass
+
+        %w[ schedules expressions errors workitems ].each do |type|
+          get_many(type, wfid).each { |d| delete(d) }
+        end
+
+        doc = get_trackers
+
+        doc['trackers'].delete_if { |k, v| k.end_with?("!#{wfid}") }
+
+        @context.storage.put(doc)
+      end
+    end
+
+    def dump(type)
+
+      require 'yaml'
+
+      YAML.dump({ type => get_many(type) })
+    end
+
     protected
 
     # Used by put_msg
@@ -303,6 +363,7 @@ module Ruote
         'original' => s,
         'at' => Ruote.time_to_utc_s(at),
         'owner' => owner_fei,
+        'wfid' => owner_fei['wfid'],
         'msg' => msg
       }
     end
@@ -322,27 +383,35 @@ module Ruote
       schedules.select { |sch| sch['at'] <= now }
     end
 
-    ## Returns true if the doc wfid is included in the wfids passed.
-    ##
-    #def wfid_match? (doc, wfids)
-    #  wfids.find { |wfid| doc['_id'].index(wfid) } != nil
-    #end
-
     # Used by #get_many. Returns true whenever one of the keys matches the
     # doc['_id']. Works with strings (_id ends with key) or regexes (_id matches
     # key).
     #
-    # It's a class method meant to be used by the various storage
-    # implementations.
+    def key_match?(type, keys, doc)
+
+      _id = doc.is_a?(Hash) ? doc['_id'] : doc
+
+      if keys.first.is_a?(String) && type == 'schedules'
+        keys.find { |key| _id.match(/#{key}-\d+$/) }
+      elsif keys.first.is_a?(String)
+        keys.find { |key| _id.end_with?(key) }
+      else # Regexp
+        keys.find { |key| _id.match(key) }
+      end
+    end
+
+    # (Only used by ruote-couch 2.2.x)
+    #
+    # TODO: remove me at some point
     #
     def self.key_match?(keys, doc)
 
       _id = doc.is_a?(Hash) ? doc['_id'] : doc
 
       if keys.first.is_a?(String)
-        keys.find { |key| _id[-key.length..-1] == key }
+        keys.find { |key| _id.end_with?(key) }
       else # Regexp
-        keys.find { |key| key.match(_id) }
+        keys.find { |key| _id.match(key) }
       end
     end
   end