openwferu 0.9.0 → 0.9.1

data/README

@@ -7,7 +7,10 @@ Ruby 1.8.0 or later
 TODO
 
 == Installation
-TODO
+Installation can be handled by Ruby gems.  This will pull in any libraries
+you will need to install
+
+  gem install -y openwferu
 
 == Overview
 OpenWFEru is a Ruby port of the OpenWFE workflow engine 
@@ -29,11 +32,56 @@ These are mostly stolen from the unit tests
 
 Creating an workflow engine instance
 
+  require 'pp'
   require 'openwferu'
 
-  engine = OpenWFEru::Engine.new()
+  # Create an engine to launch the flow
+  engine = OpenWFEru::Engine.new
   engine.register_participant('test-.*', 
                               OpenWFEru::PrintParticipant.new())
+  # Create a flow definition and assign to a new instance
+  flow = '''<process-definition name="equals_0" revision="0">
+    <sequence>
+        <equals value="a" other-value="a" />
+        <print>${field:__result__}</print>
+    </sequence>
+  </process-definition>'''
+  li = OpenWFE::LaunchItem.new
+  li.workflowDefinitionUrl = "field:__definition"
+  li.attributes['__definition'] = flow
+  # Launch the instance
+  engine.launch(li)
+  # Examine it
+  exp_storage = engine.application_context[OpenWFEru::S_EXPRESSION_STORAGE]
+  pp exp_storage
+
+== How to help
+
+If you want to help hacking on openwferu you'll probably want the following
+libraries: 
+[+rake+] Handle builds, generating documentation, and running unit tests
+[rubygems] Handles creation of the gems
+[rote] A framework being used to help with managing the offline written docs
+[redcloth] Openwferu uses textile-markup for its docs.  Redcloth provides an engine for it.
+[tidy] General cleanup
+[libxml-ruby] Allows XSD validation
+
+It's best if you use gems to install these as the process can get rather
+tedious by hand.
+
+=== Prerequisites
+You'll need libxml2-dev in order to compile the native libraries
+for libxml.  Please check your your packaging system for the appropriate
+name.
+
+On Ubuntu you can install libxml2 with:
+  sudo apt-get install libxml2-dev
+
+=== Ruby Libraries Install
+1. gem install -r rake
+2. gem install -r rote redcloth 
+3. gem install -r tidy    
+4. gem install -r libxml-ruby
 
 == Documentation
 

data/bin/validate-workflow.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+#
+# Program Name:  validate-workflow.rb
+# Purpose:       A helper script that validates a workflow document against
+#                a XML Schema
+# Author:        Alain Hoang
+# Version:       0.1
+# Notes:         Uses Ruby's libxml library to handle the parsing
+
+# Stdlib
+require 'net/http'
+require 'uri'
+# From the gems archive
+require 'rubygems'
+require 'xml/libxml'
+
+
+module OpenWFEru
+    # Validates a workflow definition against the Workflow XML Schema
+    # defined at http://www.openwfe.org/flowdef.xsd
+    class WorkflowValidator
+        OPENWFE_FLOWDEF_URL='http://www.openwfe.org/flowdef.xsd'
+
+        # Class method for validating a xml file against the
+        # OpenWFE XML Schema
+        def WorkflowValidator.validate(file)
+            # Should only be initialized once during the lifetime
+            # of the program
+            if not defined? @@schema
+                xsd_str = Net::HTTP.get URI.parse(OPENWFE_FLOWDEF_URL)
+                @@schema = XML::Schema.from_string(xsd_str)
+            end
+	        xmldoc = XML::Document.file(file)
+	        xmldoc.validate_schema(@@schema)
+        end
+    end
+end
+
+def usage
+    print "Usage: #{$0} <workflow def> [workflow def] [workflow def] ...\n"
+    print "  <workflow def> - workflow definition file\n"
+end
+
+def main
+	# Make sure we have at least one argument or bail
+	if ARGV.length == 0
+	    usage
+	    exit 1
+	end
+
+    # Loop through all arguments and validate the file
+	ARGV.each do |f|
+        print "Trying to validate #{f}...  "
+        if OpenWFEru::WorkflowValidator.validate(f)
+            print "PASSED\n"
+        else
+            print "FAILED\n"
+        end
+	end
+end
+
+if $0 == __FILE__
+    main
+end

