oracle.ide.panels
Class FSM

java.lang.Object
  oracle.ide.panels.FSM

public final class FSM

extends java.lang.Object

FSM is a complete implementation of a finite state machine (a.k.a. deterministic finite automaton). The FSM is represented as a Map, so clients will need to provide a properly formatted Map object to initialize the FSM. The recommended way to build this Map is to use the FSMBuilder class, which provides an API abstraction for building the FSM data structure.

An FSM returns an FSMStateInfo every time a client class asks for the next or previous state. The interpretation of the FSMStateInfo object's contents is left to the client class's implementation.

The FSM encapsulates fairly complex behavior. An FSM:

• knows what the start state is.
• knows when it enters a final state.
• knows when it has halted (i.e. has completed the final state).
• maintains the internal state of the machine.
• keeps track of the current step number.
• can be reset to the start state.
• moves to the next FSM state given a transition.
• can step backwards through previous states.
• is able to handle sub-FSMs and can step backward through already halted sub-FSMs (restoring them to a non-halted state).

Note that reaching a final state does not necessarily mean that an FSM has halted. By definition, a halted FSM is one that has completed its final state (and a particular FSM specification may contain more than one final state). A final state is said to be "completed" when its activity (represented by the Step) has finished and Step's Traversable does not specify an exit transition that leaves the final state.

This means that it is possible to transition out of a final state into a non-final state or even another final state. The computational model for deterministic finite automata (DFA) allows for this, so this implementation simply follows suit. From a practical standpoint, most FSM's should need only one final state, and implementors should strive to have only one final state (with no transitions out of it) unless there is a specific feature that cannot be implemented otherwise.

The design of this class and its methods are based on the concepts behind the UML State Machine diagram, the UML Activity diagram, and the computational model of a deterministic finite automaton.

See Also:

FSMBuilder, Step, Traversable

Field Summary

static java.lang.String	ANY_TRANS Special FSM state name representing all transitions that are not explicitly handled.
static java.lang.String	FSMState_OBJ State property for the state object.
static java.lang.String	IS_FINAL_STATE State property that indicates that the state is a final state.
static java.lang.String	START_STATE Special FSM state name for the FSM's starting state.
static java.lang.String	TRANSITIONS State property for the Map that tells how transitions lead out of a state to other states in the FSM.

Constructor Summary

FSM()
Initializes this instance to have a null FSM specification.

FSM(java.util.Map fsmSpec)
This constructor takes an FSM specification in the form of a Map instance and initializes this FSM instance to use it.

Method Summary

int	getStateIndex() Returns the state number of the current top-level state.
int	getStepNumber() Returns how many steps into the FSM that execution has progressed through repeated invocations of nextState(Object).
int	getTotalStepCount() Returns the total number of steps in this FSM Note: This does not take into account steps in any sub-FSM
boolean	inFinalState() Tests if the FSM is in a final state.
boolean	isFinishPageAdded() Returns true if a finish page has been added, false otherwise
boolean	isHalted() Tests if the FSM has halted.
boolean	isStarting()
boolean	isWelcomePageAdded() Returns true if a welcome page has been added, false otherwise
FSMStateInfo	nextState(java.lang.Object transition) Updates the internal state of the FSM and returns the next FSMStateInfo object.
FSMStateInfo	previousState() Rolls back the FSM to its previous state and returns the corresponding FSMStateInfo object.
void	reset() Resets the FSM state to its start state.
void	setFinishPageAdded(boolean pageAdded) Sets whether a finish page has been added
void	setFSM(java.util.Map fsmSpec) Sets the FSM specification that is to be used by this FSM instance.
void	setWelcomePageAdded(boolean pageAdded) Sets whether or not a welcome page has been added
static void	validateFSM(java.util.Map fsm) This method validates the given FSM specification, verifying that it has an appropriate structure.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

START_STATE

public static final java.lang.String START_STATE

Special FSM state name for the FSM's starting state.

See Also:

Constant Field Values

IS_FINAL_STATE

public static final java.lang.String IS_FINAL_STATE

State property that indicates that the state is a final state. The presence of this key within the state definition regardless of its associated value indicates that the state is a final state. An FSM may contain more than one final state, and it is possible to transition out of a final state to a non-final state.

See Also:

Constant Field Values

FSMState_OBJ

public static final java.lang.String FSMState_OBJ

State property for the state object. Every FSM state must have an associated state object. The value of this object must be a Step instance.

See Also:

Constant Field Values

TRANSITIONS

public static final java.lang.String TRANSITIONS

State property for the Map that tells how transitions lead out of a state to other states in the FSM.

See Also:

Constant Field Values

ANY_TRANS

public static final java.lang.String ANY_TRANS

Special FSM state name representing all transitions that are not explicitly handled. This is useful when a portion of the FSM has a series of actions that just continue one after another regardless of the specific transition that is returned.

See Also:

Constant Field Values

Constructor Detail

FSM

public FSM()

Initializes this instance to have a null FSM specification.

FSM

public FSM(java.util.Map fsmSpec)
    throws FSMInvalidException

This constructor takes an FSM specification in the form of a Map instance and initializes this FSM instance to use it. The FSM specification is validated before it is set (see the comments for validateFSM(Map) for details). If any errors are found, then an FSMException is thrown. At that point the FSM instance is invalid and cannot be used until setFSM(Map) is called with a valid FSM specification.

Method Detail

setFSM

