zkoss/zk

/**
 * 
 */
package org.zkoss.fsm;

import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;

/**
 * A context for a State in a StateMachine, holding returning and transition
 * information.
 * @since 6.0.0
 * @author simonpai
 */
public class StateCtx<E, C, IN> {
    
    protected StateMachine<E, C, IN> _machine;
    
    // local properties //
    protected boolean _returnAll = false;
    protected final Set<C> _returners = new HashSet<C>();
    protected final Set<IN> _minorReturners = new HashSet<IN>();
    protected final Map<C, E> _transitions = new HashMap<C, E>();
    protected final Map<C, TransitionListener<IN, C>> _transitionListeners = 
        new HashMap<C, TransitionListener<IN, C>>();
    protected final Map<IN, E> _minorTransitions = new HashMap<IN, E>();
    protected final Map<IN, TransitionListener<IN, C>> _minorTransitionListeners = 
        new HashMap<IN, TransitionListener<IN, C>>();
    
    /**
     * Creates a new state context
     */
    public StateCtx() {
        init();
    }
    
    /**
     * Sets the owner state machine.
     */
    protected StateCtx<E, C, IN> setMaster(StateMachine<E, C, IN> master) {
        _machine = master;
        return this;
    }
    
    
    
    // definition //
    /**
     * Initialization method called at the constructor
     */
    protected void init(){}
    
    // returning //
    /**
     * Add an input class for returning to this state
     * @return this state
     */
    public StateCtx<E, C, IN> addReturningClasses(C ... inputClasses) {
        for(C c : inputClasses) _returners.add(c);
        return this;
    }
    
    /**
     * Add multiple input classes for returning to this state
     * @return this state
     */
    public StateCtx<E, C, IN> addReturningClasses(Collection<C> collection) {
        _returners.addAll(collection);
        return this;
    }
    
    /**
     * Add input characters for returning to this state
     * @return this state
     */
    public StateCtx<E, C, IN> addReturningInputs(IN ... inputs) {
        for(IN i : inputs) _minorReturners.add(i);
        return this;
    }
    
    /**
     * Add input characters for returning to this state
     * @return this state
     */
    public StateCtx<E, C, IN> addReturningInputs(Collection<IN> collection) {
        _minorReturners.addAll(collection);
        return this;
    }
    
    /**
     * Set whether returns to this state upon meeting unspecified characters 
     * @return this state
     */
    public StateCtx<E, C, IN> setReturningAll(boolean returnAll) {
        _returnAll = returnAll;
        return this;
    }
    
    // transition //
    /**
     * Add a transition rule
     * @return this state
     */
    public StateCtx<E, C, IN> addTransition(C inputClass, E destination) {
        return addTransition(inputClass, destination, null);
    }
    
    /**
     * Add a transition rule with a callback
     * @return this state
     */
    public StateCtx<E, C, IN> addTransition(C inputClass, E destination, 
            TransitionListener<IN, C> callback) {
        _transitions.put(inputClass, destination);
        if(callback == null)
            _transitionListeners.remove(inputClass);
        else
            _transitionListeners.put(inputClass, callback);
        return this;
    }
    
    /**
     * Add multiple transitions
     * @return this state
     */
    public StateCtx<E, C, IN> addTransitions(E destination, C ... inputClasses) {
        return addTransitions(destination, null, inputClasses);
    }
    
    /**
     * Add multiple transitions with a callback
     * @return this state
     */
    public StateCtx<E, C, IN> addTransitions(E destination, 
            TransitionListener<IN, C> callback, C ... inputClasses) {
        for(C c : inputClasses)
            addTransition(c, destination, callback);
        return this;
    }
    
    // route //
    /**
     * Add a transition. Same as {@link #addTransition(Object, Object)}, 
     * and only differs in return value.
     * @return destination state.
     */
    public StateCtx<E, C, IN> addRoute(C inputClass, E destination) {
        return addRoute(inputClass, destination, null);
    }
    
    /**
     * Add a transition with callback. 
     * Same as {@link #addTransition(Object, Object, TransitionListener)}, 
     * and only differs in return value.
     * @return destination state.
     */
    public StateCtx<E, C, IN> addRoute(C inputClass, E destination, 
            TransitionListener<IN, C> callback) {
        addTransition(inputClass, destination, callback);
        return _machine.getState(destination);
    }
    
    /**
     * Add multiple transitions. 
     * Same as {@link #addTransitions(Object, Object...)}, 
     * and only differs in return value.
     * @return destination state.
     */
    public StateCtx<E, C, IN> addRoutes(E destination, C ... inputClasses) {
        return addRoutes(destination, null, inputClasses);
    }
    
    /**
     * Add multiple transitions with a callback. 
     * Same as {@link #addTransitions(Object, TransitionListener, Object...)}, 
     * and only differs in return value.
     * @return destination state.
     */
    public StateCtx<E, C, IN> addRoutes(E destination, 
            TransitionListener<IN, C> callback, C ... inputClasses) {
        addTransitions(destination, callback, inputClasses);
        return _machine.getState(destination);
    }
    