data/lib/codec.rb

@@ -1,4 +1,5 @@
 #
+#<tt>
 # Copyright (c) 2005-2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
+#</tt>
 #
 # $Id: codec.rb 2865 2006-06-23 14:54:07Z jmettraux $
 #

data/lib/controlclient.rb

@@ -1,4 +1,5 @@
 #
+#--
 # Copyright (c) 2005-2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
+#++
 #
 # $Id: controlclient.rb 3454 2006-10-08 16:51:00Z jmettraux $
 #
@@ -64,6 +66,19 @@ module OpenWFE
             return decode(r)
         end
 
+        #
+        # Returns the list of expressions currently applied for a given
+        # workflow instance
+        #
+        def get_flow_position (workflowInstanceId)
+
+            params = {}
+            params['id'] = workflowInstanceId
+
+            r = self.get('getflowposition', nil, params)
+            return decode(r)
+        end
+
         #
         # Cancels a given expression (and potentially its whole subtree)
         #
@@ -100,6 +115,10 @@ module OpenWFE
             return decode(self.post('unfreezeexpression', nil, params, fei))
         end
 
+        alias list_expressions listExpressions
+        alias cancel_expression cancelExpression
+        alias freeze_expression freezeExpression
+        alias unfreeze_expression unfreezeExpression
 
         protected
 

data/lib/definitions.rb

@@ -1,4 +1,5 @@
 #
+#<tt>
 # Copyright (c) 2005-2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
+#</tt>
 #
 # $Id: definitions.rb 3454 2006-10-08 16:51:00Z jmettraux $
 #

data/lib/exception.rb

@@ -1,4 +1,5 @@
 #
+#<tt>
 # Copyright (c) 2005-2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
+#</tt>
 #
 # $Id: exception.rb 3454 2006-10-08 16:51:00Z jmettraux $
 #

data/lib/flowexpressionid.rb

@@ -1,4 +1,5 @@
 #
+#--
 # Copyright (c) 2005-2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
+#++
 #
 # $Id: workitem.rb 3555 2006-11-13 00:47:53Z jmettraux $
 #
@@ -65,7 +67,7 @@ module OpenWFE
         # overrides the classical to_s()
         #
         def to_s ()
-            return "(fei #{@owfeVersion} #{@engineId}/#{@initialEngineId} #{@workflowDefinitionUrl} #{@workflowDefinitionName} #{@workflowDefinitionRevision} #{@workflowInstanceId} #{@expressionName} #{@expressionId} )"
+            return "(fei #{@owfeVersion} #{@engineId}/#{@initialEngineId} #{@workflowDefinitionUrl} #{@workflowDefinitionName} #{@workflowDefinitionRevision} #{@workflowInstanceId} #{@expressionName} #{@expressionId})"
         end
 
         #
@@ -127,10 +129,10 @@ module OpenWFE
 
         alias eql? ==
 
-        #alias to_debug_s to_s
-        def to_debug_s
-            "#{to_s}  (h#{hash}) (i#{object_id})"
-        end
+        alias to_debug_s to_s
+        #def to_debug_s
+        #    "#{to_s}  (h#{hash}) (i#{object_id})"
+        #end
     end
 
 end

data/lib/openwferu.rb

@@ -1,4 +1,5 @@
 #
+#<tt>
 # Copyright (c) 2005-2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 #
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
+#</tt>
 #
 #++
 #

data/lib/osocket.rb

@@ -1,4 +1,5 @@
 #
+#<tt>
 # Copyright (c) 2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
+#</tt>
 #
 # $Id: codec.rb 2515 2006-04-26 18:38:39Z jmettraux $
 #

data/lib/otime.rb

@@ -1,4 +1,5 @@
 #
+#<tt>
 # Copyright (c) 2005-2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
+#</tt>
 #
 # $Id: otime.rb 3509 2006-10-21 12:00:52Z jmettraux $
 #

data/lib/restclient.rb

@@ -1,4 +1,5 @@
 #
+#--
 # Copyright (c) 2005-2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
+#++
 #
 # $Id: restclient.rb 3454 2006-10-08 16:51:00Z jmettraux $
 #

data/lib/ru/contextual.rb

