workitem.rb in ruote-2.3.0

- old
+ new

@@ -1,7 +1,7 @@
 #--
-# 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
 # in the Software without restriction, including without limitation the rights
 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
@@ -86,11 +86,11 @@
 
     # Returns a Ruote::FlowExpressionId instance.
     #
     def fei
 
-      FlowExpressionId.new(h.fei)
+      FlowExpressionId.new(@h['fei'])
     end
 
     # Returns a complete copy of this workitem.
     #
     def dup
@@ -105,10 +105,49 @@
     def participant_name
 
       @h['participant_name']
     end
 
+    # Returns the name of the workflow to which this workitem belongs, or nil.
+    #
+    def wf_name; @h['wf_name']; end
+
+    # Returns the revision of the workflow to which this workitem belongs,
+    # or nil.
+    #
+    def wf_revision; @h['wf_revision']; end
+
+    # Returns the UTC time string indicating when the workflow was launched.
+    #
+    def wf_launched_at; @h['wf_launched_at']; end
+
+    alias launched_at wf_launched_at
+    alias definition_name wf_name
+    alias definition_revision wf_revision
+
+    # Returns the name of the sub-workflow the workitem is currently in.
+    # (If it's in the main flow, it will return the name of the main flow,
+    # if that flow has a name...)
+    #
+    def sub_wf_name; @h['sub_wf_name']; end
+
+    # The equivalent of #sub_wf_name for revisions.
+    #
+    def sub_wf_revision; @h['sub_wf_revision']; end
+
+    # Returns the UTC time string indicating when the sub-workflow was launched.
+    #
+    def sub_wf_launched_at; @h['sub_wf_launched_at']; end
+
+    # Used by some participants, returns the "owner" of the workitem. Mostly
+    # used when reserving workitems.
+    #
+    def owner
+
+      @h['owner']
+    end
+
     # Returns the payload, ie the fields hash.
     #
     def fields
 
       @h['fields']
@@ -203,10 +242,36 @@
     def set_field(key, value)
 
       Ruote.set(@h['fields'], key, value)
     end
 
+    # Shortcut for #lookup(key)
+    #
+    #   workitem.fields['customer']['city']
+    #     # or
+    #   workitem.lookup('customer.city')
+    #     # or
+    #   workitem['customer.city']
+    #
+    def [](key)
+
+      lookup(key.to_s)
+    end
+
+    # Shortcut for #set_field(key, value)
+    #
+    #   workitem.fields['customer']['city'] = 'Toronto'
+    #     # or
+    #   workitem.set_field('customer.city', 'Toronto')
+    #     # or
+    #   workitem['customer.city'] = 'Toronto'
+    #
+    def []=(key, value)
+
+      set_field(key.to_s, value)
+    end
+
     # Shortcut for wi.fields['__timed_out__']
     #
     def timed_out
 
       @h['fields']['__timed_out__']
@@ -230,21 +295,77 @@
     #    p workitem.params
     #      # => { 'ref' => 'toto', 'task' => 'x' }
     #
     def params
 
-      @h['fields']['params']
+      @h['fields']['params'] || {}
     end
 
+    # When a participant is invoked like in
+    #
+    #    accounting 'do_invoice', :customer => 'acme corp'
+    #
+    # then
+    #
+    #    p workitem.params
+    #      # => { 'ref' => 'accounting', 'do_invoice' => nil, 'customer' => 'acme corp' }
+    #
+    # and
+    #
+    #    p workitem.param_text
+    #      # => 'do_invoice'
+    #
+    # It returns nil when there is no text passed directly.
+    #
+    def param_text
+
+      (params.find { |k, v| v.nil? } || []).first
+    end
+
+    # Sometimes a value is passed as a[n expression] parameter or as a
+    # workitem field, with priority to the parameter.
+    #
+    #   sequence do
+    #     set 'f:country' => 'uruguay'
+    #     participant 'toto'
+    #       # in toto, workitem.param_or_field(:country) will yield 'uruguay'
+    #     participant 'toto', :country => 'argentina'
+    #       # workitem.param_or_field(:country) will yield 'argentina'
+    #   end
+    #
+    def param_or_field(key)
+
+      key = key.to_s
+
+      (@h['fields']['params'] || {})[key] || @h['fields'][key]
+    end
+
+    # Like #param_or_field, but priority is given to the field.
+    #
+    def field_or_param(key)
+
+      key = key.to_s
+
+      @h['fields'][key] || (@h['fields']['params'] || {})[key]
+    end
+
+    # Shortcut to the temporary/trailing fields
+    #
+    # http://groups.google.com/group/openwferu-users/browse_thread/thread/981dba6204f31ccc
+    #
+    def t
+      @h['fields']['t'] ||= {}
+    end
+
     # (advanced)
     #
     # Shortcut for wi.fields['__command__']
     #
     # __command__ is read by the 'cursor' and the 'iterator' expressions
     # when a workitem reaches it (apply and reply).
     #
-    def commmand
+    def command
 
       @h['fields']['__command__']
     end
 
     # (advanced)
@@ -268,31 +389,18 @@
     def tags
 
       @h['fields']['__tags__'] || []
     end
 
-    # Used by FlowExpression when entering a tag.
+    # How many times was this workitem re_dispatched ?
     #
-    def self.add_tag(hworkitem, tag)
-
-      (hworkitem['fields']['__tags__'] ||= []) << tag
-    end
-
-    # Used by FlowExpression when leaving a tag.
+    # It's used by LocalParticipant re_dispatch mostly, or by participant
+    # which poll a resource and re_dispatch after a while.
     #
-    def self.remove_tag(hworkitem, tag)
+    def re_dispatch_count
 
-      # it's a bit convoluted... trying to cope with potential inconsistencies
-      #
-      # normally, it should only be a tags.pop(), but since user have
-      # access to the workitem and its fields... better be safe than sorry
-
-      tags = (hworkitem['fields']['__tags__'] || [])
-
-      if index = tags.rindex(tag)
-        tags.delete_at(index)
-      end
+      @h['re_dispatch_count'] || 0
     end
 
     # Encodes this workitem as JSON. If pretty is set to true, will output
     # prettified JSON.
     #
@@ -311,9 +419,36 @@
       raise ArgumentError(
         "Arg not a JSON hash/object, but a #{h.class}. Cannot create workitem"
       ) unless h.is_a?(Hash)
 
       self.new(h)
+    end
+
+    protected
+
+    # Used by FlowExpression when entering a tag.
+    #
+    def add_tag(tag)
+
+      (@h['fields']['__tags__'] ||= []) << tag
+    end
+
+    # Used by FlowExpression when leaving a tag.
+    #
+    def remove_tag(tag)
+
+      # it's a bit convoluted... trying to cope with potential inconsistencies
+      #
+      # normally, it should only be a tags.pop(), but since user have
+      # access to the workitem and its fields... better be safe than sorry
+
+      tags = (@h['fields']['__tags__'] || [])
+
+      if index = tags.rindex(tag)
+        tags.delete_at(index)
+      end
+
+      @h['fields']['__left_tag__'] = tag
     end
   end
 end
 