Giter Site home page Giter Site logo

jstate's Introduction

JState (v2.0)

Tip with Gratipay Tip with BitcoinBitcoin

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.

Installation

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 changed to accommodate Sonatype's repository hosting requirements.)

<dependency>
    <groupId>com.unquietcode.tools.jstate</groupId>
    <artifactId>jstate</artifactId>
    <version>2.0</version>
</dependency>

Usage

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].

State Diagram

After declaring a state enum we can set up a new state machine as follows:

enum State {
    Ready, Running, Paused, Stopping, Stopped, Finished
}

...

EnumStateMachine<State> esm = new EnumStateMachine<State>(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 = new TransitionHandler<State>() {
    public void onTransition(State from, State to) {
        // ....
    }
};

esm.addTransitions(cb, State.Ready, State.Running);

Callbacks can also be added on entering or exiting a state.

esm.onEntering(State.Running, new StateHandler<State>() {
	public void onState(State state) {
		entered.incrementAndGet();
	}
});

esm.onExiting(State.Running, new StateHandler<State>() {
	public void onState(State state) {
		exited.incrementAndGet();
	}
});

StateRouters allow you to 'deflect' or 'redirect' a transition based on your own custom logic.

esm.routeBeforeEntering(TestStates.Three, new StateRouter<TestStates>() {
	public TestStates route(TestStates current, TestStates next) {
		return TestStates.Two;
	}
});

SequenceHandlers are callbacks which are triggered whenever the specified sequence of states occurs in the state machine.

List<Color> _pattern = Arrays.asList(Color.Blue, Color.Green, Color.Orange);

sm.onSequence(_pattern, new SequenceHandler<Color>() {
	public void onMatch(List<Color> pattern) {
		assertEquals(_pattern, pattern);
	}
});

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.

ReflectiveStateMachine sm = new ReflectiveStateMachine() {

	// (optional method to declare transitions inline)
	protected void declareTransitions() {
		addTransition(null, "blue");
		addTransition("blue", "green");
		addTransition("green", null);
	}

	public void onEnteringBlue(String state) {
		enteringBlue.incrementAndGet();
	}

	public void onExitingBlue() {
		exitingBlue.incrementAndGet();
	}

	public void onGreen() {
		enteringGreen.incrementAndGet();
	}

	public void onEntering() {
		enteringAny.incrementAndGet();
	}

	public void onExiting() {
		exitingAny.incrementAndGet();
	}

	public void onTransition() {
		transitionAny.incrementAndGet();
	}
};

sm.transition("blue");
sm.transition("green");
sm.transition(null);

See the tests for more usage examples, as well as the provided javadocs.

License

JState is licensed under the MIT license. Go wild.

Questions / Comments / Feedback

Send an email to [email protected]

Peace, love, and code.

Thanks!

jstate's People

Contributors

unquietcode avatar

Watchers

James Cloos avatar Monet Zheng avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.