public void setFSM(java.util.Map fsmSpec)
            throws FSMInvalidException

Sets the FSM specification that is to be used by this FSM instance. If the FSM instance already has an FSM specification, then an FSMException is thrown. Otherwise the FSM specification is validated before it is set.

Throws:

FSMInvalidException

reset

public void reset()

Resets the FSM state to its start state. The first call to nextState(Object) after a call to reset() returns the FSM's starting state.

getStateIndex

public int getStateIndex()

Returns the state number of the current top-level state. This is like the step number, except that only top-level states are counted (i.e. no states from sub-FSMs are counted).

getStepNumber

public int getStepNumber()

Returns how many steps into the FSM that execution has progressed through repeated invocations of nextState(Object).

Returns:

The number of the step that is currently executing in the FSM. By definition, 1 is the start state. A return value of 0 means that the FSM is about to enter the start state (i.e. the next call to nextState(Object) will return the start state).

isStarting

public boolean isStarting()

inFinalState

public boolean inFinalState()

Tests if the FSM is in a final state. An FSM that is in its final state is about to halt. This information can be useful to UI that needs to be updated when the FSM reaches its last step.

By definition, an FSM is in its final state if its current state is a final state and the sub-FSM, if any, is also in its final state.

Returns:

true if the FSM is in a final state; false otherwise.

isHalted

public boolean isHalted()

Tests if the FSM has halted. A halted FSM is one that has entered a final state and successfully completed it without transitioning to a non-final state.

Returns:

true if the FSM has halted; false otherwise.

nextState

public FSMStateInfo nextState(java.lang.Object transition)
                       throws FSMException

Updates the internal state of the FSM and returns the next FSMStateInfo object. If the FSM is newly created or has just had its reset() method called, then then the starting FSMStateInfo is returned no matter what the transition is (i.e. a sub-FSM is ignored). If the FSM has reached a final state and there are no transitions out of the final state, then the FSM halts, and this method returns null.

If the given transition does not lead to a defined state, then nextState(Object) throws an FSMTransitionException. In this case, the FSM's state does not change. Any subsequent call to nextState(Object) with a valid transition will cause the FSM object to resume normal operation. However, if the FSM is already in a final state and there are no transitions out of that state, then this method should throw FSMTransitionException for all transitions.

A null transition, though unusual, should be accepted as a valid, distinct transition.

If the FSM has already halted, then this method will always return null; no exception is thrown. The implementation of nextState(Object) caches the FSMStateInfo object that is returned so that the same FSMStateInfo instance is returned if it is ever requested again. This is important for handling calls to the previousState() method properly, which may be called to retreat through the steps of the FSM. Classes that operate an FSM can therefore rely on the FSM to return the same FSMStateInfo instances as before, if the user visits the same state at the same step by following the same transition.

Parameters:

transition - The transition that should be followed to reach the next state.

Returns:

the state machine's next state given a transition.

Throws:

Throws - FSMTransitionException if the given transition does not lead to a defined state.

Throws - FSMException if an internal error occurs that cannot other wise be a FSMTransitionException.

FSMException

previousState

public FSMStateInfo previousState()
                           throws FSMException

Rolls back the FSM to its previous state and returns the corresponding FSMStateInfo object. When returning a previous state, the FSM should return the same FSMStateInfo instance that was initially returned by nextState(Object).

If the FSM is in the start state, then null is returned, and no exception is thrown. If calling previousState() causes the FSM to move from a final state to a non-final state, the return value of inFinalState() should reflect this.

Returns:

The previous FSMStateInfo that was returned by this FSM. The state of the FSM is also rolled back to that state.

Throws:

FSMException

See Also:

nextState()

validateFSM

public static final void validateFSM(java.util.Map fsm)
                              throws FSMInvalidException

This method validates the given FSM specification, verifying that it has an appropriate structure. If the FSM is invalid, an FSMException is thrown with an explanatory message. If this method returns without throwing an FSMException, the FSM is valid.

By definition, an FSM specification is said to be valid if all of the following requirements are met:

• The specification is not null.
• It contains a start state.
• It contains one or more final states.
• Each value in the specification Map is itself an instance of Map. Each of these maps are referred to as a "state node" within the FSM specification.
• Each state node contains the key FSM.FSMState_OBJ. The value associated with this key must be a non-null instance of Step.
• Each state node contains the key FSM.TRANSITIONS. The value associated with this key must be a non-null instance of Map. This value is referred to as a "transition map". The keys of a transition map are transitions names, and the values are state names.
• Each value in the transition map must be a state name that is defined in the FSM specification.
• Non-final states must have at least one transition. Final states are allowed to have no transitions (i.e. an empty transition map).

Notably missing from the definition of a valid FSM specification are the following, which may be implemented in the future:

• Verifying that a path from the start state to a final state exists.

Throws:

FSMInvalidException

setWelcomePageAdded

public void setWelcomePageAdded(boolean pageAdded)

Sets whether or not a welcome page has been added

isWelcomePageAdded

public boolean isWelcomePageAdded()

Returns true if a welcome page has been added, false otherwise

setFinishPageAdded

public void setFinishPageAdded(boolean pageAdded)

Sets whether a finish page has been added

isFinishPageAdded

public boolean isFinishPageAdded()

Returns true if a finish page has been added, false otherwise

getTotalStepCount

public int getTotalStepCount()

Returns the total number of steps in this FSM Note: This does not take into account steps in any sub-FSM