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

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

Direct Known Subclasses:

CompareSchemaOnlyStateMachineDefinition, DemoStateMachineDefinition, ExampleApplicationStateMachineDefinition, UpgradeToolStateMachineDefinition

public class StateMachineDefinition

extends Object

A description of the structure of a StateMachine (eg a MetaStateMachine). StateMachineDefinitions record the start, stop, and basic states of a state machine, the events that each state can handle, and the actions that can be conditionally taken for each event type.

StateMachineDefinitions have one start state and one or more stop states. Any number of basic states may be added.

Developers should ensure that start event handlers are registered with the single StartState and that there is some pathway to the stop states. If a StateMachineDefinition is created that does not satisfy these constraints, then it will be possible to instantiate a StateMachine that cannot be used or shutdown properly.

Once defined a StateMachineDefinition may be shared my any number of StateMachine instances. Modification of a StateMachineDefinition after instantiating a dependent StateMachine is not supported and may lead to unexpected behavior.

Example Definition

The following is an example of a StateMachineDefinition for a machine with three states (State1, State2, and State3 defined in corresponding Java classes) that allows the following unconditional transitions:

   START  -> State1
   State1 -> State2
   State1 -> State1
   State2 -> State1
   State2 -> State2
   State2 -> State3
   State3 -> State2
   State3 -> State3
   State3 -> STOP

 public class MyStateMachineDefinition
    extends StateMachineDefinition
 {
    MyStateMachineDefinition()
    {
       super(); // one stop state;
  
       final StartStateDefinition start_def = getStartStateDefinition();
       final BasicStateDefinition state1_def = newStateDefinition(State1.class);
       final BasicStateDefinition state2_def = newStateDefinition(State2.class);
       final BasicStateDefinition state3_def = newStateDefinition(State3.class);
       final StopStateDefinition stop_def = getStopStateDefinitions()[0];
  
       start_def.addStartEventHandler(Condition.ALWAYS, new Transition(state1_def));
  
       state1_def.addEventHandler(GOTO_1, Condition.ALWAYS, new Transition(state1_def));
       state1_def.addEventHandler(GOTO_2, Condition.ALWAYS, new Transition(state2_def));
  
       state2_def.addEventHandler(GOTO_1, Condition.ALWAYS, new Transition(state1_def));
       state2_def.addEventHandler(GOTO_2, Condition.ALWAYS, new Transition(state2_def));
       state2_def.addEventHandler(GOTO_3, Condition.ALWAYS, new Transition(state3_def));
  
       state3_def.addEventHandler(GOTO_2, Condition.ALWAYS, new Transition(state2_def));
       state3_def.addEventHandler(GOTO_3, Condition.ALWAYS, new Transition(state3_def));
       state3_def.addEventHandler(EXIT, Condition.ALWAYS, new Transition(stop_def));
    }
 }

See Also:

StateMachine

Field Summary

static EventType	CANCEL
static EventType	CONTINUE
static EventType	EXIT
static EventType	RESTART
static EventType	RESTARTED
private StartStateDefinition	startStateDefinition_
private HashSet	stateDefinitions_
private StopStateDefinition[]	stopStateDefinitions_
static EventType	THREADED_WORK_CANCELED
static EventType	THREADED_WORK_COMPLETE
static EventType	THREADED_WORK_ERRORED

Constructor Summary

StateMachineDefinition()
Create a machine definition that has a single stop state.

StateMachineDefinition(int number_of_stop_states)
Create a machine definition that has number_of_stop_states stop states.

Method Summary

void	describe() Dumps a description of this state machine definition to System.out.
StartStateDefinition	getStartStateDefinition() Return the StateMachineDefinitions single start state.
StopStateDefinition[]	getStopStateDefinitions() Return the StateMachineDefinitions stop states.
BasicStateDefinition	newStateDefinition(Class state_class) Create a StateDefinition for which instances of the specified State class will be used.
BasicStateDefinition	newStateDefinition(StateInstantiator state_instantiator) Create a StateDefinition that uses a custom StateInstantiator to create State instances.
(package private) void	transitionToState(StateDefinition state_definition, StateMachine sm, Event event) A package internal method: ask the definition for a controlled transition to a state with the specified definition.

Methods inherited from class java.lang.Object

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

Field Detail

CONTINUE

public static EventType CONTINUE

RESTART

public static EventType RESTART

RESTARTED

public static EventType RESTARTED

CANCEL

public static EventType CANCEL

EXIT

public static EventType EXIT

THREADED_WORK_COMPLETE

public static EventType THREADED_WORK_COMPLETE

THREADED_WORK_CANCELED

public static EventType THREADED_WORK_CANCELED

THREADED_WORK_ERRORED

public static EventType THREADED_WORK_ERRORED

stateDefinitions_

private HashSet stateDefinitions_

startStateDefinition_

private StartStateDefinition startStateDefinition_

stopStateDefinitions_

private StopStateDefinition[] stopStateDefinitions_

Constructor Detail

StateMachineDefinition

public StateMachineDefinition()

Create a machine definition that has a single stop state.

StateMachineDefinition

public StateMachineDefinition(int number_of_stop_states)

Create a machine definition that has number_of_stop_states stop states.

Method Detail

getStartStateDefinition

public final StartStateDefinition getStartStateDefinition()

Return the StateMachineDefinitions single start state.

Returns:

a non-null reference to the single start state

getStopStateDefinitions

public final StopStateDefinition[] getStopStateDefinitions()

Return the StateMachineDefinitions stop states.

Returns:

a non-null array of at least one stop state

newStateDefinition

public final BasicStateDefinition newStateDefinition(Class state_class)

Create a StateDefinition for which instances of the specified State class will be used. Not that this class must meet the requirements of the class DefaultStateInstantiator.

Returns:

a non-null BasicStateDefinition

See Also:

DefaultStateInstantiator

newStateDefinition

public final BasicStateDefinition newStateDefinition(StateInstantiator state_instantiator)

Create a StateDefinition that uses a custom StateInstantiator to create State instances.

Returns:

a non-null BasicStateDefinition

describe

public void describe()

Dumps a description of this state machine definition to System.out.

transitionToState

final void transitionToState(StateDefinition state_definition,
                             StateMachine sm,
                             Event event)

A package internal method: ask the definition for a controlled transition to a state with the specified definition. Will error if the state definition hasn't been added to this state machine definition.