openwferu 0.9.12 → 0.9.12.863

data/lib/openwfe/expressions/fe_iterator.rb

@@ -30,8 +30,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 #++
 #
-# $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
-#
 
 #
 # "made in Japan"
@@ -41,6 +39,7 @@
 
 require 'openwfe/expressions/wtemplate'
 require 'openwfe/expressions/flowexpression'
+require 'openwfe/expressions/fe_command'
 
 
 module OpenWFE
@@ -62,22 +61,37 @@ module OpenWFE
     # of elements in the iteration and the field "\_\_ip__" the index of the
     # current iteration.
     #
+    # The 'iterator' expression understands the same cursor commands as the
+    # CursorExpression. One can thus exit an iterator or skip steps in it.
+    #
+    #     iterator :on_value => "alice, bob, charles, doug", to_variable => "v" do
+    #         sequence do
+    #             participant :variable_ref => "v"
+    #             skip 1, :if => "${f:reply} == 'skip next'"
+    #         end
+    #     end
+    #
     class IteratorExpression < WithTemplateExpression
+        include CommandMixin
 
         names :iterator
 
+        #
+        # an Iterator instance that holds the list of values being iterated
+        # upon.
+        #
         attr_accessor :iterator
 
         def apply (workitem)
 
             if @children.length < 1
-                reply_to_parent(workitem)
+                reply_to_parent workitem
                 return
             end
 
             @iterator = Iterator.new(self, workitem)
 
-            if not @iterator.has_next?
+            if @iterator.size < 1
                 reply_to_parent workitem
                 return
             end
@@ -87,14 +101,35 @@ module OpenWFE
 
         def reply (workitem)
 
-            unless @iterator.has_next?
-                reply_to_parent(workitem)
-                return
+            command, step = determine_command_and_step workitem
+
+            vars = if not command
+
+                @iterator.next workitem
+
+            elsif command == C_BREAK or command == C_CANCEL
+
+                nil
+
+            elsif command == C_REWIND or command == C_CONTINUE
+
+                @iterator.rewind workitem
+
+            elsif command.match "^#{C_JUMP}"
+
+                @iterator.jump workitem, step
+
+            else # C_SKIP or C_BACK
+
+                @iterator.skip workitem, step
             end
 
-            vars = @iterator.next(self, workitem)
+            unless vars
+                reply_to_parent workitem
+                return
+            end
 
-            store_itself()
+            store_itself
 
             get_expression_pool.launch_template(
                 self, @iterator.index, @children[0], workitem, vars)
@@ -111,13 +146,17 @@ module OpenWFE
         ITERATOR_COUNT = "__ic__"
         ITERATOR_POSITION = "__ip__"
 
-        attr_accessor \
-            :iteration_list,
-            :to_field,
-            :to_variable,
-            :value_separator,
-            :counter
+        attr_accessor :iteration_index
+        attr_accessor :iteration_list
+        attr_accessor :to_field
+        attr_accessor :to_variable
+        attr_accessor :value_separator
 
+        #
+        # Builds a new iterator, serving a given iterator_expression. 
+        # The second parameter is the workitem (as applied to the iterator
+        # expression).
+        #
         def initialize (iterator_expression, workitem)
 
             @to_field = iterator_expression\
@@ -130,7 +169,7 @@ module OpenWFE
 
             @value_separator = /,\s*/ unless @value_separator
 
-            @counter = 0
+            @iteration_index = 0
 
             raw_list = iterator_expression.lookup_vf_attribute(
                 workitem, :value, :on)
@@ -144,58 +183,125 @@ module OpenWFE
         # Has the iteration a next element ?
         #
         def has_next?
-            @iteration_list.length > 0
+
+            @iteration_index < @iteration_list.size
+        end
+
+        #
+        # Returns the size of this iterator, or rather, the size of the
+        # underlying iteration list.
+        #
+        def size
+
+            @iteration_list.size
         end
 
         #
         # Prepares the iterator expression and the workitem for the next 
         # iteration.
         #
-        def next (iterator_expression, workitem)
+        def next (workitem)
 
-            result = {}
+            position_at workitem, @iteration_index
+        end
+
+        #
+        # Positions the iterator back at position 0.
+        #
+        def rewind (workitem)
 
-            value = @iteration_list.pop
+            position_at workitem, 0
+        end
+
+        #
+        # Jumps to a given position in the iterator
+        #
+        def jump (workitem, index)
 
