ruote-maestrodev 2.2.1

data/lib/ruote/exp/ro_persist.rb

@@ -0,0 +1,154 @@
+#--
+# Copyright (c) 2005-2011, 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.
+#++
+
+
+module Ruote::Exp
+
+  #
+  # Reopening the FlowExpression class to add [un]persist methods.
+  #
+  class FlowExpression
+
+    #--
+    # PERSISTENCE
+    #++
+
+    # Persists and fetches the _rev identifier from the storage.
+    #
+    # Only used by the worker when creating the expression.
+    #
+    def initial_persist
+
+      r = @context.storage.put(@h, :update_rev => true)
+
+      #t = Thread.current.object_id.to_s[-3..-1]
+      #puts "+ per #{h.fei['expid']} #{tree[0]} r#{h._rev} t#{t} -> #{r.class}"
+      #Ruote.p_caller('+ per')
+
+      raise_or_return('initial_persist failed', r)
+    end
+
+    def try_persist
+
+      r = @context.storage.put(@h)
+
+      #t = Thread.current.object_id.to_s[-3..-1]
+      #puts "+ per #{h.fei['expid']} #{tree[0]} r#{h._rev} t#{t} -> #{r.class}"
+      #Ruote.p_caller('+ per')
+
+      r
+    end
+
+    def try_unpersist
+
+      r = @context.storage.delete(@h)
+
+      #t = Thread.current.object_id.to_s[-3..-1]
+      #puts "- unp #{h.fei['expid']} #{tree[0]} r#{h._rev} t#{t} -> #{r.class}"
+      #Ruote.p_caller('- unp')
+
+      return r if r
+
+      #if h.has_error
+      err = @context.storage.get('errors', "err_#{Ruote.to_storage_id(h.fei)}")
+      @context.storage.delete(err) if err
+      #end
+        # removes any error in the journal for this expression
+        # since it will now be gone, no need to keep track of its errors
+
+      nil
+    end
+
+    def persist_or_raise
+
+      p_or_raise(true)
+    end
+
+    def unpersist_or_raise
+
+      p_or_raise(false)
+    end
+
+    alias persist persist_or_raise
+    alias unpersist unpersist_or_raise
+
+    def do_persist
+
+      do_p(true)
+    end
+
+    def do_unpersist
+
+      do_p(false)
+    end
+
+    protected
+
+    def raise_or_return(msg, r)
+
+      msg = msg.is_a?(String) ?
+        msg : (msg ? 'persist' : 'unpersist') + ' failed'
+
+      raise(
+        "#{msg} for " +
+        "#{Ruote.to_storage_id(h.fei)} #{tree[0]} #{tree[1].inspect} " +
+        'r(' + (r == true ? 'gone' : "rev : #{r['_rev']}") + ')'
+      ) if r
+
+      r
+    end
+
+    # Does persist or unpersist, returns nothing in particular.
+    #
+    # Will raise a runtime error if it fails (ie if it happens, there
+    # is something wrong with the storage implementation or the engine).
+    #
+    def p_or_raise(pers)
+
+      r = pers ? try_persist : try_unpersist
+
+      raise_or_return(pers, r)
+    end
+
+    # Does persist or unpersist, if successful then return true. If the
+    # expression is gone, return false.
+    # If there is a 'fresher' version of the expression, re-attempt and return
+    # false.
+    #
+    def do_p(pers)
+
+      case r = pers ? try_persist : try_unpersist
+        when true
+          false # do not go on
+        when Hash
+          self.h = r
+          self.send("do_#{@msg['action']}", @msg)
+          false # do not go on
+        else
+          true # success, do go on
+      end
+    end
+  end
+end
+

data/lib/ruote/exp/ro_variables.rb