@@ -1,4 +1,5 @@
 #
+#--
 # Copyright (c) 2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # 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 $
 #

data/lib/ru/dollar.rb

@@ -1,4 +1,5 @@
 #
+#<tt>
 # Copyright (c) 2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
+#</tt>
 #
 # $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
 #

data/lib/ru/engine.rb

@@ -1,4 +1,5 @@
 #
+#--
 # Copyright (c) 2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # 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 $
 #

data/lib/ru/environment.rb

@@ -1,4 +1,5 @@
 #
+#<tt>
 # Copyright (c) 2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
+#</tt>
 #
 # $Id: definitions.rb 2725 2006-06-02 13:26:32Z jmettraux $
 #

data/lib/ru/expressionmap.rb

@@ -1,4 +1,5 @@
 #
+#--
 # Copyright (c) 2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # 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 $
 #
@@ -89,6 +91,9 @@ module OpenWFEru
 
             @map["reval"] = RevalExpression
             @map["print"] = PrintExpression
+
+            @map["lose"] = LoseExpression
+            @map["forget"] = ForgetExpression
         end
 
         #

data/lib/ru/expressionpool.rb

@@ -1,4 +1,5 @@
 #
+#--
 # Copyright (c) 2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # 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 $
 #
@@ -119,18 +121,40 @@ module OpenWFEru
         end
 
         #
-        # Applies a given expression (id)
+        # Evaluates a raw definition expression and
+        # returns its body fei
         #
-        def apply (flowExpressionId, workitem)
+        def evaluate (rawExpression, workitem)
+            exp = rawExpression.instantiate_real_expression(workitem)
+            fei = exp.evaluate(workitem)
+            remove(rawExpression)
+            return fei
+        end
 
-            ldebug { "apply()  #{flowExpressionId.to_debug_s}" }
+        #
+        # Applies a given expression (id or expression)
+        #
+        def apply (exp, workitem)
 
-            workitem.lastExpressionId = flowExpressionId
+            exp = fetch(exp) if exp.kind_of? OpenWFE::FlowExpressionId
+
+            ldebug { "apply()  #{exp.fei.to_debug_s}" }
+
+            workitem.lastExpressionId = exp.fei
 
-            exp = fetch(flowExpressionId)
             exp.apply(workitem)
         end
 
+        #
+        # Cancels the given expression
+        #
+        def cancel (exp)
+            exp = fetch(exp) if exp.kind_of? OpenWFE::FlowExpressionId
+            inflowitem = exp.cancel()
+            remove(exp)
+            return inflowitem
+        end
+
         #
         # Replies to the parent of the given expression.
         #
@@ -154,8 +178,23 @@ module OpenWFEru
         # Triggers the reply expression of the expression given by its id.
         #
         def reply (flowExpressionId, workitem)
-            ldebug { "reply()  #{flowExpressionId.to_debug_s}" }
+
+            ldebug { "reply() to   #{flowExpressionId.to_debug_s}" }
+            ldebug { "reply() from #{workitem.last_expression_id}" }
+
             exp = fetch(flowExpressionId)
+
+            if not exp
+                #raise \
+                #    "cannot reply to missing expression " + 
+                #    flowExpressionId.to_debug_s
+                lwarn do
+                    "reply() cannot reply to missing  "+
+                    flowExpressionId.to_debug_s
+                end
+                return
+            end
+
             exp.reply(workitem)
         end
 
@@ -266,6 +305,10 @@ module OpenWFEru
 
         protected
 
+            def evaluate_definition (raw_definition, workitem)
+                expression = raw_definition.instantiate(workitem)
+            end
+
             def remove_environment (environment_id)
                 env = fetch(environment_id)
                 env.unbind()

data/lib/ru/expressionstorage.rb

@@ -1,4 +1,5 @@
 #
+#--
 # Copyright (c) 2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # 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 $
 #
@@ -82,7 +84,7 @@ module OpenWFEru
                 if v.kind_of?(RawExpression)
                     s << "*raw" 
                 else
-                    s << "    "
+                    s << "  "
                 end
                 s << v.to_s
                 s << "    key/value mismatch !" if k != v.fei

data/lib/ru/fe_base.rb

@@ -1,4 +1,5 @@
 #
