ruote-maestrodev 2.2.1

data/lib/ruote/reader/ruby_dsl.rb

@@ -0,0 +1,186 @@
+#--
+# 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 'sourcify'
+require 'ruote/util/ometa'
+
+
+module Ruote
+
+  # Not really a reader, more an AST builder.
+  #
+  #   pdef = Ruote.define :name => 'take_out_garbage' do
+  #     sequence do
+  #       take_out_regular_garbage
+  #       take_out_glass
+  #       take_out_paper
+  #     end
+  #   end
+  #
+  #   engine.launch(pdef)
+  #
+  def self.define(*attributes, &block)
+
+    RubyDsl.create_branch('define', attributes, &block)
+  end
+
+  # Same as Ruote.define()
+  #
+  #   pdef = Ruote.process_definition :name => 'take_out_garbage' do
+  #     sequence do
+  #       take_out_regular_garbage
+  #       take_out_paper
+  #     end
+  #   end
+  #
+  #   engine.launch(pdef)
+  #
+  def self.process_definition(*attributes, &block)
+
+    define(*attributes, &block)
+  end
+
+  # Similar in purpose to Ruote.define and Ruote.process_definition but
+  # instead of returning a [process] definition, returns the tree.
+  #
+  #   tree = Ruote.process_definition :name => 'take_out_garbage' do
+  #     sequence do
+  #       take_out_regular_garbage
+  #       take_out_paper
+  #     end
+  #   end
+  #
+  #   p tree
+  #     # => [ 'sequence', {}, [ [ 'take_out_regular_garbage', {}, [] ], [ 'take_out_paper', {}, [] ] ] ],
+  #
+  # This is useful when modifying a process instance via methods like re_apply :
+  #
+  #   engine.re_apply(
+  #     fei,
+  #     :tree => Ruote.to_tree {
+  #       sequence do
+  #         participant 'alfred'
+  #         participant 'bob'
+  #       end
+  #     })
+  #       #
+  #       # cancels the segment of process at fei and replaces it with
+  #       # a simple alfred-bob sequence.
+  #
+  def self.to_tree(&block)
+
+    RubyDsl.create_branch('x', {}, &block).last.first
+  end
+
+  # :nodoc:
+  #
+  module RubyDsl
+
+    class BranchContext < Ruote::BlankSlate
+
+      def initialize(name, attributes)
+
+        @name = name
+        @attributes = attributes
+        @children = []
+      end
+
+      def method_missing(m, *args, &block)
+
+        @children.push(Ruote::RubyDsl.create_branch(m.to_s, args, &block))
+      end
+
+      def to_a
+
+        [ @name, @attributes, @children ]
+      end
+    end
+
+    def self.create_branch(name, attributes, &block)
+
+      name = name[1..-1] while name[0, 1] == '_'
+
+      h = attributes.inject({}) { |h1, a|
+
+        a.is_a?(Hash) ? h1.merge!(a) : h1[a] = nil
+
+        h1
+
+      }.inject({}) { |h1, (k, v)|
+
+        k = k.is_a?(Regexp) ? k.inspect : k.to_s
+        h1[k] = to_json(v)
+
+        h1
+      }
+
+      c = BranchContext.new(name, h)
+      c.instance_eval(&block) if block
+
+      c.to_a
+    end
+
+    def self.to_json(v)
+
+      case v
+        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 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

@@ -0,0 +1,99 @@
+#--
+# 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 'rexml/parsers/sax2parser'
+require 'rexml/sax2listener'
+
+
+module Ruote
+
+  #
+  # Turns an XML string into a process definition tree.
+  #
+  module XmlReader
+
+    # Returns true if the string seems to be an XML string.
+    #
+    def self.understands?(s)
+
+      s.match(/<[a-z]+>/) != nil
+    end
+
+    #
+    # A helper class to store the temporary tree while it gets read.
+    #
+    class Node
+
+      attr_reader :parent, :attributes, :children
+
+      def initialize(parent, name, attributes)
+
+        @parent = parent
+        @name = name
+        @attributes = attributes.inject({}) { |h, (k, v)|
+          h[k.gsub(/-/, '_')] = v
+          h
+        }
+        @children = []
+
+        parent.children << self if parent
+      end
+
+      def to_a
+
+        [ @name, @attributes, @children.collect { |c| c.to_a } ]
+      end
+    end
+
+    # Parses the XML string into a process definition tree (array of arrays).
+    #
+    def self.read(s, opt=nil)
+
+      parser = REXML::Parsers::SAX2Parser.new(s)
+
+      root = nil
+      current = nil
+
+      # u, l, q, a <=> url, local, qname, attributes
+
+      parser.listen(:start_element) do |u, l, q, a|
+        current = Node.new(current, l.gsub(/-/, '_'), a)
+        root ||= current
+      end
+      parser.listen(:end_element) do |u, l, q, a|
+        current = current.parent
+      end
+
+      parser.listen(:characters) do |text|
+        t = text.strip
+        current.attributes[t] = nil if t.size > 0
+      end
+
+      parser.parse
+
+      root.to_a
+    end
+  end
+end
+