-            if @to_field
-                workitem.attributes[@to_field] = value
+            index = if index < 0
+                0
+            elsif index >= @iteration_list.size
+                @iteration_list.size
             else
-                #iterator_expression.set_variable(@to_variable, value)
-                result[@to_variable] = value
+                index
             end
 
-            workitem.attributes[ITERATOR_POSITION] = @counter
-            result[ITERATOR_POSITION] = @counter
+            position_at workitem, index
+        end
 
-            @counter = @counter + 1
+        #
+        # Jumps a certain number of positions in the iterator.
+        #
+        def skip (workitem, offset)
 
-            result
+            jump workitem, @iteration_index + offset
         end
 
+        #
+        # The current index (whereas @iteration_index already points to
+        # the next element).
+        #
         def index
-            return @counter - 1
+
+            @iteration_index - 1
         end
 
         protected
 
+            #
+            # Positions the iterator absolutely.
+            #
+            def position_at (workitem, position)
+
+                result = {}
+
+                value = @iteration_list[position]
+
+                return nil unless value
+
+                if @to_field
+                    workitem.attributes[@to_field] = value
+                else
+                    result[@to_variable] = value
+                end
+
+                workitem.attributes[ITERATOR_POSITION] = position
+                result[ITERATOR_POSITION] = position
+
+                @iteration_index = position + 1
+
+                result
+            end
+
+            #
+            # Extracts the iteration list from any value.
+            #
             def extract_iteration_list (raw_list)
 
-                l = if is_suitable_list(raw_list)
+                if is_suitable_list?(raw_list)
                     raw_list
                 else
                     extract_list_from_string(raw_list.to_s)
                 end
-
-                return l.reverse
             end
 
-            def is_suitable_list (instance)
-                instance.respond_to? :pop and \
-                instance.respond_to? :reverse and \
+            #
+            # Returns true if the given instance can be directly
+            # used as a list.
+            #
+            def is_suitable_list? (instance)
+
+                (not instance.is_a?(String)) and \
+                instance.respond_to? :[] and \
                 instance.respond_to? :length
             end
 
+            #
+            # Extracts the list from the string (comma separated list
+            # usually).
+            #
             def extract_list_from_string (s)
+
                 s.split(@value_separator)
             end
     end

data/lib/openwfe/expressions/fe_subprocess.rb

@@ -30,8 +30,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 #++
 #
-# $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
-#
 
 #
 # "made in Japan"
@@ -39,8 +37,6 @@
 # John Mettraux at openwfe.org
 #
 
-#require 'uri'
-
 require 'openwfe/utils'
 
 
@@ -87,15 +83,9 @@ module OpenWFE
 
             raise "'subprocess' expression misses a 'ref', 'field-ref' or 'variable-ref' attribute" unless ref
 
-            template_uri = parse_uri(ref)
-
-            template = if template_uri
-                template_uri
-            else
-                lookup_variable(ref)
-            end
+            template_uri = OpenWFE::parse_known_uri(ref)
 
-            #template_fei = lookup_participant(ref) if not template_fei
+            template = template_uri || lookup_variable(ref)
 
             raise "did not find any subprocess named '#{ref}'" \
                 if not template
@@ -103,7 +93,7 @@ module OpenWFE
             forget = lookup_boolean_attribute(:forget, workitem)
 
             requester = @fei
-            requester = @fei.workflowInstanceId if forget
+            requester = @fei.workflow_instance_id if forget
 
             params = lookup_attributes(workitem)
 
@@ -120,22 +110,6 @@ module OpenWFE
 
         #def reply (workitem)
         #end
-
-        protected
-
-            def parse_uri (ref)
-
-                uri = OpenWFE::parse_uri(ref)
-
-                return nil unless uri
-
-                return uri if uri.scheme == "http"
-                return uri if uri.scheme == "https"
-                return uri if uri.scheme == "ftp"
-                    # what else ...
-
-                return nil
-            end
     end
 
 end

data/lib/openwfe/expressions/fe_value.rb

@@ -29,9 +29,6 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
 #++
-#
-# $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
-#
 
 #
 # "made in Japan"
@@ -99,7 +96,7 @@ module OpenWFE
             #puts "value is '#{value}'"
 
             if vkey
-                set_variable(vkey, value)
+                set_variable vkey, value
             elsif fkey
                 workitem.attributes[fkey] = value
             else

data/lib/openwfe/expressions/flowexpression.rb

@@ -29,9 +29,6 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
 #++
