Simple state machine framework (SMS) tutorial

SM inheritance. 3

Run-time changes to SM behavior definitions. 3

SMS requirements. 3

SMS usage example - SMSDemo. 3

SMSDemo state machine. 4

SMSDemo GUI controller 4

SMS API 4

State machine behavior definition API 4

State machine scheduling API 4

SMS debugger 5

How to run. 5

SMS debugger GUI 5

SMS debugger statechart 5

SMS statechart layout 5

SMS statechart icons. 5

SMS overview

SMS is software framework that allows creation, execution and debugging of finate state machines (SMs). Background information about state machines and their visual representation – statechart can be found in the following articles: Harel David, "Statecharts: A Visual Formalism for Complex Systems", UML statecharts.

In few words state machines allow modeling of an object behavior by defining set of object states, set of events handled by the object and set of state transitions to be performed during handling of the events. Statecharts are visual representations of the state machines. The following is the statechart generated by SMS debugger for state machine from the SMS usage example:

The above diagram represents:

1. Three states: initState, demoViewClosedState and demoViewProvidedState

2. Three events: SayEvent, ViewProvisioningEvent and ViewClosedEvent

3. State transitions associated with the states and events:

a. initState to demoViewProvidedState transition on the arrival of ViewProvisioningEvent, method transition() of ViewProvisioningTrans class will be executed during this state transition

b. initState to initState transition on the arrival of SayEvent, method transition() of TooEarlyTrans class will be executed during this state transition

c. demoViewProvidedState to demoViewClosedState transition on the arrival of ViewClosedEvent, there is not any transition specific logic associated with this state transition

d. demoViewClosedState to demoViewProvidedState transition on the arrival of ViewProvisioningEvent, method transition() of ViewProvisioningTrans class will be executed during this state transition

e. demoViewClosedState to demoViewClosedState transition on the arrival of SayEvent, method transition() of TooLateTrans class will be executed during this state transition

4. Icon in demoViewProvidedState means that this state is composite. Icon means that this state has entry state transition.

SMS provides:

· State machine(SM) behavior (state, events, transitions) definition API. This API allows application code to define SM states, events and state transitions

· SM scheduling API. This API allows applications to post events to SMs or call SM directly

· SMS debugger. The debugger provides visual representation of SMs runtime information such as generated statechart, current state, handled events and preformed transitions.

SMS state machine features

Basic SM features

· Event handling according to the currently defined states, events, transitions and current state

· Predefined new state calculation according SM definitions can be overridden by the transition code

· Any state can become composite state and have substates. During event handling a state will attempt to pass event to its substates, if not consumed will attempt to handle it with its own transitions. Composite state implements deep history that may be overridden with entry transition.

· Entry/exit transitions can be defined for any state. A state can have more then one entry/exit transitions. Entry transitions performed every time the state becomes current. Exit transitions performed every time the state replaced by another state as the current state. Substate entry/exit transitions performed as in the case of regular states besides the following two cases:

o Entry transition of a substate is not performed in case its composite state becomes current and the substate becomes current as the results of the deep history mechanism

o Exit transition of a substate is preformed if its composite state stops to be current

SM inheritance

It is possible to define inheritance relation between SMs. It is done by defining inheritance between parent and derived SM classes. Derived SM inherits all the behavior definitions of the parent SM. Derived SM can override the following definitions:

· Add new states and event and transitions on these states

· Add new events and transitions to derived states

· Overload transition logic of the derived transitions on the derived states

· Overload new state definitions for the derived transitions

· Extend the logic of the derived transitions

Run-time changes to SM behavior definitions

SM behavior definitions and scheduling API are thread-safe. It is possible to update SM behavior definitions by SM transitions or external application code during run-time and during event handling. The changes will be immediately reflected in the SM event handling and in the SMS debugger generated statecharts.

SMS requirements

J2SE 5.0

ANT in order to build SMS and SMSDemo.

XMLParser - crimson.jar included in the SMS package

SMS usage example - SMSDemo

The following simple application SMSDemo illustrates the usage of SMS API.

SMSDemo source code available at SMSDemo.zip. In order to run it use runDemo.bat, in order to build use ANT.

The application consists of:

· SMSDemo GUI controller – allows interaction with the application and illustrates the usage of “State machine scheduling API”. Resides in SMSDemoController.java.

· SMSDemo GUI view – provides GUI feedback Resides in SMSDemoView.java.

· SMSDemo model – binds all the components together. Resides in SMSDemoModel.java.

· SMSDemo state machine – implements the logic of the application and illustrates the usage of “State machine behavior definition API”. Resides in SMSDemoSM.java.

SMSDemo state machine

The following classes implement demo state machine:

· SMSDemoSM is the main state machine class. It uses SimpleStateMachine API in order to create states, transitions and events. SMSDemoSM inherits from SimpleStateMachine, alternatively state machine may hold internal copy of SimpleStateMachine instance and delegate to it.

o ViewProvisioningEvent, ViewClosedEvent, DayTimeEvent, NightTimeEvent, SayEvent are classes implementing events handled by SM. All these classes inherit from SMEvent, all SM events should inherit from this class.

o SMStates is the enumeration that declares SM states

o DemoViewProvidedStates is the enumeration that defines demoViewProvidedState substates

o ViewProvisioningTrans, TooEarlyTrans, TooLateTrans, DaySayTrans, NightSayTrans are classes implementing transition actions. All state transition actions should implement StateTransition interface.

o SMSDemoSM() constructor implements the following SM init states:

§ defines SM and demoViewProvidedState behavior with setSMMatrix method

§ adds demoViewProvidedState entry transition that will set demoViewProvidedState initial substate

§ sets machine initial state

SMSDemo GUI controller

The controller uses SMS scheduler to post events to the machine, the following few lines illustrate the usage:

model.scheduler.postEvent(

model.demoSM,

new SMSDemoSM.ViewProvisioningEvent(demoView)

);

SMS API

SMS JavaDoc API documentation can be found at index.html

State machine behavior definition API

SimpleStateMachineIF, SMStateIF interfaces provide SM behavior definition API

State machine scheduling API

SMScheduler provides SM scheduling API

SMS debugger

SMS debugger provides visual representation of the running SMs in the form of their statecharts with the indication of current states and handled events.

icon means the state has defined exit transitions