A core Java tool which provides state machine semantics using enums, strings, or anything else you want to represent the various states. States have transitions which can move them to other states. Callbacks are provided for transitions, and for each state when entering or exiting. It is also possible to route a transition request based on your own logic. You can even provide a callback which will fire when a sequence of states is matched.
All of the methods which modify, transition, or inquire about the state are synchronized, allowing multiple threads access to the same state machine. However, to avoid unpredictable behavior, it is generally better to construct your state machine up front and not modify it thereafter. The EnumStateMachine and StringStateMachine in particular can be serialized to and from their string representations.
As of version 3.0, the minimum version of Java required is JDK 8.
The project is built using Maven, and the artifacts are available from Maven Central. (If you are a current user of the tool, note that the group name has been recently changed to accommodate Sonatype's repository hosting requirements.)
<dependency>
<groupId>com.unquietcode.tools.jstate</groupId>
<artifactId>jstate</artifactId>
<version>3.1</version>
</dependency>
You can view the provided Javadocs or the unit tests for more information about how to use the library.
A typical use case might be a state machine for controlling a process, which can move between the
states [Ready, Running, Paused, Stopping, Stopped, Finished].
After declaring a state enum we can set up a new state machine as follows:
enumState {
Ready, Running, Paused, Stopping, Stopped, Finished
}
...
EnumStateMachine<State> esm = newEnumStateMachine<>(State.Ready);
esm.addTransitions(State.Ready, State.Running, State.Finished);
esm.addTransitions(State.Running, State.Paused, State.Stopping);
esm.addTransitions(State.Paused, State.Running, State.Stopping);
esm.addTransitions(State.Stopping, State.Stopped);
esm.addTransitions(State.Stopped, State.Finished);
esm.addTransitions(State.Finished, State.Ready, null);
esm.transition(State.Running);The initial state is set either in the constructor or the setInitialState(...) method. The addTransition(...)
method supports mapping from 1..n states. In the example above, we see that some states can move to more than
one other states. The null state is also a possibility, depending on your preference.
Callbacks can be added as transitions are defined, and fire during transition between states:
TransitionHandler<State> cb = newTransitionHandler<>() {
publicvoidonTransition(Statefrom, Stateto) {
// ....
}
};
esm.addTransitions(cb, State.Ready, State.Running);Callbacks can also be added on entering or exiting a state.
esm.onEntering(State.Running, newStateHandler<State>() {
publicvoidonState(Statestate) {
entered.incrementAndGet();
}
});
esm.onExiting(State.Running, newStateHandler<State>() {
publicvoidonState(Statestate) {
exited.incrementAndGet();
}
});StateRouters allow you to 'deflect' or 'redirect' a transition based on your own custom logic.
There are several pre-defined routers available which provide round-robin and randomized routing.
esm.routeBeforeEntering(TestStates.Three, newStateRouter<TestStates>() {
publicTestStatesroute(TestStatescurrent, TestStatesnext) {
returnTestStates.Two;
}
});SequenceHandlers are callbacks which are triggered whenever the specified sequence of states
occurs in the state machine.
finalList<Color> _pattern = Arrays.asList(Color.Blue, Color.Green, Color.Orange);
sm.onSequence(_pattern, newSequenceHandler<Color>() {
publicvoidonMatch(List<Color> pattern) {
// pattern equals [Blue, Green, Orange]
}
});There is also support for wildcard matching in sequences, available through the use
of the PatternBuilder class.
finalPattern<Color> _pattern = PatternBuilder.<Color>create()
.add(Color.Red, Color.Blue)
.addWildcard()
.add(Color.Green)
.build();
sm.onSequence(_pattern, newSequenceHandler<Color>() {
publicvoidonMatch(List<Color> pattern) {
// pattern equals [Red, Blue, Purple, Green]
}
});A special form of StringStateMachine (which uses strings as states) is available as the ReflectiveStateMachine.
This flavor allows you to declare your callbacks as methods of the state machine class. The arguments are flexible, matching the standalone callback
method's signature and allowing you to skip parameters you don't care about.
ReflectiveStateMachinesm = newReflectiveStateMachine() {
// (optional method to declare transitions inline)protectedvoiddeclareTransitions() {
addTransition(null, "blue");
addTransition("blue", "green");
addTransition("green", null);
}
publicvoidonEnteringBlue(Stringstate) {
enteringBlue.incrementAndGet();
}
publicvoidonExitingBlue() {
exitingBlue.incrementAndGet();
}
publicvoidonGreen() {
enteringGreen.incrementAndGet();
}
publicvoidonEntering() {
enteringAny.incrementAndGet();
}
publicvoidonExiting() {
exitingAny.incrementAndGet();
}
publicvoidonTransition() {
transitionAny.incrementAndGet();
}
};
sm.transition("blue");
sm.transition("green");
sm.transition(null);See the tests for more usage examples.
JState is licensed under the MIT license. Go wild.
Send an email to blouis@unquietcode.com
Peace, love, and code.