-#
-#  $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
-#
 
 #
 # "made in Japan"
@@ -51,8 +48,6 @@ module OpenWFE
 
     #
     # FlowExpression
-    #
-
     #
     # The base class for all OpenWFE flow expression classes.
     # It gathers all the methods for attributes and variable lookup.

data/lib/openwfe/expressions/raw.rb

@@ -30,8 +30,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 #++
 #
-# $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
-#
 
 #
 # "made in Japan"

data/lib/openwfe/expressions/raw_prog.rb

@@ -49,24 +49,24 @@ require 'openwfe/expressions/simplerep'
 module OpenWFE
 
     #
-    # This is the class to extend to create a programmatic process definition.
+    # Extend this class to create a programmatic process definition.
     #
     # A short example :
-    # <tt>
-    # class MyProcessDefinition < OpenWFE::ProcessDefinition
-    #     def make
-    #         process_definition :name => "test1", :revision => "0" do
-    #             sequence do
-    #                 set :variable => "toto", :value => "nada"
-    #                 print "toto:${toto}"
-    #             end
-    #         end
-    #     end
-    # end
+    # 
+    #   class MyProcessDefinition < OpenWFE::ProcessDefinition
+    #       def make
+    #           process_definition :name => "test1", :revision => "0" do
+    #               sequence do
+    #                   set :variable => "toto", :value => "nada"
+    #                   print "toto:${toto}"
+    #               end
+    #           end
+    #       end
+    #   end
     #
-    # li = OpenWFE::LaunchItem.new(MyProcessDefinition)
-    # engine.launch(li)
-    # </tt>
+    #   li = OpenWFE::LaunchItem.new(MyProcessDefinition)
+    #   engine.launch(li)
+    # 
     #
     class ProcessDefinition
 

data/lib/openwfe/flowexpressionid.rb

@@ -47,9 +47,9 @@ module OpenWFE
     # A FlowExpressionId is a unique identifier for a FlowExpression (an atomic
     # piece of a process instance).
     # 
-    # As workitems do transit among the expressions and are emitted outside
-    # of the business process engine via 'participant expressions', workitems
-    # out there are identified via the FlowExpressionId of the participant
+    # As workitems move through a workflow among the expressions and are emitted
+    # outside of the business process engine via 'participant expressions', these 
+    # workitems are identified by the FlowExpressionId of the participant
     # expression that pushed them out (and is waiting for them to come back).
     #
     class FlowExpressionId

data/lib/openwfe/listeners/listeners.rb

@@ -30,8 +30,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 #++
 #
-# $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
-#
 
 #
 # "made in Japan"
@@ -75,12 +73,10 @@ module OpenWFE
         attr_reader :workdir
 
         def initialize (service_name, application_context)
+
             super
 
-            #@workdir = application_context[:work_directory]
-            #@workdir = OpenWFE::DEFAULT_WORK_DIRECTORY unless @workdir
-            #@workdir += "/in/"
-            @workdir = OpenWFE::get_work_directory + "/in/"
+            @workdir = get_work_directory + "/in/"
 
             linfo { "new() workdir is '#{@workdir}'" }
         end

data/lib/openwfe/participants/enoparticipants.rb

@@ -30,7 +30,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 #++
 #
-#
 
 #
 # "made in Japan"
@@ -142,7 +141,7 @@ module OpenWFE
     # This participant is used to send an email notification.
     #
     # It's perhaps better to use MailParticipant which is simpler to 
-    # initialiaze. This class is anyway an extension of MailParticipant.
+    # initialize. This class is anyway an extension of MailParticipant.
     #
     #     @engine.register_participant(
     #         'eno', 

data/lib/openwfe/participants/participantmap.rb

@@ -30,8 +30,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 #++
 #
-# $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
-#
 
 #
 # "made in Japan"

data/lib/openwfe/participants/participants.rb

@@ -30,8 +30,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 #++
 #
-# $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
-#
 
 #
 # "made in Japan"
@@ -68,7 +66,7 @@ module OpenWFE
         #
         def initialize (context_or_dir=nil)
 
-            @workdir = OpenWFE::get_work_directory(context_or_dir) + "/out/"
+            @workdir = get_work_directory(context_or_dir) + "/out/"
 
             @reply_anyway = false
         end
@@ -190,6 +188,7 @@ module OpenWFE
         # Simply discards the incoming workitem
         #
         def consume (workitem)
+            # does nothing and does not reply to the engine.
         end
     end
 
