Java example source code file (StateEngine.java)

This example Java source code file (StateEngine.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

action, fsm, guard, illegalstateexception, input, state, stateengine

The StateEngine.java Java example source code

/*
 * Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.corba.se.spi.orbutil.fsm;

/**
 * A StateEngine defines the state transition function for a
 * finite state machine (FSM). A FSM always has a current state.
 * In response to an Input, the FSM performs an Action and
 * makes a transition to a new state.  Note that any object can
 * be used as an input if it supports the Input interface.
 * For example, a protocol message may be an input.  The FSM
 * uses only the result of calling getLabel on the Input to
 * drive the transition.
 * <p>
 * The function can be non-deterministic
 * in that the same input may cause transitions to different new
 * states from the current state.  In this case, the action that
 * is executed for the transition must set the correct new state.
 *
 * @author Ken Cavanaugh
 */
public interface StateEngine
{
        /** Add a new transition (old,in,guard,act,new) to the state engine.
        * Multiple calls to add with the same old and in are permitted,
        * in which case only a transition in which the guard evaluates to
        * true will be taken.  If no such transition is enabled, a default
        * will be taken.  If more than one transition is enabled, one will
        * be chosen arbitrarily.
        * This method can only be called before done().  An attempt to
        * call it after done() results in an IllegalStateException.
        */
        public StateEngine add( State oldState, Input input, Guard guard,
            Action action, State newState ) throws IllegalStateException ;

        /** Add a transition with a guard that always evaluates to true.
        */
        public StateEngine add( State oldState, Input input,
            Action action, State newState ) throws IllegalStateException ;

        /** Set the default transition and action for a state.
        * This transition will be used if no more specific transition was
        * defined for the actual input.  Repeated calls to this method
        * simply change the default.
        * This method can only be called before done().  An attempt to
        * call it after done() results in an IllegalStateException.
        */
        public StateEngine setDefault( State oldState, Action action, State newState )
                throws IllegalStateException ;

        /** Equivalent to setDefault( oldState, act, newState ) where act is an
         * action that does nothing.
         */
        public StateEngine setDefault( State oldState, State newState )
                throws IllegalStateException ;

        /** Euaivalent to setDefault( oldState, oldState )
         */
        public StateEngine setDefault( State oldState )
                throws IllegalStateException ;

        /** Set the default action used in this state engine.  This is the
        * action that is called whenever there is no applicable transition.
        * Normally this would simply flag an error.  This method can only
        * be called before done().  An attempt to
        * call it after done() results in an IllegalStateException.
        */
        public void setDefaultAction( Action act ) throws IllegalStateException ;

        /** Called after all transitions have been added to the state engine.
        * This provides an opportunity for the implementation to optimize
        * its representation before the state engine is used.  This method
        * may only be called once.  An attempt to call it more than once
        * results in an IllegalStateException.
        */
        public void done() throws IllegalStateException ;

        /** Create an instance of a FSM that uses this state engine.
        * The initial state of the FSM will be the stateState specified
        * here.  This method can only be called after done().  An attempt
        * to call it before done results in an IllegalStateException.
        */
        public FSM makeFSM( State startState ) throws IllegalStateException ;
}

// end of StateEngine.java