FlowController

/*
Copyright 2005 by the authors of asapframework

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

import org.asapframework.events.Dispatcher;
import data.tree.*;
import org.asapframework.util.debug.Console;

/**
FlowController runs through a series of instructions - represented by a Tree of {@link FlowTreeNode FlowTreeNodes}.
@author Arthur Clemens
@version 24 July 2005
@todo Document evaluation
*/

class data.tree.FlowController extends Dispatcher {
    
    private var mTree:Tree; /**< Tree object that holds the data. */
    private var mEnumerator:TreeEnumerator;
    private var mActionObject:Object; /**< The object to perform {@link FlowTreeNode#method methods}. */

    /**
    Creates a FlowController, with the FlowController's Tree. This Tree uses nodes of type {@link FlowTreeNode}.
    @param inActionObject : the object to perform methods, see {@link #setActionObject}
    @example
    In a FlowController subclass (when using {@link TextFile2Tree}):
    <code>
    function MyFlowController (inActionObject:Object, inDataUrl:String)
    {
        super(inActionObject);
        new TextFile2Tree(inDataUrl, this, tree);
    }

    private function onTextFile2TreeFinished (inEvent:TextFile2TreeEvent) : Void
    {
        run();
    }
    </code>
    */
    function FlowController (inActionObject:Object)
    {
        super();
        if (inActionObject != undefined) {
            mActionObject = inActionObject;
        }
        mTree = new Tree("FlowController tree");
        var rootNode:FlowTreeNode = new FlowTreeNode(Tree.ROOT_NODE_NAME);
        mTree.setRootNode(rootNode);
    }
    
    /**
    The Tree object used by FlowController.
    */
    public function get tree () : Tree
    {
        return mTree;
    }

    /**
    Stores the object that performs methods that are passed with the {@link FlowTreeNode#method} instruction attribute.
    @param inActionObject : the object to perform {@link FlowTreeNode#method methods}
    */
    public function setActionObject (inActionObject:Object) : Void
    {
        mActionObject = inActionObject;
    }

    /**
    First creates an enumerator if not defined before.
    Calls the next instruction of the enumerator. The type of instruction is defined by the attribute {@link FlowTreeNode#type}. The value of the instruction type determines the next steps:
    <ul>
        <li>In case of an <b>action</b> instruction
            <ul>
                <li>If an action object has been set and a {@link FlowTreeNode#method} is passed in the instruction, this method is called on the action object; then the next {@code run} is called.</li>
                <li>A {@link FlowControllerEvent#ACTION} message is sent and the next {@code run} is called.</li>
            </ul>
        </li>
        <li>In case of a <b>condition</b>
            <ul>
                <li>If an action object has been set and a {@link FlowTreeNode#method} is passed in the instruction, this method is called on the action object.</li>
                <li>A {@link FlowControllerEvent#CONDITION} message is sent and further running is deferred. The receiving object is responsible for interpreting the condition. To continue the flow, the object should call {@link #runResult} or {@link #run}.</li>
            </ul>
        </li>
        <li>In case of an <b>await:</b>
            <ul>
                <li>If an action object has been set and a {@code method} is passed in the instruction, this method is called on the action object (no message is sent).</li>
                <li>A {@link FlowControllerEvent#AWAIT} message is sent.</li>
            </ul>
        </li>
        <li>In case of an <b>exit</b> instruction, an {@link FlowControllerEvent#EXIT} message is sent.</li>
        <li>In all other cases (when no type is given) the next {@code run} is called.</li>
    </ul>
    @sends FlowControllerEvent#CONDITION When a condition is found.
    @sends FlowControllerEvent#ACTION When an action is.
    @sends FlowControllerEvent#AWAIT When an await is found.
    @sends FlowControllerEvent#EXIT When an exit instruction is found.
    @implementationNote Events are sent by the invoked method {@link #update}.
    */
    public function run () : Void
    {
        if (mEnumerator == undefined) {
            createEnumerator();
        }
        var node:FlowTreeNode = FlowTreeNode(mEnumerator.getNextObject());
        if (node == null) {
            return;
        }
        update();
    }

