#
#--
# Copyright (c) 2006-2007, John Mettraux, OpenWFE.org
# All rights reserved.
# 
# Redistribution and use in source and binary forms, with or without 
# modification, are permitted provided that the following conditions are met:
# 
# . Redistributions of source code must retain the above copyright notice, this
#   list of conditions and the following disclaimer.  
# 
# . Redistributions in binary form must reproduce the above copyright notice, 
#   this list of conditions and the following disclaimer in the documentation 
#   and/or other materials provided with the distribution.
# 
# . Neither the name of the "OpenWFE" nor the names of its contributors may be
#   used to endorse or promote products derived from this software without
#   specific prior written permission.
# 
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
# 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 $
#

#
# "made in Japan"
#
# John Mettraux at openwfe.org
#

require 'uri'
require 'monitor'
require 'open-uri'
require 'rexml/document'

require 'openwfe/utils'
require 'openwfe/service'
require 'openwfe/logging'
require 'openwfe/rudefinitions'
require 'openwfe/flowexpressionid'
require 'openwfe/util/lru'
require 'openwfe/util/safe'
require 'openwfe/util/observable'
require 'openwfe/expressions/environment'
require 'openwfe/expressions/raw_xml'

include OpenWFE


module OpenWFE

    #
    # a small help class for storing monitors provided on demand 
    # to expressions that need them
    #
    class MonitorProvider
        include MonitorMixin, Logging

        MAX_MONITORS = 10000

        def initialize (application_context=nil)
            super()
            @application_context = application_context
            @monitors = LruHash.new(MAX_MONITORS)
        end

        def [] (key)
            synchronize do
                #ldebug { "[] caller :\n" + OpenWFE::caller_to_s(8) }
                mon = @monitors[key]
                if not mon
                    #ldebug { "[] creating new Monitor for  #{key}" }
                    mon = Monitor.new
                    @monitors[key] = mon
                else
                    #ldebug { "[] already had Monitor for  #{key}" }
                end
                return mon
            end
        end

        def delete (key)
            synchronize do
                #ldebug { "delete() removing Monitor for  #{key}" }
                @monitors.delete(key)
            end
        end
    end

    GONE = "gone"

    #
    # This special flow expression id is used by the forget() method
    # (which is used by the forget expression and the concurrence
    #  synchronization expressions)
    #
    GONE_PARENT_ID = FlowExpressionId.new
    GONE_PARENT_ID.engine_id = GONE
    GONE_PARENT_ID.initial_engine_id = GONE
    GONE_PARENT_ID.workflow_definition_url = GONE
    GONE_PARENT_ID.workflow_definition_name = GONE
    GONE_PARENT_ID.workflow_definition_revision = GONE
    GONE_PARENT_ID.workflow_instance_id = "-1"
    GONE_PARENT_ID.expression_name = GONE
    GONE_PARENT_ID.expression_id = "-1"
    GONE_PARENT_ID.freeze

    #
    # The ExpressionPool stores expressions (pieces of workflow instance).
    # It's the core of the workflow engine.
    # It relies on an expression storage for actual persistence of the
    # expressions.
    #
    class ExpressionPool
        include \
            ServiceMixin, 
            MonitorMixin, 
            OwfeServiceLocator, 
            Observable

        SAFETY_LEVEL = 2
            #
            # code loaded from a remote URI will get evaluated with 
            # that security level

        @@last_given_instance_id = -1
            #
            # storing at class level the last workflow instance id given

        def initialize (service_name, application_context)

            super()

            service_init(service_name, application_context)

            @monitors = MonitorProvider.new(application_context)

            @observers = {}

            @stopped = false
        end

        #
        # Makes sure to call the do_stop() method of the Stoppable mixin
        #
        def stop
            @stopped = true
            onotify :stop
        end

        #
        # Obtains a unique monitor for an expression.
        # It avoids the need for the FlowExpression instances to include
        # the monitor mixin by themselves
        #
        def get_monitor (fei)
            return @monitors[fei]
        end

        #
        # Instantiates a workflow definition and launches it.
        #
        # If async is set to true, the launch will occur in its own thread.
        #
        # Returns the FlowExpressionId instance of the root expression of
        # the newly launched flow.
        # If async is set to true, returns a tuple FlowExpressionId /
        # Thread instance used.
        #
        def launch (launchitem, async=false)

            onotify :launch, launchitem.workflow_definition_url

            procdef = fetch_definition(launchitem)

            raw_expression = build_raw_expression(
                launchitem.workflow_definition_url, procdef)

            raw_expression.new_environment()
                #
                # as this expression is the root of a new process instance,
                # it has to have an environment for all the variables of 
                # the process instance

            wi = build_workitem(launchitem)

            fei = raw_expression.fei

            if async

                t = OpenWFE::call_in_thread "launch()", self do
                    apply(raw_expression, wi)
                end

                return fei, t
            end

            apply(raw_expression, wi)

            return fei
        end

        #
        # launches a subprocess
        #
        def launch_template (
            requesting_expression, sub_id, template, workitem, params=nil)

            #ldebug { "launch_template() of class #{template.class}" }

            rawexp = nil

            if template.kind_of? FlowExpressionId

                rawexp, fei = fetch(template)

            elsif template.kind_of? URI

                rawexp = load_rawexp_from_uri(template)

            else # template is of kind RawExpression

                rawexp = template
            end

            ldebug { "launch_template() request for #{rawexp.fei.to_debug_s}" }

            onotify :launch_template, rawexp.fei

            rawexp = rawexp.dup()
            rawexp.fei = rawexp.fei.dup()

            if requesting_expression == nil

                rawexp.parent_id = nil
                rawexp.fei.workflow_instance_id = new_workflow_instance_id()

            elsif requesting_expression.kind_of? FlowExpressionId

                rawexp.parent_id = requesting_expression
                rawexp.fei.workflow_instance_id = \
                    "#{requesting_expression.workflow_instance_id}.#{sub_id}"

            elsif requesting_expression.kind_of? String

                rawexp.parent_id = nil
                rawexp.fei.workflow_instance_id = \
                    "#{requesting_expression}.${sub_id}"

            else # kind is FlowExpression

                rawexp.parent_id = requesting_expression.fei
                rawexp.fei.workflow_instance_id = \
                    "#{requesting_expression.fei.workflow_instance_id}.#{sub_id}"
            end

            #ldebug do
            #    p = ""
            #    p = rawexp.parent_id.to_debug_s if rawexp.parent_id
            #    "launch_template()\n"+
            #    "    rawexp.fei is #{rawexp.fei.to_debug_s}\n"+
            #    "    rawexp.parent_id is #{p}"
            #end
            
            #ldebug do
            #    "launch_template() spawning wfid " +
            #    "#{rawexp.fei.workflow_instance_id.to_s}"
            #end

            env = rawexp.new_environment()
                #
            params.each { |k, v| env[k] = v } if params
                #
                # the new scope gets its own environment

            rawexp.store_itself()

            workitem.flow_expression_id = rawexp.fei

            fei = rawexp.fei

            apply(rawexp, workitem)

            return fei
        end

        #
        # Evaluates a raw definition expression and
        # returns its body fei
        #
        def evaluate (rawExpression, workitem)

            exp = rawExpression.instantiate_real_expression(workitem)
            fei = exp.evaluate(workitem)

            #remove(rawExpression)
                #
                # not necessary, the raw expression gets overriden by
                # the real expression

            return fei
        end

        #
        # Applies a given expression (id or expression)
        #
        def apply (exp, workitem)

            exp, fei = fetch(exp) if exp.kind_of? FlowExpressionId

            #ldebug { "apply()  '#{fei}' (#{fei.class})" }

            if not exp
                lwarn { "apply() cannot apply missing  #{fei.to_debug_s}" }
                return
            end

            #ldebug { "apply()  #{fei.to_debug_s}" }

            #exp.apply_time = OpenWFE::now()
                #
                # this is done in RawExpression

            workitem.flow_expression_id = exp.fei

            onotify :apply, exp.fei, workitem

            exp.apply(workitem)
        end

        #
        # Cancels the given expression
        #
        def cancel (exp)

            exp, fei = fetch(exp)

            if not exp
                ldebug { "cancel() cannot cancel missing  #{fei.to_debug_s}" }
                return nil
            end

            ldebug { "cancel() for  #{fei.to_debug_s}" }

            onotify :cancel, fei

            inflowitem = exp.cancel()
            remove(exp)

            return inflowitem
        end

        #
        # Given any expression of a process, cancels the complete process.
        #
        def cancel_flow (exp)

            ldebug { "cancel_flow() from  #{exp}" }

            root = fetch_root(exp)
            cancel(root)
        end

        alias :cancel_process :cancel_flow

        #
        # Forgets the given expression (makes sure to substitute its
        # parent_id with the GONE_PARENT_ID constant)
        #
        def forget (exp)

            exp, fei = fetch(exp)

            return if not exp

            onotify :forget, fei

            exp.parent_id = GONE_PARENT_ID
            exp.store_itself()
        end

        #
        # Replies to the parent of the given expression.
        #
        def reply_to_parent (exp, workitem)

            ldebug { "reply_to_parent() for #{exp.fei.to_debug_s}" }

            workitem.last_expression_id = exp.fei

            onotify :reply_to_parent, exp.fei, workitem

            remove(exp)

            #
            # remove all the children of the expression

            exp.clean_children()

            if not exp.parent_id
                ldebug do 
                    "reply_to_parent() process " +
                    "#{exp.fei.workflow_instance_id} terminated"
                end
            else
                if exp.parent_id == GONE_PARENT_ID
                    ldebug do
                        "reply_to_parent() parent is gone for  " +
                        exp.fei.to_debug_s
                    end
                else
                    reply(exp.parent_id, workitem)
                end
            end
        end

        #
        # Triggers the reply expression of the expression given by its id.
        #
        def reply (exp, workitem)

            exp, fei = fetch(exp)

            ldebug { "reply() to   #{fei.to_debug_s}" }
            ldebug { "reply() from #{workitem.last_expression_id}" }

            if not exp
                #raise "cannot reply to missing  #{fei.to_debug_s}"
                lwarn { "reply() cannot reply to missing  #{fei.to_debug_s}" }
                return
            end

            onotify :reply, fei, workitem

            exp.reply(workitem)
        end

        #
        # Adds or updates a flow expression in this pool
        #
        def update (flowExpression)

            t = Timer.new

            onotify :update, flowExpression.fei, flowExpression

            #get_expression_storage()[flowExpression.fei] = flowExpression

            ldebug { "update() took #{t.duration} ms" }

            return flowExpression
        end

        #
        # Fetches a FlowExpression from the pool.
        # Returns a tuple : the FlowExpression plus its FlowExpressionId.
        #
        # The param 'exp' may be a FlowExpressionId or a FlowExpression that
        # has to be reloaded.
        # 
        def fetch (exp)
            synchronize do

                fei = exp

                #ldebug { "fetch() exp is of kind #{exp.class}" }

                if exp.kind_of? FlowExpression
                    fei = exp.fei 
                elsif not exp.kind_of? FlowExpressionId
                    raise \
                        "Cannot fetch expression with key : "+
                        "'#{fei}' (#{fei.class})"
                end

                ldebug { "fetch() for  #{fei.to_debug_s}" }

                return get_expression_storage()[fei], fei
            end
        end

        #
        # Fetches a FlowExpression (returns only the FlowExpression instance)
        #
        # The param 'exp' may be a FlowExpressionId or a FlowExpression that
        # has to be reloaded.
        #
        def fetch_expression (exp)
            exp, _fei = fetch(exp)
            return exp
        end

        #
        # Fetches the root expression of a process (given any of its
        # expressions).
        #
        def fetch_root (exp)
            exp = fetch_expression(exp)
            return exp unless exp.parent_id
            return fetch_root(fetch_expression(exp.parent_id))
        end

        #
        # Returns the engine environment (the top level environment)
        #
        def fetch_engine_environment ()
            synchronize do

                eei = engine_environment_id
                ee, fei = fetch(eei)

                if not ee
                    ee = Environment\
                        .new(eei, nil, nil, @application_context, nil)
                    ee.store_itself()
                end

                return ee
            end
        end

        #
        # Removes a flow expression from the pool
        # (This method is mainly called from the pool itself)
        #
        def remove (exp)

            exp, _fei = fetch(exp) \
                if exp.kind_of? FlowExpressionId

            return if not exp

            ldebug { "remove() fe  #{exp.fei.to_debug_s}" }

            onotify :remove, exp.fei

            synchronize do

                @monitors.delete(exp.fei)

                remove_environment(exp.environment_id) \
                    if exp.owns_its_environment?
            end
        end

        #
        # This method is called at each expool (engine) [re]start.
        # It roams through the previously saved (persisted) expressions
        # to reschedule ones like 'sleep' or 'cron'.
        #
        def reschedule

            return if @stopped

            synchronize do

                t = OpenWFE::Timer.new

                ldebug { "reschedule() initiating..." }

                get_expression_storage.each_of_kind(Schedulable) do |fe|

                    ldebug { "reschedule() for  #{fe.fei.to_debug_s}..." }

                    onotify :reschedule, fe.fei

                    fe.reschedule(get_scheduler)
                end

                ldebug { "reschedule() done. (took #{t.duration} ms)" }
            end
        end

        #
        # Returns the unique engine_environment FlowExpressionId instance.
        # There is only one such environment in an engine, hence this 
        # 'singleton' method.
        #
        def engine_environment_id ()
            synchronize do
                return @eei if @eei
                @eei = FlowExpressionId.new
                @eei.owfe_version = OPENWFERU_VERSION
                @eei.engine_id = get_engine.service_name
                @eei.initial_engine_id = @eei.engine_id
                @eei.workflow_definition_url = 'ee'
                @eei.workflow_definition_name = 'ee'
                @eei.workflow_definition_revision = '0'
                @eei.workflow_instance_id = '0'
                @eei.expression_name = EN_ENVIRONMENT
                @eei.expression_id = '0'
                return @eei
            end
        end

        #
        # Returns the list of applied expressions belonging to a given
        # workflow instance.
        #
        def get_flow_position (wfid)

            raise "please provide a non-nil workflow instance id" \
                unless wfid

            result = []

            get_expression_storage.real_each do |fei, fexp|

                next if fexp.kind_of? Environment
                next if fexp.kind_of? RawExpression
                next unless fexp.apply_time

                pi = fei.parent_wfid

                next if pi != wfid

                result << fexp
            end

            ldebug do 
                "get_flow_position() " +
                "found #{result.size} exps for flow #{wfid}" 
            end

            return result
        end

        protected

            #def evaluate_definition (raw_definition, workitem)
            #    expression = raw_definition.instantiate(workitem)
            #end

            #
            # Prepares the RawExpression for a 'remote' process definition
            # (a process definition pointed at via a URI).
            #
            def load_rawexp_from_uri (uri)

                procdef = determine_representation(uri.read)

                build_raw_expression(uri.to_s, procdef)
            end

            #
            # Removes an environment, especially takes care of unbinding
            # any special value it may contain.
            #
            def remove_environment (environment_id)

                ldebug { "remove_environment()  #{environment_id.to_debug_s}" }

                env, fei = fetch(environment_id)

                env.unbind()

                #get_expression_storage().delete(environment_id)

                onotify :remove, environment_id
            end

            #
            # Prepares a new instance of InFlowWorkItem from a LaunchItem
            # instance.
            #
            def build_workitem (launchitem)

                wi = InFlowWorkItem.new()

                wi.attributes = launchitem.attributes.dup()

                return wi
            end

            #
            # Given a string that contains either an XML process
            # definition, either a Ruby process definition
            # will return a 'representation' (what is used to build
            # a RawExpression instance).
            #
            def determine_representation (string_definition)

                if string_definition[0, 1] == "<"

                    xmlRoot = REXML::Document.new(string_definition).root
                    class << xmlRoot
                        def raw_expression_class
                            XmlRawExpression
                        end
                    end
                    return xmlRoot
                end

                # else

                #o = eval(string_definition)
                o = OpenWFE::eval_safely(string_definition, SAFETY_LEVEL)
                #o = OpenWFE::load_eval_safely(string_definition, SAFETY_LEVEL)
                #o = OpenWFE::eval_r_safely(string_definition, SAFETY_LEVEL)

                return o.do_make if o.kind_of? Class

                return o
            end

            #
            # Extracts the process definition that a launchitem points at.
            #
            def fetch_definition (launchitem)

                wfdUrl = launchitem.workflow_definition_url

                #ldebug { "wfdUrl is '#{wfdUrl}'" }

                sDefinition = nil
                wfdField = nil

                if wfdUrl[0..5] == 'field:'
                    wfdField = wfdUrl[6..-1]
                    sDefinition = launchitem.attributes[wfdField]
                else
                    sDefinition = URI.parse(wfdUrl).read
                end

                #ldebug { "sDefinition is \n#{sDefinition}" }

                launchitem.attributes.delete(wfdField) if wfdField

                return determine_representation(sDefinition) \
                    if sDefinition.kind_of? String

                return sDefinition \
                    if sDefinition.kind_of? ProgExpRepresentation

                return sDefinition.make \
                    if sDefinition.kind_of? ProcessDefinition

                return sDefinition.do_make \
                    if sDefinition.kind_of? Class

                # else...

                raise \
                    "Cannot deduce process definition " +
                    "out of instance of class #{sDefinition.class}"
            end

            #
            # Builds a FlowExpressionId instance for process being
            # launched.
            #
            def new_fei (flow_url, flow_name, flow_revision, exp_name)

                fei = FlowExpressionId.new

                fei.owfe_version = OPENWFERU_VERSION
                fei.engine_id = get_engine.service_name
                fei.initial_engine_id = fei.engine_id
                fei.workflow_definition_url = flow_url
                fei.workflow_definition_name = flow_name
                fei.workflow_definition_revision = flow_revision
                fei.workflow_instance_id = new_workflow_instance_id()
                fei.expression_id = "0"
                fei.expression_name = exp_name
                return fei
            end

            #
            # Returns a new unique workflow instance id
            #
            def new_workflow_instance_id ()

                synchronize do

                    wfid = OpenWFE::current_time_millis()

                    wfid = @@last_given_instance_id + 1 \
                        if wfid <= @@last_given_instance_id

                    @@last_given_instance_id = wfid

                    return wfid.to_s
                end
            end

            #
            # Builds the RawExpression instance at the root of the flow
            # being launched.
            #
            def build_raw_expression (url, procdef)

                flow_name = procdef.attributes['name']
                flow_revision = procdef.attributes['revision']
                exp_name = procdef.name

                fei = new_fei(url, flow_name, flow_revision, exp_name)

                #puts procdef.raw_expression_class
                #puts procdef.raw_expression_class.public_methods

                return procdef.raw_expression_class\
                    .new(fei, nil, nil, @application_context, procdef)
            end

    end

end