Java Finite State Machine Framework

Well-formed Boolean expression may contain:

• constants true and false;
• input actions identifiers;
• logical operators ! (not), && (and), || (or);
• relation operators >, <, !=, ==, >=, <=.

Formal BNF grammar definition for well-formed Boolean expression is:

S -> S || I1 | I1

I1 -> I1 && I2 | I2

I2 -> !I3 | I3

I3 -> (S) | I4

I4 -> I5 rel I5 | IB | CB

I5 -> IN | CN

Where IB – Action identifier that corresponds to method with boolean return type, CB – Boolean constant true or false, IN – Action identifier that corresponds to method with int return type, CN – natural number constant.

Correct Boolean expressions examples:

• !o1.x1 && o2.x2 > 10
• (o1.x1 || o1.x2 || o2.x2 != 10) && o2.x10
• true && o1.x2

Semantics of Boolean expression or interpretation rules are the following: after compilation, Boolean expression is parsed into AST, leaves of AST are action identifiers and constants; AST value is calculated using depth first search; to calculate action identifier value, corresponding method of corresponding ControlledObject is being called.

For example, to calculate value of Boolean expression !o1.x1 && o2.x2 > 10 the following steps us needed to be done:

1. calculate o2.x2: call method x2() of ControlledObject with identifier o2;
2. calculate o2.x2 > 10 using already calculated value of o2.x2;
3. calculate o1.x2: call method x2() of ControlledObject with identifier o2;
4. calculate !o1.x1 using already calculated value of o1.x1;
5. calculate !o1.x1 && o2.x2 > 10 using already calculated value for expression parts !o1.x1 and o2.x2 > 10.

Consider you have to programmatically create model that is shown on fig. 2.

Figure 2. Sample FSM Graphical Model

Resulting Java code will look like:

// create model
Model m = Model.createModel("test");
// create state machine A1
StateMachine A1 = m.createStateMachine("A1");
// create event provider and associate it with state machine A1
A1.createAssociation(m.createEventProviderHandler(
	"p1", "test.Provider1"), "p1");
// create controlled object and associate it with state machine A1
// using identifier "o1"
A1.createAssociation(m.createControlledObjectHandler(
	"o1", "test.ControllableObject1"), "o1");

// create top state and set it as top for state machine A1
State top = A1.createTopState("TOP");
A1.setTop(top);
// create other states
State initial1 = A1.createState("initial1", StateType.INITIAL);
State s2 = A1.createState("s2", StateType.NORMAL);
State initial2 = A1.createState("initial1", StateType.INITIAL);
State s4 = A1.createState("s4", StateType.NORMAL);
// add on-enter actions for state s4
s4.addOnEnterAction(A1. createAction("o1.z2"));
State final1 = A1. createAction("final1", StateType.FINAL);

// setup child-parent relations for states
top.addSubstate(initial1);
top.addSubstate (s2);
top.addSubstate (final1);
s2.addSubstate (initial2);
s2.addSubstate (s4);

// create transitions between states
Transition t1 = A1.createTransition(initial1, s2, null, null);
t1.addOutputAction(A1.createAction("o1.z1"));
Transition t2 = A1.createTransition(initial2, s4, null, null);
Transition t3 = A1.createTransition(
	s4, s4, A1.createGuard("o1.x1"), A1.createEvent("e1"));
Transition t4 = A1.createTransition(
	s4, final1, A1.createGuard("!o1.x1"), A1.createEvent("e1"));
			

If you want to pass this model to interpreter, you have to compile model with a help of the following code:

StateMachineCompiler smc = new StateMachineCompiler(null);
DefaultCompilationListener dcl = new DefaultCompilationListener();
smc.addCompilationListener(dcl);
smc.compileWithIncluded(A1);
			

The only initialization parameter of StateMachineCompiler is OperationResolver. This interface should be implemented in case when actions associated with methods of ControlledObject could be resolved. There is no any default implementation of this interface in framework, but there is one in Eclipse plug-in. If you pass implementation of this interface to StateMachineCompiler, it will make additional semantic checks.

To see compilation errors use code:

for (int i = 0; i < dcl.getErrors().length; i++) {
	System.out.println(dcl.getErrors()[i]);
}
			

Actually compilation process does the following:

• checks that every model element has name;
• checks that ControlledObjectHandlers and EventProviderHandlers have not empty implementation class;
• checks that every State has StateType;
• parses and translates to AST all Guards Boolean expressions;
• parses and translates Actions identifiers to pair (ControlledObject reference, method name).

