org.squirrelframework.foundation.fsm.StateMachine Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of squirrel-foundation Show documentation
foundation module of squirrel framework which provided event driven infrastructure and a finite state machine implementation.
There is a newer version: 0.3.10
Show newest version
package org.squirrelframework.foundation.fsm;

import org.squirrelframework.foundation.component.Observable;
import org.squirrelframework.foundation.event.SquirrelEvent;
import org.squirrelframework.foundation.exception.TransitionException;
import org.squirrelframework.foundation.fsm.ActionExecutionService.BeforeExecActionListener;
import org.squirrelframework.foundation.util.ReflectUtils;

import java.lang.reflect.Method;
import java.util.Collection;
import java.util.List;

/**
 * Interface for finite state machine.
 * 
 * @author Henry.He
 *
 * @param  type of State Machine
 * @param  type of State
 * @param  type of Event
 * @param  type of Context
 */
public interface StateMachine, S, E, C> extends Visitable, Observable {
    
    /**
     * Fires the specified event
     * @param event the event
     * @param context external context
     */
    void fire(E event, C context);
    
    /**
     * Fires event with context immediately, if current state machine is busy, the next processing event 
     * is this event.
     * @param event the event
     * @param context external context
     */
    void fireImmediate(E event, C context);
    
    /**
     * Test transition result under circumstance
     * @param event test event
     * @param context text context
     * @return test transition result
     */
    S test(E event, C context);
    
    /**
     * Fire event
     * @param event
     */
    void fire(E event);
    
    /**
     * Fire event immediately
     * @param event
     */
    void fireImmediate(E event);
    
    /**
     * Test event
     * @param event
     */
    S test(E event);
    
    /**
     * @param event test event
     * @return true is passed in event is acceptable otherwise return false
     */
    boolean canAccept(E event);
    
    /**
     * Start state machine under external context
     * @param context external context
     */
    void start(C context);
    
    /**
     * Start state machine without context
     */
    void start();
    
    /**
     * Terminate state machine under external context
     * @param context external context
     */
    void terminate(C context);
    
    /**
     * Terminate state machine without context
     */
    void terminate();
    
    /**
     * @return current status of state machine
     */
    StateMachineStatus getStatus();
    
    /**
     * @return type-safe state machine instance
     */
    T getThis();
    
    /**
     * @return current state id of state machine
     */
    S getCurrentState();
    
    /**
     * @return last active state id of state machine
     */
    S getLastState();

    /**
     * @return id of state machine initial state
     */
    S getInitialState();
    
    /**
     * @param parentStateId id of parent state
     * @return last active child state of the parent state
     */
    S getLastActiveChildStateOf(S parentStateId);
    
    /**
     * @param parentStateId
     * @return sub state of parallel state
     */
    List getSubStatesOn(S parentStateId);
    
    /**
     * @return current raw state of state machine
     */
    ImmutableState getCurrentRawState();
    
    /**
     * @return last active raw state of state machine
     */
    ImmutableState getLastRawState();
    
    /**
     * @return initial raw state of state machine
     */
    ImmutableState getInitialRawState();
    
    ImmutableState getRawStateFrom(S stateId);
    
    Collection getAllStates();
    
    Collection> getAllRawStates();
    
    /**
     * Dump current state machine data. This operation can only be done when state machine status is 
     * {@link StateMachineStatus#IDLE}, otherwise null will be returned.
     * 
     * @return dumped state machine data reader
     */
    StateMachineData.Reader dumpSavedData();
    
    /**
     * Load saved data for current state machine. The operation can only be done when state machine 
     * status is {@link StateMachineStatus#INITIALIZED} or {@link StateMachineStatus#TERMINATED}.
     * 
     * @param savedData provided saved data
     * @return true if load saved data success otherwise false
     */
    boolean loadSavedData(StateMachineData.Reader savedData);
    
    /**
     * @return whether state machine is context sensitive
     */
    @Deprecated
    boolean isContextSensitive();
    
    Class typeOfContext();
    
    Class typeOfEvent();
    
    Class typeOfState();
    
    TransitionException getLastException();
    
    String getIdentifier();
    
    String getDescription();
    
    String exportXMLDefinition(boolean beautifyXml);
    
    void addDeclarativeListener(Object listener);
    
    void removeDeclarativeListener(Object listener);
    
    boolean isRemoteMonitorEnabled();
    
    boolean isStarted();
    
    boolean isTerminated();
    
    boolean isError();
    
    interface StateMachineListener, S, E, C> {
        public static final String METHOD_NAME = "stateMachineEvent";
        // leverage bridge method to call the method of actual listener
        public static final Method METHOD = ReflectUtils.getMethod(
                StateMachineListener.class, METHOD_NAME, new Class[]{StateMachineEvent.class});
        
        void stateMachineEvent(StateMachineEvent event);
    }
    interface StateMachineEvent, S, E, C> extends SquirrelEvent {
        T getStateMachine();
    }
    void addStateMachineListener(StateMachineListener listener);
    void removeStateMachineListener(StateMachineListener listener);
    