@@ -210,7 +209,7 @@ module OpenWFE
 
     #
     # The PrintParticipant will just emit its name to the
-    # test tracer if any or to stdout else.
+    # test tracer if any or to the stdout else.
     # Used by some unit tests.
     #
     class PrintParticipant 
@@ -231,5 +230,97 @@ module OpenWFE
         end
     end
 
+    #
+    # Links a process under a participant [name].
+    #
+    # Turns top level processes into participants
+    #
+    # Some examples :
+    #
+    #     require 'engine/participants/participants'
+    #
+    #     engine.register_participant(
+    #         "transmit_to_accounting", 
+    #         "http://company.process.server.ie/processes/acc0.xml")
+    #
+    #     engine.register_participant(
+    #         "hr_resume_review_process",
+    #         "file:/var/processes/hr_resume_review_process.rb")
+    #
+    # Some more examples :
+    #
+    #     class RegistrationProcess < OpenWFE::ProcessDefinition
+    #         sequence do
+    #             participant :ref => "Alice"
+    #             participant :ref => "Bob"
+    #         end
+    #     end
+    #
+    #     # later in the code ...
+    #    
+    #     engine.register_participant("registration", RegistrationProcess)
+    #
+    # Or directly with some XML string :
+    #
+    #     engine.register_participant("registration", '''
+    #         <process-definition name="registration" revision="0.1">
+    #             <sequence>
+    #                 <participant ref="Alice" />
+    #                 <participant ref="Bob" />
+    #             </sequence>
+    #         </process-definition>
+    #     '''.strip)
+    #
+    # It's then easy to call the subprocess as if it were a participant :
+    #
+    #     sequence do
+    #         participant :ref => "registration"
+    #             # or
+    #         participant  "registration"
+    #             # or simply
+    #         registration
+    #     end
+    #
+    # Note that the 'subprocess' expression may be used as well :
+    #
+    #     sequence do
+    #         subprocess ref => "http://dms.company.org/processes/proc1.rb"
+    #     end
+    #
+    # But you can't use the URL as an expression name for writing nice,
+    # concise, process definitions.
+    #
+    class ProcessParticipant
+        include LocalParticipant
+
+        #
+        # The 'object' may be the URL of a process definition or the process
+        # definition itself as an XML string or a Ruby process definition
+        # (as a class or in a String).
+        #
+        def initialize (object)
+
+            super()
+
+            template_uri = OpenWFE::parse_known_uri object
+
+            @template = template_uri || object
+        end
+
+        #
+        # This is the method called by the engine when it has a workitem
+        # for this participant.
+        #
+        def consume (workitem)
+
+            get_expression_pool.launch_template(
+                get_flow_expression(workitem),
+                0, #sub_id
+                @template, 
+                workitem) 
+                #params)
+        end
+    end
+
 end
 

data/lib/openwfe/participants/soapparticipants.rb

@@ -30,8 +30,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 #++
 #
-# $Id$
-#
 
 #
 # "made in Japan"
@@ -57,8 +55,14 @@ module OpenWFE
     #     
     #     engine.register_participant("quote_service", quote_service)
     #
-    # You can override the method handle_call_result for better mappings 
-    # between web service calls and the workitems.
+    # By default, call params for the SOAP operations are determined by
+    # iterating the parameters and fetching the values under the 
+    # corresponding workitem fields.
+    # This behaviour can be changed by overriding the prepare_call_params()
+    # method.
+    # 
+    # On the return side, you can override the method handle_call_result 
+    # for better mappings between web service calls and the workitems.
     #
     class SoapParticipant 
         include LocalParticipant
@@ -77,6 +81,10 @@ module OpenWFE
             @driver.add_method(method_name, *params)
         end
 
+        #
+        # The method called by the engine when the flow reaches an instance
+        # of this Participant class.
+        #
         def consume (workitem)
 
             call_params = prepare_call_params(workitem)
@@ -97,7 +105,7 @@ module OpenWFE
         def prepare_call_params (workitem)
 
             @params.collect do |param|
-                get_param(workitem, param)
+                get_param workitem, param
             end
         end
 
@@ -117,9 +125,8 @@ module OpenWFE
             def get_param (workitem, param_name)
 
                 param_name = @param_prefix + param_name if @param_prefix
-                r = workitem.attributes[param_name]
-                return r if r
-                return ""
+
+                workitem.attributes[param_name] || ""
             end
 
     end