    // minor transition //
    /**
     * Add a transition for a character.
     * @return this state
     */
    public StateCtx<E, C, IN> addMinorTransition(IN input, E destination) {
        return addMinorTransition(input, destination, null);
    }
    
    /**
     * Add a transition for a character with a callback
     * @return this state
     */
    public StateCtx<E, C, IN> addMinorTransition(IN input, E destination, 
            TransitionListener<IN, C> callback) {
        _minorTransitions.put(input, destination);
        if(callback == null)
            _minorTransitionListeners.remove(input);
        else
            _minorTransitionListeners.put(input, callback);
        return this;
    }
    
    /**
     * Add multiple transitions for characters
     * @return this state
     */
    public StateCtx<E, C, IN> addMinorTransitions(E destination, IN ... inputs) {
        return addMinorTransitions(destination, null, inputs);
    }
    
    /**
     * Add multiple transitions for characters with a callback
     * @return this state
     */
    public StateCtx<E, C, IN> addMinorTransitions(E destination, 
            TransitionListener<IN, C> callback, IN ... inputs) {
        for(IN i : inputs)
            addMinorTransition(i, destination, callback);
        return this;
    }
    
    // minor route //
    /**
     * Add a transition for a character. 
     * Same as {@link #addMinorRoute(Object, Object)}, 
     * and only differs in return value.
     * @return destination state
     */
    public StateCtx<E, C, IN> addMinorRoute(IN input, E destination) {
        return addMinorRoute(input, destination, null);
    }
    
    /**
     * Add a transition for a character with callback. 
     * Same as {@link #addMinorTransition(Object, Object, TransitionListener)}, 
     * and only differs in return value.
     * @return destination state
     */
    public StateCtx<E, C, IN> addMinorRoute(IN input, E destination, 
            TransitionListener<IN, C> callback) {
        addMinorTransition(input, destination, callback);
        return _machine.getState(destination);
    }
    
    /**
     * Add multiple transitions for characters. 
     * Same as {@link #addMinorTransitions(Object, Object...)}, 
     * and only differs in return value.
     * @return destination state
     */
    public StateCtx<E, C, IN> addMinorRoutes(E destination, IN ... inputs) {
        return addMinorRoutes(destination, null, inputs);
    }
    
    /**
     * Add multiple transitions for characters with a callback. 
     * Same as {@link #addMinorTransitions(Object, TransitionListener, Object...)}, 
     * and only differs in return value.
     * @return destination state
     */
    public StateCtx<E, C, IN> addMinorRoutes(E destination, 
            TransitionListener<IN, C> callback, IN ... inputs) {
        addMinorTransitions(destination, callback, inputs);
        return _machine.getState(destination);
    }
    
    
    
    // query //
    /**
     * Returns true if this state returns to itself by default, unless meeting
     * specified characters or classes.
     */
    public boolean isReturningAll(){
        return _returnAll;
    }
    
    /**
     * Returns true if this state returns to itself upon meeting the character
     * or the class.
     */
    public boolean isReturning(IN input, C inputClass) {
        return _returnAll || _returners.contains(inputClass) || 
            _minorReturners.contains(input);
    }
    
    /**
     * Returns true if the machine is leaving this state upon meeting the 
     * character or the class.
     */
    public boolean isLeaving(IN input, C inputClass) {
        return _transitions.containsKey(inputClass) || 
            _minorTransitions.containsKey(input);
    }
    
    /**
     * Returns the destination state upon meeting the character or the class.
     */
    public E getDestination(IN input, C inputClass) {
        E result = _minorTransitions.get(input);
        return (result != null)? result : _transitions.get(inputClass);
    }
    
    
    
    // event handler //
    /**
     * This method is called when the machine enters this state
     */
    protected void onLand(IN input, C inputClass, E origin) {}
    
    /**
     * This method is called when the machine returns to the same state
     */
    protected void onReturn(IN input, C inputClass) {}
    
    /**
     * This method is called when the machine rejects the input on this state
     */
    protected void onReject(IN input, C inputClass) {}
    
    /**
     * This method is called when the machine leaves this state
     */
    protected void onLeave(IN input, C inputClass, E destination) {}
    
    /**
     * This method is called when the machine stops on this state
     */
    protected void onStop(boolean endOfInput) {}
    
    public interface TransitionListener<IN, C> {
        public void onTransit(IN input, C inputClass);
    }
    
    
    
    // default operation //
    /*package*/ void doTransit(IN input, C inputClass) {
        TransitionListener<IN, C> c = _transitionListeners.get(inputClass);
        if(c != null) c.onTransit(input, inputClass);
        c = _minorTransitionListeners.get(input);
        if(c != null) c.onTransit(input, inputClass);
    }
}