com.ptc.windchill.upgrade.util.fsm
Class StateMachine

java.lang.Object
  com.ptc.windchill.upgrade.util.fsm.StateMachine

Direct Known Subclasses:

ApplicationStateMachine, CompareSchemaOnlyStateMachine, UpgradeToolStateMachine

public class StateMachine

extends Object

A StateMachine instance manages State information, events, and transitions according to a StateMachineDefinition.

StateMachines can run in synchronous or asynchronous mode:

• In synchronous mode, all event dispatch processing occurs on the invoking client's thread. This includes state transitions(and other actions) and listener method calls.
• In asynchronous mode, the state machine is given its own daemon thread. Event dispatches will return immediately to the client, and the state machine's thread will handle transitions(and other actions) and listener method calls. It is important for listeners to not block the state machine's thread with length activities. Listeners to asynchronous state machines should delegate any time consuming tasks to other threads.

Regardless of which mode the state machine runs in, clients should invoke start(...) to transition it from the single start state into another state.

See Also:

StateMachineDefinition, StateDefinition, State

Nested Class Summary

private class	StateMachine.CheckEventTypeEnabledStates
private class	StateMachine.HandleEvent
private class	StateMachine.Instruction
private class	StateMachine.InstructionHandlingThread

Field Summary

private State	currentState_
private StateMachineDefinition	definition_
private HashMap	eventEnabledStates_
private FixedLengthQueue	instructionQueue_
private StateMachineListener	listener_
private static int	RUNNING
private int	runningStatus_
private static int	STOPPED
private boolean	synchronous_

Constructor Summary

StateMachine(StateMachineDefinition definition, boolean asynchronous)
Create an instance based on the the StateMachineDefinition.

Method Summary

void	addStateMachineListener(StateMachineListener new_listener) Add a listener.
void	checkEventTypeEnabledStates() Instruct the state machine to reevaluate the enabled states of all known event types in the state machine.
void	dispatchEvent(EventType event_type) Create and dispatch an event of the specified type with no event object.
void	dispatchEvent(EventType event_type, Object event_object) Create and dispatch an event of the specified type and an acommpanying event object.
private void	doCheckEventTypeEnabledStates()
private void	enqueue(StateMachine.Instruction instruction)
(package private) void	fireEventEnabledStateEvaluationError(Throwable throwable)
(package private) void	fireEventHandlingError(Event event, Throwable throwable)
(package private) void	fireEventTypeEnabledStateChanged(EventType event_type, boolean is_enabled)
(package private) void	firePostStateActivate(State state)
(package private) void	firePostStateDeactivate(State state)
(package private) void	firePreStateActivate(State state)
(package private) void	firePreStateDeactivate(State state)
(package private) void	fireStateMachineStopped()
boolean	isEventTypeEnabled(EventType event_type) Determine if events of the specified type will cause any action given the state machine's current state.
(package private) boolean	isRunning() A package internal method: whether or not the state machine is running or has stopped
void	join() If StateMachine is asynchronous, block until there are no pending events.
private void	logListenerError(String listener_method_name, Throwable t)
private void	onStop()
void	removeStateMachineListener(StateMachineListener listener_to_remove) Remove a listener.
(package private) void	setState(State state, Event event)
void	start() Start the state machine with no event argument.
void	start(Object event_argument) Start the state machine with an event argument.
(package private) void	transitionToState(StateDefinition state_definition, Event event)

Methods inherited from class java.lang.Object

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

Field Detail

RUNNING

private static final int RUNNING

See Also:

Constant Field Values

STOPPED

private static final int STOPPED

See Also:

Constant Field Values

definition_

private StateMachineDefinition definition_

synchronous_

private boolean synchronous_

currentState_

private State currentState_

instructionQueue_

private FixedLengthQueue instructionQueue_

listener_

private StateMachineListener listener_

eventEnabledStates_

private HashMap eventEnabledStates_

runningStatus_

private int runningStatus_

Constructor Detail

StateMachine

public StateMachine(StateMachineDefinition definition,
                    boolean asynchronous)

Create an instance based on the the StateMachineDefinition. You must specify whether the instance will be synchronous or asynchronous.

While you do not need to subclass this type, you may want to do so in order to maintain application-specific data.

Method Detail

addStateMachineListener

public final void addStateMachineListener(StateMachineListener new_listener)

Add a listener.

removeStateMachineListener

public final void removeStateMachineListener(StateMachineListener listener_to_remove)

Remove a listener.

start

public final void start()

Start the state machine with no event argument. Note: this is equivalent to dispatchEvent(EventType.START)

start

public final void start(Object event_argument)

Start the state machine with an event argument.

Note: this is equivalent to dispatchEvent(EventType.START, event_argument)

dispatchEvent

public final void dispatchEvent(EventType event_type)

Create and dispatch an event of the specified type with no event object.

Returns immediately for asynchronous state machine instances

dispatchEvent

public final void dispatchEvent(EventType event_type,
                                Object event_object)

Create and dispatch an event of the specified type and an acommpanying event object.

Parameters:

event_object - a value of any type, may be null

Returns immediately for asynchronous state machine instances

isEventTypeEnabled

public final boolean isEventTypeEnabled(EventType event_type)

Determine if events of the specified type will cause any action given the state machine's current state.

Returns:

false if the event will have no effect

checkEventTypeEnabledStates

public final void checkEventTypeEnabledStates()

Instruct the state machine to reevaluate the enabled states of all known event types in the state machine.

This is done automatically after handling each event. But client's may invoke this method whenever they do something that may change the result of Conditions that control the applicability of actions upon events.

This call will execute synchronously in the caller's thread. (THIS MAY CHANGE)

See Also:

isEventTypeEnabled(EventType)

enqueue

private void enqueue(StateMachine.Instruction instruction)

onStop

private void onStop()

isRunning

final boolean isRunning()

A package internal method: whether or not the state machine is running or has stopped

join

public final void join()

If StateMachine is asynchronous, block until there are no pending events.

transitionToState

final void transitionToState(StateDefinition state_definition,
                             Event event)

setState

final void setState(State state,
                    Event event)

doCheckEventTypeEnabledStates

private void doCheckEventTypeEnabledStates()

firePreStateDeactivate

final void firePreStateDeactivate(State state)

firePostStateDeactivate

final void firePostStateDeactivate(State state)

firePreStateActivate

final void firePreStateActivate(State state)

firePostStateActivate

final void firePostStateActivate(State state)

fireEventHandlingError

final void fireEventHandlingError(Event event,
                                  Throwable throwable)

fireEventEnabledStateEvaluationError

final void fireEventEnabledStateEvaluationError(Throwable throwable)

fireEventTypeEnabledStateChanged

final void fireEventTypeEnabledStateChanged(EventType event_type,
                                            boolean is_enabled)

fireStateMachineStopped

final void fireStateMachineStopped()

logListenerError

private void logListenerError(String listener_method_name,
                              Throwable t)