StateEngine.java revision 608:7e06bf1dcb09 
1/*
2 * Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package com.sun.corba.se.spi.orbutil.fsm;
27
28/**
29 * A StateEngine defines the state transition function for a
30 * finite state machine (FSM). A FSM always has a current state.
31 * In response to an Input, the FSM performs an Action and
32 * makes a transition to a new state.  Note that any object can
33 * be used as an input if it supports the Input interface.
34 * For example, a protocol message may be an input.  The FSM
35 * uses only the result of calling getLabel on the Input to
36 * drive the transition.
37 * <p>
38 * The function can be non-deterministic
39 * in that the same input may cause transitions to different new
40 * states from the current state.  In this case, the action that
41 * is executed for the transition must set the correct new state.
42 *
43 * @author Ken Cavanaugh
44 */
45public interface StateEngine
46{
47        /** Add a new transition (old,in,guard,act,new) to the state engine.
48        * Multiple calls to add with the same old and in are permitted,
49        * in which case only a transition in which the guard evaluates to
50        * true will be taken.  If no such transition is enabled, a default
51        * will be taken.  If more than one transition is enabled, one will
52        * be chosen arbitrarily.
53        * This method can only be called before done().  An attempt to
54        * call it after done() results in an IllegalStateException.
55        */
56        public StateEngine add( State oldState, Input input, Guard guard,
57            Action action, State newState ) throws IllegalStateException ;
58
59        /** Add a transition with a guard that always evaluates to true.
60        */
61        public StateEngine add( State oldState, Input input,
62            Action action, State newState ) throws IllegalStateException ;
63
64        /** Set the default transition and action for a state.
65        * This transition will be used if no more specific transition was
66        * defined for the actual input.  Repeated calls to this method
67        * simply change the default.
68        * This method can only be called before done().  An attempt to
69        * call it after done() results in an IllegalStateException.
70        */
71        public StateEngine setDefault( State oldState, Action action, State newState )
72                throws IllegalStateException ;
73
74        /** Equivalent to setDefault( oldState, act, newState ) where act is an
75         * action that does nothing.
76         */
77        public StateEngine setDefault( State oldState, State newState )
78                throws IllegalStateException ;
79
80        /** Euaivalent to setDefault( oldState, oldState )
81         */
82        public StateEngine setDefault( State oldState )
83                throws IllegalStateException ;
84
85        /** Set the default action used in this state engine.  This is the
86        * action that is called whenever there is no applicable transition.
87        * Normally this would simply flag an error.  This method can only
88        * be called before done().  An attempt to
89        * call it after done() results in an IllegalStateException.
90        */
91        public void setDefaultAction( Action act ) throws IllegalStateException ;
92
93        /** Called after all transitions have been added to the state engine.
94        * This provides an opportunity for the implementation to optimize
95        * its representation before the state engine is used.  This method
96        * may only be called once.  An attempt to call it more than once
97        * results in an IllegalStateException.
98        */
99        public void done() throws IllegalStateException ;
100
101        /** Create an instance of a FSM that uses this state engine.
102        * The initial state of the FSM will be the stateState specified
103        * here.  This method can only be called after done().  An attempt
104        * to call it before done results in an IllegalStateException.
105        */
106        public FSM makeFSM( State startState ) throws IllegalStateException ;
107}
108
109// end of StateEngine.java
110