During compilation the following errors may be found:

• model element has empty name;
• EventProviderHandler or ControlledObjectHandler has empty implementation class;
• empty state type;
• incorrect Action identifier;
• incorrect Guard Boolean expression syntax;
• unresolved reference to ControlledObject in Action identifier;
• unresolved reference to method of ControllableObject in Action identifier.

After compilation model is ready for interpreting, but also it may be checked for semantics errors using model validation facilities.

FSM model validation facilities allow finding errors in model during Design Phase. Some validation methods may be called “model static verification”.

You may validate in-memory FSM model programmatically using code:

// init validator
StateMachineValidator validator = StateMachineValidator.createValidator(A1);

// create default implementation of validation errors listener
ValidationMessenger validationMessenger = new ValidationMessenger();
// setup default validation error listener
validator.addStructureListener(validationMessenger);
validator.addAttainabilityListener(validationMessenger);
validator.addConsistencyListener(validationMessenger);
validator.addCompletenessListener(validationMessenger);

// validate structure
validator.validateStructure();
// validate states attainability
validator.validateAttainability();
// validate transitions consistency
validator.validateConsistency();
// validate transitions completeness
validator.validateCompleteness();
				

FSM XML-description may be checked with command line validation tool:

java -jar UniMod-Core-XX.XX.XXX.jar A1.xml

During model validation the following errors may be found:

• composite state has no initial state;
• composite state has more then one initial state;
• state is unattainable;
• transition set for given event is incomplete;
• two transitions are inconsistent;
• state has more then one outgoing “else” transition;
• transition from initial state has event on it;
• not root state machine has associated EventProviderHandlers.

In-memory FSM model may be serialized into XML file, XML file may be de-serialized into in-memory model. For storing model in XML file statemachine.dtd is used.

To support model serialization to XML and de-serialization from XML special XML Transformers classes exist. The following code demonstrates how store model in XML:

// create file 
FileOutputStream f = new FileOutputStream("model.xml");
// write model to file
ModelToXML.write(model, f);
// close file
f.close();
				

Next code shows how to load model from XML:

// open file 
FileInputStream f = new FileInputStream("model.xml");
// load model
Model model = XMLToModel.load(f);
// close file
f.close();
				

Also, there is Transformer for generating C++ code for Symbian platform (comming soon).

1. On startup engine calls EventProvider.init() for all event providers associated with root StateMachine, setup EventHandler implementation depending of chosen thread model, set given ConfigStore to root StateMachine if root StateMachine has empty ConfigStore;
2. On Event post engine calls EventProcessor implementation. EventProcessor do the following:
   1. Loads current StateMachine Config using associated ConfigStore. If loaded Config is null, then Initial State of Top State is treated as active State;
   2. Gets outgoing Transitions from active State that has Events equals to posted Event; looks through all selected Transitions and calculates Guard Boolean expressions; stops when calculated Boolean expression is true; Transition that owns such Boolean expression is trigged;
   3. Executes output Actions on Transition that is being trigged, executes on-enter Actions in target State;
   4. If target State is composite, continues processing from step 2.2;
   5. If target State is not composite, executes included StateMachines starting from step 2.1. Note, that if included StateMachine has empty ConfigStore, parent ConfigStore will be used: engine will ask Config of parent StateMachine to create sub-Config for included StateMachine and the whole parent Config with sub-Configs will be stored when all included StateMachines finish event processing;
   6. Saves new StateMachine Config using associated ConfigStore;
3. If root StateMachine active State has type StateType.FINAL, calls EventProvider.dispose() for all event providers associated with root StateMachine and stops accepting Events.

Two execution thread models are supported by runtime engine:

• Strict. Thread that comes with Event is used for event processing. Caller of method EventHandler.handle() is blocked until the end of Event processing. If more then one Event will be posted concurrently, their thread will not be joined, so there will be more then one thread processing Event against the same engine. It’s not bad and rather good for developing Web application that works inside Servlet container. See Messenger Web for more details;
• Queued. Event queue exists. Event dispatcher thread checks for new Event in queue and if there is one – starts its processing. It’s guaranteed that Events are dispatched from queue one-by-one, so in any time only one Event is being processed against same engine. Caller thread is not blocked. It’s not allowed to change in-memory model after StateMachineEngine created.

Runtime engine is delivered with default implementations of EventProcessorFactory and EventProcessor classes. If you want to create custom implementation, follow next rules.

