Pronto State

Pronto's state module contains a "state transition graph" API in the package com.tomgibara.pronto.state package. The module provides the ability to:

Obtain editors with which to programmatically define graphs composed of states (vertices) and labelled transitions (edges).
Produce immutable graph objects that can be shared between threads.
Identify all paths between any sets of states in a graph; including graphs which contain cycles.
Create engine objects that manage a single state within the constraints of a state graph and state activator (an object that does any work associated with performing a transition).
Listen to engine state changes and identify and recover from exceptions that may have left an engine in an inconsistent state.

Editing Graphs

We take the simple state graph below as an example. This general state pattern should be familiar to developers who have used any of the common Java frameworks.

We begin by creating classes which model our states and transitions. Because our example is so simple, we can use two enums.

public enum State {
    constructed, initialized, started, destroyed
}

public enum Label {
    init, start, stop, destroy
}

Now we define the graph by obtaining a factory, an empty graph from that factory and an editor from the empty graph. The editor features lots of methods for editing graphs but in this case we just need to add transitions. Note that adding the transitions via an editor automatically adds the associated states.

    StateGraph createGraph() {
        //create the editor
        StateFactory factory = StateFactory.getInstance();
        StateGraph<State, Label> empty = factory.emptyStateGraph();
        StateGraphEditor<State, Label> editor = empty.newEditor();
        //define the graph
        editor.addTransition(State.constructed, Label.init, State.initialized);
        editor.addTransition(State.initialized, Label.start, State.started);
        editor.addTransition(State.started, Label.stop, State.initialized);
        editor.addTransition(State.initialized, Label.destroy, State.destroyed);
        //create the graph
        return editor.getGraph();
    }

Creating Engines

Now we create an engine that can use this graph to move between a set of states. Any actions to be performed in response to state changes should be performed by activators; engines are safe for concurrent use and do the work of ensuring that their associated activator receives events sequentially and in the correct order.

    StateEngine createEngine() {
        StateGraph<State, Label> graph = createGraph();
        StateFactory factory = StateFactory.getInstance();
        StateActivator<State, Label, ?> activator =
            new StateActivator<State, Label, Object>() {
                public void changeState(State state) {
                    System.out.println(state);
               }
                public void transitionState(
                    StateTransition<State, Label> transition, Object parameter
                ) {
                    System.out.println(transition);
                }
            };
        return factory.newEngine(graph, activator);
    }

Java's generics make this look very convoluted, but it is very simple; we create a graph, create an activator that echos its calls to stdout and create an engine that combines the two.

At present, a StateActivator is required to create a StateEngine, this may be relaxed in future versions of the api.

Using Engines

Now we are in a position to use the engine, as in the following method.

    void performTransitions() {
        StateEngine engine = createEngine();
        //set the state explicitly
        engine.setState(State.constructed);
        //transition along a label
        engine.transition(null, Label.init, null);
        //transition to a state
        engine.transition(State.started, null, null);
        //transition to the same state
        engine.pathTransition(State.started, null, PathType.uniqueTransitions, null);
        //use the graph to identify a state
        State terminal = engine.getGraph().getTerminalState();
        //transition to a state via a label
        engine.pathTransition(terminal, null, PathType.uniqueStates, null);
    }

Executing this method produces the following output. A line-by-line explanation follows.

constructed [transition from constructed to initialized via init] [transition from initialized to started via start] [transition from started to initialized via stop] [transition from initialized to started via start] [transition from started to initialized via stop] [transition from initialized to destroyed via destroy]

Before an engine can undergo any transitions, a start-state must be specified. This is what the first line does; it sets the engine to be in the constructed state. Once an engine has a state, the state cannot be set again but must be manipulated by transitions. The exception to this is if an activator throws an unchecked exception. In this case transitions will work until a new state ahas been set (see StateGraph.getPossibleStates()) for more details.
When the engine has a state, we can use the transition method. In this example we instruct the engine to follow the transition labelled init. As a result the engine is now in the initialized state. If any instruction is ambiguous (ie. if there is more than one path which matches the criteria given, an exception is raised).
Instead of specifying a label for a transition, it is possible to simply specify the target state. In this case, the engine enters the started state.
If the engine is instructed to enter the state it is currently in, it will look for a cycle of transitions that lead back to the same state. So specifying the started state again results in two transitions being made: stop followed by start.
Because graphs are immutable and thread-safe, engines can safely expose them. The graph can be interrogated for information; in this case we identfy the unique terminal state (which is destroyed).
Finally, we specify that the engine enter the terminal state identified above. It analyses the graph, identifying the unique path which leads to that state, and then transitions accordingly from the started state through the initialized state to enter the destroyed state . The engine is now effectively immutable since there are no possible transitions. The graph can of course be reused in any number of engines.

Other features of the API

The api does not permit null states and labels.
StateEngine objects can have listeners attached to them that are notified of state changes and state transitions after they have occured.
Parameters may be passed through to StateActivator objects via the transition method.
There is no constraint on the multiplicity or directionality of transitions between states. The only constraint is that there can only be one transition with a given (source, label, target) combination.