+#--
 # Copyright (c) 2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # 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 $
 #
@@ -86,7 +88,8 @@ module OpenWFEru
                 end
                 found = false
                 @children.each do |c|
-                    ldebug { "next_fei() considering #{c} (found ? #{found})" }
+                    #ldebug { "next_fei() considering #{c} (found ? #{found})" }
+                    ldebug { "next_fei() considering #{c}" }
                     if found 
                         return c if c.kind_of?(OpenWFE::FlowExpressionId)
                         next

data/lib/ru/fe_concurrence.rb

@@ -1,4 +1,5 @@
 #
+#--
 # Copyright (c) 2006, John Mettraux, OpenWFE.org
 # All rights reserved.
 # 
@@ -27,6 +28,7 @@
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 # 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 $
 #
@@ -37,6 +39,7 @@
 # John Mettraux at openwfe.org
 #
 
+require 'monitor'
 require 'ru/flowexpression'
 require 'ru/rudefinitions'
 require 'ru/ruutils'
@@ -57,14 +60,20 @@ module OpenWFEru
 
             sync = lookup_attribute(A_SYNC, workitem)
             sync = "generic" if not sync
-            @sync_expression = get_expression_map().get_sync_class(sync).new()
+
+            @sync_expression = \
+                get_expression_map().get_sync_class(sync).new(@attributes)
 
             #threads = []
 
+            @children.each do |child|
+                @sync_expression.add_child(child)
+            end
+
             @children.each do |child|
                 t = Thread.new do
                     begin
-                        @sync_expression.apply_child(self, child, workitem)
+                        get_expression_pool().apply(child, workitem.dup)
                     rescue Exception => e
                         lwarn do 
                             "apply() caught exception in concurrent child\n" + 
@@ -93,29 +102,92 @@ module OpenWFEru
 
     class GenericSyncExpression < SyncExpression
 
-        def initialize ()
+        attr_accessor \
+            :remaining_children,
+            :count,
+            :reply_count,
+            :cancel_remaining
+
+        def initialize (attributes)
+
             super()
+
+            @remaining_children = []
             @reply_count = 0
+
+            @count = determine_count(attributes)
+            @cancel_remaining = determine_remaining(attributes)
         end
 
-        def apply_child (synchable, child, workitem)
-            synchronize do
-                @application_context = synchable.application_context
-                ldebug { "apply_child()  #{child.to_debug_s}" }
-                synchable.get_expression_pool().apply(child, workitem.dup)
-            end
+        def add_child (child)
+            @remaining_children << child
         end
 
         def reply (synchable, workitem)
             synchronize do
+
                 @application_context = synchable.application_context
+                    #
+                    # ldebug uses the application context
+
                 ldebug { "reply()  #{workitem.lastExpressionId.to_debug_s}" }
+
                 @reply_count = @reply_count + 1
+
+                @remaining_children.delete(workitem.last_expression_id)
+
                 return workitem \
-                    if @reply_count >= synchable.children.length
+                    if @remaining_children.length <= 0
+
+                if @count > 0 and @reply_count >= @count
+                    treat_remaining_children(synchable)
+                    return workitem
+                end
+
                 return nil
             end
         end
+
+        protected
+
+            def treat_remaining_children (synchable)
+
+                expool = synchable.get_expression_pool
+
+                @remaining_children.each do |child|
+                    if @cancel_remaining
+                        expool.cancel(child)
+                    else
+                        expool.remove(child)
+                    end
+                end
+            end
+
+            def determine_remaining (attributes)
+                return attributes[A_REMAINING] == REM_CANCEL
+            end
+
+            def determine_count (attributes)
+                s = attributes[A_COUNT]
+                return -1 if not s
+                i = s.to_i
+                return -1 if i < 1
+                return i
+            end
+    end
+
+    #
+    # Merges a workitem (source) into another (target).
+    # If inPlace is left to false, a brand new workitem is returned,
+    # else the merge occurs directly into the target workitem.
+    #
+    def merge (wiTarget, wiSource, inPlace=false)
+
+        wiTarget = wiTarget.dup if not inPlace
+
+        wiSource.attributes.each do | k, v |
+            wiTarget.attributes[k.dup] = v.dup
+        end
     end
 
 end