    interface StartListener, S, E, C> {
        public static final String METHOD_NAME = "started";
        public static final Method METHOD = ReflectUtils.getMethod(
                StartListener.class, METHOD_NAME, new Class[]{StartEvent.class});
        
        void started(StartEvent event);
    }
    interface StartEvent , S, E, C> extends StateMachineEvent {}
    void addStartListener(StartListener listener);
    void removeStartListener(StartListener listener);
    
    interface TerminateListener, S, E, C> {
        public static final String METHOD_NAME = "terminated";
        public static final Method METHOD = ReflectUtils.getMethod(
                TerminateListener.class, METHOD_NAME, new Class[]{TerminateEvent.class});
        
        void terminated(TerminateEvent event);
    }
    interface TerminateEvent , S, E, C> extends StateMachineEvent {}
    void addTerminateListener(TerminateListener listener);
    void removeTerminateListener(TerminateListener listener);
    
    interface StateMachineExceptionListener, S, E, C> {
        public static final String METHOD_NAME = "stateMachineException";
        public static final Method METHOD = ReflectUtils.getMethod(
                StateMachineExceptionListener.class, METHOD_NAME, new Class[]{StateMachineExceptionEvent.class});
        
        void stateMachineException(StateMachineExceptionEvent event);
    }
    interface StateMachineExceptionEvent, S, E, C> extends StateMachineEvent {
        Exception getException();
    }
    void addStateMachineExceptionListener(StateMachineExceptionListener listener);
    void removeStateMachineExceptionListener(StateMachineExceptionListener listener);
    
    interface TransitionEvent, S, E, C> extends StateMachineEvent {
        S getSourceState();
        E getCause();
        C getContext();
    }
    
    interface TransitionBeginListener, S, E, C> {
        public static final String METHOD_NAME = "transitionBegin";
        public static final Method METHOD = ReflectUtils.getMethod(
                TransitionBeginListener.class, METHOD_NAME, new Class[]{TransitionBeginEvent.class});
        
        void transitionBegin(TransitionBeginEvent event);
    }
    interface TransitionBeginEvent, S, E, C> extends TransitionEvent {}
    void addTransitionBeginListener(TransitionBeginListener listener);
    void removeTransitionBeginListener(TransitionBeginListener listener);
    
    interface TransitionCompleteListener, S, E, C> {
        public static final String METHOD_NAME = "transitionComplete";
        public static final Method METHOD = ReflectUtils.getMethod(
                TransitionCompleteListener.class, METHOD_NAME, new Class[]{TransitionCompleteEvent.class});
        
        void transitionComplete(TransitionCompleteEvent event);
    }
    interface TransitionCompleteEvent, S, E, C> extends TransitionEvent {
        S getTargetState();
    }
    void addTransitionCompleteListener(TransitionCompleteListener listener);
    void removeTransitionCompleteListener(TransitionCompleteListener listener);
    
    interface TransitionExceptionListener, S, E, C> {
        public static final String METHOD_NAME = "transitionException";
        public static final Method METHOD = ReflectUtils.getMethod(
                TransitionExceptionListener.class, METHOD_NAME, new Class[]{TransitionExceptionEvent.class});
        
        void transitionException(TransitionExceptionEvent event);
    }
    interface TransitionExceptionEvent, S, E, C> extends TransitionEvent {
        S getTargetState();
        TransitionException getException();
    }
    void addTransitionExceptionListener(TransitionExceptionListener listener);
    void removeTransitionExceptionListener(TransitionExceptionListener listener);
    
    interface TransitionDeclinedListener, S, E, C> {
        public static final String METHOD_NAME = "transitionDeclined";
        public static final Method METHOD = ReflectUtils.getMethod(
                TransitionDeclinedListener.class, METHOD_NAME, new Class[]{TransitionDeclinedEvent.class});
        
        void transitionDeclined(TransitionDeclinedEvent event);
    }
    interface TransitionDeclinedEvent, S, E, C> extends TransitionEvent {}
    void addTransitionDeclinedListener(TransitionDeclinedListener listener);
    void removeTransitionDecleindListener(TransitionDeclinedListener listener);
    
    interface TransitionEndListener, S, E, C> {
        public static final String METHOD_NAME = "transitionEnd";
        public static final Method METHOD = ReflectUtils.getMethod(
                TransitionEndListener.class, METHOD_NAME, new Class[]{TransitionEndEvent.class});
        
        void transitionEnd(TransitionEndEvent event);
    }
    interface TransitionEndEvent, S, E, C> extends TransitionEvent {
        S getTargetState();
    }
    void addTransitionEndListener(TransitionEndListener listener);
    void removeTransitionEndListener(TransitionEndListener listener);
    
    void addExecActionListener(BeforeExecActionListener listener);
    void removeExecActionListener(BeforeExecActionListener listener);
}