EventProcessorFactory subclass must has public no args constructor.

EventProcessorFactory has public static method create() that is used by StateMachineEngine to obtain EventProcessorFactory instance. Method create() tries to find name of class that subclasses EventProcessorFactory using algorithm:

1. get system property (System.getProperty()) with name com.evelopers.unimod.runtime.EventProcessorImplFactory;
2. if not found, tries to load properties from file unimod.properties using method EventProcessorFactory.class.getClassLoader().getResourceAsStream() and get property with name com.evelopers.unimod.runtime.EventProcessorFactory from loaded bundle;
3. if not found, creates default implementation com.evelopers.unimod.runtime.impl1.EventProcessorImplFactory1;

Subclass of EventProcessorFactory must implement the only method that must return instance of EventProcessor:

public EventProcessor newExecutor(StateMachine sm) {…}						
					

EventProcessor subclass must implement the only method:

protected abstract State process(
	Config config, 
	State activeState, 
	Event event, 
	StateMachineContext context) 
		throws EventProcessorException, InterpreterException;
					

ConfigStore subclass must have public no agrs constructor.

ConfigStore subclass must implement methods for storing and loading Config. StateMachineContext is passed to ConfigStore methods, so StateMachineContext may be used as underlining Config storage. For example, interpreter for Web Applications associates User Context with HttpSession, it allows to store Config user HttpSession.

Config may be stored in database. It’s useful when you model behavior of some business entity such as Order, for example. Consider that Order has some behavior that is described using UniMod methodology, so you can implement ConfigStore that will store Order state in database, but all business logic will be implemented on Java. Such approach suits for applications with thin database – database that has no stored procedures that controls entities behavior.

ControlledObject subclass must have public no args constructor. Methods that correspond to input Actions must have signatures like this:

/**@unimod.action.descr is initialization successful */
public boolean xM(StateMachineContext ctx) 
	throws MyException1, MeException2 {…}

/**@unimod.action.descr number of logged-in users */
public int xM(StateMachineContext ctx) 
	throws MyException1, MeException2 {…}
					

Methods that correspond to output Actions must have signature:

/**@unimod.action.desc makes some action */
public void zK(StateMachineContext ctx) 
	throws MyExcpetion1, MyException2 {…}
					

JavaDoc tag @unimod.action.descr allows to define action description, that will be shown on Connectivity Diagram. All exceptions thrown by methods of ControlledObject will be passed to registered ExceptionHandlers method handleException().

Unit subclass must implement the only method:

public void handle(
	final Position p,
	final Config config,
	final Event event,
	final State processedState,
	final Transition processedTransition,
	final Action processedAction);
					

This method will be called by EventProcessor during Event processing in places that are described by class Position.

EventProvider subclass must have public no args constructor.

EvnetProvider subclass must start none daemon thread in EvnetProvider.init() method to notify EventHandler about new Events. It’s not permitted to hang in EvnetProvider.init(). In EvnetProvider.dispose() methods thread must be stopped. Such technique allows JVM to exit when root StateMachine comes to Final State, because on-enter to Final State StateMachineEngine calls EventProvider.dispose() method for all event providers.

To post Event EventProvider must pass implementation of StateMachineContext interface to EventHandler, this implementation will be delegated to all methods of ControllableObjects that will be executed during Event processing, it means that StateMachineContext acts as shared data bus.

EventProvider subclass may define Events that it throws with a help of code snippet:

/**@unimod.event.descr timer tick */
public static final String EN = “eN”;
					

Special JavaDoc tag @unimod.event.descr allows to define Event description, that will be shown on Connectivity Diagram.

StateMachineEngine guarantees that there are no concurrent calls to StateMachineContext during Event processing inside this particular engine, but if you create more then one instance of StateMachineEngine that will operate concurrently and will pass them the same StateMachineContext for Event processing, there is no guarantee that there will be no concurrent calls to StateMachineContext.

There is another example of satiation, when concurrent calls are possible. Consider you’ve created engine with Strict thread model, but your EventProvider post Events in different threads. Strict thread model doesn’t join Event threads, so concurrent threads against the same engine will take place and, consequently, there will be concurrent calls to StateMachineContext.

StateMachineContext consists of three contexts:

• Event context – shared data bus that must “live” only during event processing;
• User context – shared data bus that must be associated with application user session (for Web applications it is HttpSession);
• Application context – shared data bus that must “live” while application alive.

Developers are free to implement StateMachineContext as they want, but we strongly recommend to follow the rules described above.