    /**
    Calls the next instruction with the action that corresponds to the key inResult.
    @example
    With the following instruction:
    <code>
    question1, text="Which square is the red one?", type=condition, red=question2, green=question3
    </code>
    when {@code runResult} is called with the result "green", the next instruction {@code question3} is called.

    In the FlowController owner:
    <code>
    private function onEventButtonPress (inEvent:EventButtonEvent) : Void
    {
        var answer:String = inEvent.buttonName;
        mFlowController.runResult(answer);
    }
    </code>
    */
    public function runResult (inResult:String) : Void
    {
        var instructionName:String;
        instructionName = FlowTreeNode(mEnumerator.getCurrentObject()).getValueForKey(inResult);
        var instruction:FlowTreeNode = FlowTreeNode(mTree.getNode(instructionName));
        if (instruction == null) {
            Console.WARN("FlowManager runResult: no action found for result: '" + inResult + "'.");
        } else {
            mEnumerator.setCurrentObject(instruction);
            update();
        }
    }
    
    public function evaluate (inCondition:String) : Void
    {
        var node:FlowTreeNode = FlowTreeNode(mEnumerator.getCurrentObject());
        // get evaluation items
        var conditions:Array = node.conditions;
        removeFromArray(conditions, inCondition);
        if (conditions.length == 0) {
            run();
        }
    }

    /**
    @exclude
    */
    public function toString () : String
    {
        return "(FlowController)";
    }

    // PRIVATE METHODS

    private function removeFromArray( inList:Array, inValue ) : Boolean {

        for (var i:Number=0; i<inList.length; ++i) {
            if (inList[i] == inValue) {
                inList.splice(i, 1);
                return true;
                break;
            }
        }
        return false;
    }

    /**
    Calls method inActionMethod from object inActionObject and passes inNode as argument.
    */
    private function callActionMethod (inActionObject:Object,
                                      inActionMethod:String,
                                      inNode:FlowTreeNode) : Void
    {
        var method:Function = inActionObject[inActionMethod];
        method.call(inActionObject, inNode);
    }
    
    /**
    @see #run
    @sends FlowControllerEvent#CONDITION When a condition is found.
    @sends FlowControllerEvent#ACTION When an action is found.
    @sends FlowControllerEvent#AWAIT When an await instruction is found.
    @sends FlowControllerEvent#EXIT When an exit instruction is found.
    */
    private function update () : Void
    {
        var node:FlowTreeNode = FlowTreeNode(mEnumerator.getCurrentObject());
        if (node == null) {
            return;
        }
        switch (node.type) {
            case "condition":
                if (mActionObject != undefined && node.method != undefined) {
                    callActionMethod(mActionObject, node.method, node);
                }
                dispatchEvent(new FlowControllerEvent(FlowControllerEvent.CONDITION, node));
                break;
            case "action":
                if (mActionObject != undefined && node.method != undefined) {
                    callActionMethod(mActionObject, node.method, node);
                }
                dispatchEvent(new FlowControllerEvent(FlowControllerEvent.ACTION, node));
                run();
                break;
            case "await":
                if (mActionObject != undefined && node.method != undefined) {
                    callActionMethod(mActionObject, node.method, node);
                }
                dispatchEvent(new FlowControllerEvent(FlowControllerEvent.AWAIT, node));
                break;
            case "evaluation":
                dispatchEvent(new FlowControllerEvent(FlowControllerEvent.EVALUATION, node));
                break;
            case "exit":
                dispatchEvent(new FlowControllerEvent(FlowControllerEvent.EXIT, node));
                break;
            default:
                run();
        }
    }
    
    /**
    Creates the Tree enumerator.
    */
    private function createEnumerator () : Void
    {
        mEnumerator = new TreeEnumerator(mTree.root);
    }
}