@@ -0,0 +1,189 @@
+#--
+# Copyright (c) 2005-2011, 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.
+#++
+
+
+module Ruote::Exp
+
+  #
+  # 're-opening' the FlowExpression class to add the methods about variables.
+  #
+  class FlowExpression
+
+    # A shortcut to the variables held in the expression (nil if none held).
+    #
+    def variables
+
+      @h['variables']
+    end
+
+    # Returns a fresh hash of all the variables visible from this expression.
+    #
+    # This is used mainly when forgetting an expression.
+    #
+    def compile_variables
+
+      vars = h.parent_id ? parent.compile_variables : {}
+      vars.merge!(h.variables) if h.variables
+
+      vars
+    end
+
+    # Looks up the value of a variable in expression tree
+    # (seen from a leaf, it looks more like a stack than a tree)
+    #
+    def lookup_variable(var, prefix=nil)
+
+      var, prefix = split_prefix(var, prefix)
+
+      return @context.storage.get_engine_variable(var) \
+        if prefix.length >= 2
+
+      return parent.lookup_variable(var, prefix) \
+        if h.parent_id && prefix.length >= 1
+
+      if h.variables
+
+        val = Ruote.lookup(h.variables, var)
+
+        return val if val != nil
+      end
+
+      if h.parent_id && h.parent_id['engine_id'] == @context.engine_id
+        #
+        # do not lookup variables in a remote engine ...
+
+        (return parent.lookup_variable(var, prefix)) rescue nil
+          # if the lookup fails (parent gone) then rescue and let go
+      end
+
+      @context.storage.get_engine_variable(var)
+    end
+
+    # A shortcut for #lookup_variable
+    #
+    alias :v :lookup_variable
+
+    # A shortcut for #lookup_variable
+    #
+    alias :lv :lookup_variable
+
+    # Sets a variable to a given value.
+    # (will set at the appropriate level).
+    #
+    def set_variable(var, val)
+
+      fexp, v = locate_var(var)
+
+      fexp.un_set_variable(:set, v, val, (fexp.h.fei != h.fei)) if fexp
+    end
+
+    # Unbinds a variables.
+    #
+    def unset_variable(var)
+
+      fexp, v = locate_var(var)
+
+      fexp.un_set_variable(:unset, v, nil, (fexp.h.fei != h.fei)) if fexp
+    end
+
+    # TODO : redoc rewrite needed
+    #
+    # This method is mostly used by the worker when looking up
+    # a process name or participant name bound under a variable.
+    #
+    def iterative_var_lookup(k)
+
+      v = lookup_variable(k)
+
+      return [ k, v ] unless (v.is_a?(String) or v.is_a?(Symbol))
+
+      iterative_var_lookup(v)
+    end
+
+    protected
+
+    # Sets (or unsets) the value of a local variable
+    #
+    # val should be nil in case of 'unset'.
+    #
+    def un_set_variable(op, var, val, should_persist)
+
+      if op == :set
+        Ruote.set(h.variables, var, val)
+      else # op == :unset
+        Ruote.unset(h.variables, var)
+      end
+
+      if should_persist && r = try_persist # persist failed, have to retry
+
+        @h = r
+        un_set_variable(op, var, val, true)
+
+      else # success (even when should_persist == false)
+
+        @context.storage.put_msg("variable_#{op}", 'var' => var, 'fei' => h.fei)
+      end
+    end
+
+    VAR_PREFIX_REGEX = /^(\/*)/
+
+    # Used by lookup_variable and set_variable to extract the
+    # prefix in a variable name
+    #
+    def split_prefix(var, prefix)
+
+      if prefix.nil?
+        var = var.to_s
+        m = VAR_PREFIX_REGEX.match(var)
+        prefix = m ? m[1][0, 2] : ''
+        var = var[prefix.length..-1]
+      end
+
+      [ var, prefix ]
+    end
+
+    # Returns the flow expression that owns a variable (or the one
+    # that should own it) and the var without its potential / prefixes.
+    #
+    def locate_var(var, prefix=nil)
+
+      var, prefix = split_prefix(var, prefix)
+
+      return nil if prefix.length >= 2 # engine variable
+      return parent.locate_var(var, prefix) if prefix.length == 1 && h.parent_id
+
+      # no prefix...
+
+      return [ self, var ] if h.variables
+
+      if par = parent
+        return parent.locate_var(var, prefix) rescue nil
+      end
+
+      #raise "uprooted var lookup, something went wrong"
+      [ nil, nil ]
+    end
+  end
+end
+

data/lib/ruote/exp/ro_vf.rb

@@ -0,0 +1,68 @@
+#--
+# Copyright (c) 2005-2011, 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.
+#++
+
+
+module Ruote::Exp
+
+  #
+  # 're-opening' the FlowExpression class to add methods like set_vf and co.
+  #
+  class FlowExpression
+
+    protected
+
+    def set_v(key, value, unset=false)
+
+      if unset
+        unset_variable(key)
+      else
+        set_variable(key, value)
+      end
+    end
+
+    def set_f(key, value, unset=false)
+
+      if unset
+        h.applied_workitem['fields'].delete(key)
+      else
+        Ruote.set(h.applied_workitem['fields'], key, value)
+      end
+    end
+
+    PREFIX_REGEX = /^([^:]+):(.+)$/
+    F_PREFIX_REGEX = /^f/
+
+    def set_vf(key, value, unset=false)
+
+      field, key = if m = PREFIX_REGEX.match(key)
+        [ F_PREFIX_REGEX.match(m[1]), m[2] ]
+      else
+        [ true, key ]
+      end
+
+      field ? set_f(key, value, unset) : set_v(key, value, unset)
+    end
+  end
+end
+

data/lib/ruote/fei.rb

@@ -0,0 +1,260 @@
+#--
+# Copyright (c) 2005-2011, 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 'digest/md5'
+
+require 'ruote/version'
+require 'ruote/workitem'
+require 'ruote/util/misc'
+require 'ruote/util/hashdot'
+
+
+module Ruote
+
+  # A shortcut for
+  #
+  #   Ruote::FlowExpressionId.to_storage_id(fei)
+  #
+  def self.to_storage_id(fei)
+
+    Ruote::FlowExpressionId.to_storage_id(fei)
+  end
+
+  # A shorter shortcut for
+  #
+  #   Ruote::FlowExpressionId.to_storage_id(fei)
+  #
+  def self.sid(fei)
+
+    Ruote::FlowExpressionId.to_storage_id(fei)
+  end
+
+  # A shortcut for
+  #
+  #   Ruote::FlowExpressionId.is_a_fei?(o)
+  #
+  def self.is_a_fei?(o)
+
+    Ruote::FlowExpressionId.is_a_fei?(o)
+  end
+
+  # Will do its best to return a wfid (String) or a fei (Hash instance)
+  # extract from the given o argument.
+  #
+  def self.extract_id(o)
+
+    return o if o.is_a?(String) and o.index('!').nil? # wfid
+
+    Ruote::FlowExpressionId.extract_h(o)
+  end
+
+  # Given something, tries to return the fei (Ruote::FlowExpressionId) in it.
+  #
+  def self.extract_fei(o)
+
+    Ruote::FlowExpressionId.extract(o)
+  end
+
+  # This function is used to generate the subids. Each flow
+  # expression receives such an id (it's useful for cursors, loops and
+  # forgotten branches).
+  #
+  def self.generate_subid(salt)
+
+    Digest::MD5.hexdigest(
+      "#{rand}-#{salt}-#{$$}-#{Thread.current.object_id}#{Time.now.to_f}")
+  end
+
+  #
+  # The FlowExpressionId (fei for short) is an process expression identifier.
+  # Each expression when instantiated gets a unique fei.
+  #
+  # Feis are also used in workitems, where the fei is the fei of the
+  # [participant] expression that emitted the workitem.
+  #
+  # Feis can thus indicate the position of a workitem in a process tree.
+  #
+  # Feis contain four pieces of information :
+  #
+  # * wfid : workflow instance id, the identifier for the process instance
+  # * subid : a unique identifier for expressions (useful in loops)
+  # * expid : the expression id, where in the process tree
+  # * engine_id : only relevant in multi engine scenarii (defaults to 'engine')
+  #
+  class FlowExpressionId
+
+    CHILD_SEP = '_'
+
+    attr_reader :h
+
+    def initialize(h)
+
+      @h = h
+      class << h; include Ruote::HashDot; end
+
+      @h['subid'] = @h.delete('sub_wfid') if @h['sub_wfid']
+        # TODO : for 2.1.13, remove this
+    end
+
+    def expid; @h['expid']; end
+    def wfid; @h['wfid']; end
+    def engine_id; @h['engine_id']; end
+    def subid; @h['subid']; end
+
+    alias sub_wfid subid
+
+    def to_storage_id
+
+      "#{@h['expid']}!#{@h['subid']}!#{@h['wfid']}"
+    end
+    alias sid to_storage_id
+
+    def to_sortable_id
+
+      "#{@h['wfid']}!!#{@h['expid']}"
+    end
+
+    def self.to_storage_id(hfei)
+
+      hfei.respond_to?(:to_storage_id) ?
+        hfei.to_storage_id :
+        "#{hfei['expid']}!#{hfei['subid'] || hfei['sub_wfid']}!#{hfei['wfid']}"
+
+      # TODO : for 2.1.13, remove the subid || sub_wfid trick
+    end
+
+    # Turns the result of to_storage_id back to a FlowExpressionId instance.
+    #
+    def self.from_id(s, engine_id='engine')
+
+      extract("#{engine_id}!#{s}")
+    end
+
+    # Returns the last number in the expid. For instance, if the expid is
+    # '0_5_7', the child_id will be '7'.
+    #
+    def child_id
+
+      h.expid.split(CHILD_SEP).last.to_i
+    end
+
+    def hash
+
+      to_storage_id.hash
+    end
+
+    def <=>(other)
+
+      self.to_sortable_id <=> other.to_sortable_id
+    end
+
+    # Returns true if the other is a FlowExpressionId instance and it
+    # points to the same expression as this one.
+    #
+    def ==(other)
+
+      return false unless other.is_a?(Ruote::FlowExpressionId)
+
+      (hash == other.hash)
+    end
+
+    alias eql? ==
+
+    SUBS = %w[ subid sub_wfid ]
+    IDS = %w[ engine_id expid wfid ]
+
+    # Returns true if the h is a representation of a FlowExpressionId instance.
+    #
+    def self.is_a_fei?(h)
+
+      h.respond_to?(:keys) && (h.keys - SUBS).sort == IDS
+    end
+
+    # Returns child_id... For an expid of '0_1_4', this will be 4.
+    #
+    def self.child_id(h)
+
+      h['expid'].split(CHILD_SEP).last.to_i
+    end
+
+    def to_h
+
+      @h
+    end
+
+    # Returns true if other_fei is the fei of a child expression of
+    # parent_fei.
+    #
+    def self.direct_child?(parent_fei, other_fei)
+
+      %w[ wfid engine_id ].each do |k|
+        return false if parent_fei[k] != other_fei[k]
+      end
+
+      pei = other_fei['expid'].split(CHILD_SEP)[0..-2].join(CHILD_SEP)
+
+      (pei == parent_fei['expid'])
+    end
+
+    # Attempts at extracting a FlowExpressionId from the given argument
+    # (workitem, string, ...)
+    #
+    # Uses .extract_h
+    #
+    def self.extract(arg)
+
+      FlowExpressionId.new(extract_h(arg))
+    end
+
+    # Attempts at extracting a FlowExpressionId (as a Hash instance) from the
+    # given argument (workitem, string, ...)
+    #
+    def self.extract_h(arg)
+
+      if arg.is_a?(Hash)
+        return arg if arg['expid']
+        return arg['fei'] if arg['fei']
+      end
+
+      return extract_h(arg.fei) if arg.respond_to?(:fei)
+      return arg.h if arg.is_a?(Ruote::FlowExpressionId)
+      return arg.h['fei'] if arg.is_a?(Ruote::Workitem)
+
+      if arg.is_a?(String)
+
+        ss = arg.split('!')
+
+        return {
+          'engine_id' => ss[-4] || 'engine',
+          'expid' => ss[-3],
+          'subid' => ss[-2],
+          'wfid' => ss[-1] }
+      end
+
+      raise ArgumentError.new(
+        "couldn't extract fei out of instance of #{arg.class}")
+    end
+  end
+end
+