#
#--
# Copyright (c) 2006-2007, John Mettraux, Nicolas Modrzyk 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
# Nicolas Modrzyk at openwfe.org
# 

require 'logger'

require 'openwfe/workitem'
require 'openwfe/rudefinitions'
require 'openwfe/service'
require 'openwfe/util/scheduler'
require 'openwfe/util/schedulers'
require 'openwfe/expool/wfidgen'
require 'openwfe/expool/expressionpool'
require 'openwfe/expool/expstorage'
require 'openwfe/expressions/expressionmap'
require 'openwfe/participants/participantmap'


module OpenWFE

    #
    # The simplest implementation of the OpenWFE workflow engine.
    # No persistence is used, everything is stored in memory.
    #
    class Engine < Service
        include OwfeServiceLocator

        #
        # Builds an OpenWFEru engine.
        #
        def initialize ()

            super(S_ENGINE, {})

            @application_context[@service_name] = self

            $OWFE_LOG = Logger.new("engine.log") unless $OWFE_LOG

            # build order matters.
            #
            # especially for the expstorage which 'observes' the expression
            # pool and thus needs to be instantiated after it.

            build_scheduler()

            build_expression_map()

            build_wfid_generator()
            build_expression_pool()
            build_expression_storage()

            build_participant_map()

            #get_expression_pool.reschedule()

            linfo { "new() --- engine started --- #{self.object_id}" }
        end

        #
        # Call this method once the participant for a persisted engine
        # have been [re]added.
        # If you call this method too soon, missing participants will 
        # cause troubles... Call this method after all the participants
        # have been added.
        #
        def reschedule
            get_expression_pool.reschedule()
        end

        alias :reload :reschedule

        #
        # When 'parameters' are used at the top of a process definition, this
        # method can be used to assert a launchitem before launch.
        # An expression will get raised if the parameters do not match the
        # requirements.
        #
        # Note that the launch method will raise those exceptions as well.
        # This method can be useful in some scenarii though.
        #
        def pre_launch_check (launchitem)
            get_expression_pool.prepare_raw_expression(launchitem)
        end

        #
        # Launches a [business] process.
        # The 'launch_object' param may contain either a LaunchItem instance, 
        # either a String containing the URL of the process definition
        # to launch (with an empty LaunchItem created on the fly).
        #
        # If async is set to true, the process will be launched asynchronously
        # (in his own thread).
        #
        # Returns a FlowExpressionId instance or a tuple FlowExpressionId / 
        # Thread object if async is set to true.
        #
        def launch (launch_object, async=false)

            launchitem = nil

            if launch_object.kind_of? OpenWFE::LaunchItem

                launchitem = launch_object

            elsif launch_object.kind_of? Class

                launchitem = LaunchItem.new(launch_object)

            elsif launch_object.kind_of? String

                launchitem = OpenWFE::LaunchItem.new

                if launch_object[0] == '<'
                    launchitem.workflowDefinitionUrl = "field:__definition"
                    launchitem['definition'] = launch_object
                else
                    launchitem.workflowDefinitionUrl = launch_object
                end
            end

            get_expression_pool.launch(launchitem, async)
        end

        #
        # This method is used to feed a workitem back to the engine (after
        # it got sent to a worklist or wherever by a participant).
        # Participant implementations themselves do call this method usually.
        #
        # This method also accepts LaunchItem instances.
        #
        def reply (workitem)

            if workitem.kind_of? InFlowWorkItem

                get_expression_pool.reply(workitem.flow_expression_id, workitem)

            elsif workitem.kind_of? LaunchItem

                get_expression_pool.launch(workitem, false)

            else

                raise \
                    "engine.reply() " +
                    "cannot handle instances of #{workitem.class}"
            end
        end

        #
        # Registers a participant in this [embedded] engine.
        # This method is a shortcut to the ParticipantMap method
        # with the same name.
        #
        # Returns the participant instance.
        #
        # see ParticipantMap#register_participant
        #
        def register_participant (regex, participant=nil, &block)

            get_participant_map.register_participant(regex, participant, &block)
        end

        #
        # Given a participant name, returns the participant in charge
        # of handling workitems for that name.
        # May be useful in some embedded contexts.
        #
        def get_participant (participant_name)

            get_participant_map.lookup_participant(participant_name)
        end

        #
        # Removes the first participant matching the given name from the
        # participant map kept by the engine.
        #
        def unregister_participant (participant_name)

            get_participant_map.unregister_participant(participant_name)
        end

        #
        # Adds a workitem listener to this engine.
        #
        # The 'freq' parameters if present might indicate how frequently
        # the resource should be polled for incoming workitems.
        #
        #     engine.add_workitem_listener(listener, "3m10s")
        #        # every 3 minutes and 10 seconds
        #
        #     engine.add_workitem_listener(listener, "0 22 * * 1-5")
        #        # every weekday at 10pm
        #
        # TODO : block handling...
        #
        def add_workitem_listener (listener, freq=nil)

            name = nil

            if listener.kind_of? Class

                listener = init_service(nil, listener)

                name = listener.service_name
            else

                name = listener.name if listener.respond_to? :name
                name = "#{listener.class}::#{listener.object_id}" unless name

                @application_context[name] = listener
            end

            result = nil

            if freq

                freq = freq.to_s.strip

                result = if Scheduler.is_cron_string(freq)

                    get_scheduler.schedule(freq, nil, listener, nil)
                else

                    get_scheduler.schedule_every(freq, listener, nil)
                end
            end

            linfo { "add_workitem_listener() added '#{name}'" }

            result
        end

        #
        # Makes the current thread join the engine's scheduler thread
        #
        # You can thus make an engine standalone with something like :
        #
        #     require 'openwfe/engine/engine'
        #
        #     the_engine = OpenWFE::Engine.new
        #     the_engine.join
        #
        # And you'll have to hit CTRL-C to make it stop.
        #
        def join

            get_scheduler.join
        end

        #
        # Stopping the engine will stop all the services in the
        # application context.
        #
        def stop

            linfo { "stop() stopping engine '#{@service_name}'" }

            @application_context.each do |name, service|

                next if name == self.service_name

                #service.stop if service.respond_to? :stop

                if service.kind_of? ServiceMixin
                    service.stop
                    linfo do 
                        "stop() stopped service '#{service.service_name}' "+
                        "(#{service.class})"
                    end
                end
            end
        end

        #
        # METHODS FROM THE EXPRESSION POOL
        #
        # These methods are 'proxy' to method found in the expression pool.
        # They are made available here for a simpler model.
        #

        #
        # Returns the list of applied expressions belonging to a given
        # workflow instance.
        # May be used to determine where a process instance currently is.
        #
        def get_flow_position (workflow_instance_id)
            get_expression_pool.get_flow_position(workflow_instance_id)
        end
        alias :get_process_position :get_flow_position

        #
        # Lists all workflows (processes) currently in the expool (in
        # the engine).
        # This method will return a list of "process-definition" expressions
        # (root of flows).
        #
        # If consider_subprocesses is set to true, "process-definition" 
        # expressions of subprocesses will be returned as well.
        #
        # "wfid_prefix" allows your to query for specific workflow instance
        # id prefixes.
        #
        def list_workflows (consider_subprocesses=false, wfid_prefix=nil)

            get_expression_pool.list_workflows(
                consider_subprocesses, wfid_prefix)
        end
        alias :list_processes :list_workflows

        #
        # Given any expression of a process, cancels the complete process
        # instance.
        #
        def cancel_flow (exp_or_wfid)
            get_expression_pool.cancel_flow(exp_or_wfid)
        end
        alias :cancel_process :cancel_flow

        #
        # Cancels the given expression (and its children if any)
        # (warning : advanced method)
        #
        def cancel_expression (exp_or_fei)
            get_expression_pool.cancel(exp_or_fei)
        end

        #
        # Forgets the given expression (make it an orphan)
        # (warning : advanced method)
        #
        def forget_expression (exp_or_fei)
            get_expression_pool.forget(exp_or_fei)
        end

        protected

            #
            # the following methods may get overridden upon extension
            # see for example file_persisted_engine.rb
            #

            def build_expression_map ()

                @application_context[S_EXPRESSION_MAP] = ExpressionMap.new
                    #
                    # the expression map is not a Service anymore,
                    # it's a simple instance (that will be reused in other
                    # OpenWFEru components)

                #ldebug do 
                #    "build_expression_map() :\n" +
                #    get_expression_map.to_s
                #end
            end

            def build_wfid_generator ()

                #init_service(S_WFID_GENERATOR, DefaultWfidGenerator)
                #init_service(S_WFID_GENERATOR, UuidWfidGenerator)
                init_service(S_WFID_GENERATOR, KotobaWfidGenerator)
            end

            def build_expression_pool ()

                init_service(S_EXPRESSION_POOL, ExpressionPool)
            end

            def build_expression_storage ()

                init_service(S_EXPRESSION_STORAGE, InMemoryExpressionStorage)
            end

            def build_participant_map ()

                init_service(S_PARTICIPANT_MAP, ParticipantMap)
            end
            
            def build_scheduler ()

                init_service(S_SCHEDULER, SchedulerService)
            end

    end

end