data/lib/ruote/receiver/base.rb

@@ -0,0 +1,212 @@
+#--
+# 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
+
+  #
+  # The core methods for the Receiver class (sometimes a Mixin is easier
+  # to integrate).
+  #
+  # (The engine itself includes this mixin, the LocalParticipant module
+  # includes it as well).
+  #
+  module ReceiverMixin
+
+    # This method pipes back a workitem into the engine, letting it resume
+    # in its flow, hopefully.
+    #
+    def receive(workitem)
+
+      workitem = workitem.to_h if workitem.respond_to?(:to_h)
+
+      @context.storage.put_msg(
+        'receive',
+        'fei' => workitem['fei'],
+        'workitem' => workitem,
+        'participant_name' => workitem['participant_name'],
+        'receiver' => sign)
+    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).
+    #
+    # process_definition must be a result of Ruote.process_definition call
+    # or XML or JSON serialized process definition, as accepted by
+    # Ruote::Reader#read.
+    #
+    # fields are workflow parameters that will be placed in workitem.fields.
+    #
+    # variables contain engine variables.
+    #
+    def launch(process_definition, fields={}, variables={})
+
+      wfid = @context.wfidgen.generate
+
+      @context.storage.put_msg(
+        'launch',
+        'wfid' => wfid,
+        'tree' => @context.reader.read(process_definition),
+        'workitem' => { 'fields' => fields },
+        'variables' => variables)
+
+      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.
+    #
+    def sign
+
+      self.class.to_s
+    end
+
+    # Convenience method, given a workitem or a fei, returns the
+    # corresponding flow expession.
+    #
+    def fetch_flow_expression(workitem_or_fei)
+
+      Ruote::Exp::FlowExpression.fetch(
+        @context,
+        Ruote::FlowExpressionId.extract_h(workitem_or_fei))
+    end
+
+    # For example :
+    #
+    #   fexp = engine.fexp(fei)
+    #     # or
+    #   fexp = engine.fexp(workitem)
+    #
+    alias fexp fetch_flow_expression
+
+    # A convenience methods for advanced users (like Oleg).
+    #
+    # Given a fei (flow expression id), fetches the workitem as stored in
+    # the expression with that fei.
+    # This is the "applied workitem", if the workitem is currently handed to
+    # a participant, this method will return the workitem as applied, not
+    # the workitem as saved by the participant/user in whatever worklist it
+    # uses. If you need that workitem, do the vanilla thing and ask it to
+    # the [storage] participant or its worklist.
+    #
+    # The fei might be a string fei (result of fei.to_storage_id), a
+    # FlowExpressionId instance or a hash.
+    #
+    # 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)
+
+      Ruote::Workitem.new(fexp(fei).h.applied_workitem)
+    end
+    alias workitem applied_workitem
+
+    protected
+
+    # Stashes values in the participant expression (in the storage).
+    #
+    #   put(workitem.fei, 'key' => 'value', 'colour' => 'blue')
+    #
+    # Remember that keys/values must be serializable in JSON.
+    #
+    # put & get are useful for a participant that needs to communicate
+    # between its consume and its cancel.
+    #
+    # See the thread at
+    # http://groups.google.com/group/openwferu-users/t/2e6a95708c10847b for the
+    # justification.
+    #
+    def put(fei, hash)
+
+      fexp = Ruote::Exp::FlowExpression.fetch(@context, fei.to_h)
+
+      (fexp.h['stash'] ||= {}).merge!(hash)
+
+      fexp.persist_or_raise
+    end
+
+    # Fetches back a stashed value.
+    #
+    #   get(fei, 'colour')
+    #     # => 'blue'
+    #
+    # To return the whole stash
+    #
+    #   get(fei)
+    #     # => { 'colour' => 'blue' }
+    #
+    # 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)
+
+      stash = fexp.h['stash'] rescue {}
+
+      key ? stash[key] : stash
+    end
+  end
+
+  #
+  # A receiver is meant to receive workitems and feed them back into the
+  # engine (the storage actually).
+  #
+  class Receiver
+    include ReceiverMixin
+
+    # Accepts context, worker, engine or storage as first argument.
+    #
+    def initialize(cwes, options={})
+
+      @context = cwes.context
+      @options = options
+    end
+  end
+end
+