[[introduction]]
= Introduction
Spring Statemachine(SSM) is a framework for application developers to
use traditional state machine concepts with Spring applications. SSM
aims to provide the following features:

* Easy to use flat one level state machine for simple use cases.
* Hierarchical state machine structure to ease complex state
  configuration.
* State machine regions to provide even more complex state
  configurations.
* Usage of triggers, transitions, guards and actions.
* Type safe configuration adapter.
* State machine event listeners.
* Spring IOC integration to associate beans with a state machine.

Before you continue it's worth to go through appendices <<glossary>>
and <<crashcourse>> to get a generic idea of what state machines are,
mostly because the rest of the documentation expects the reader to be
fairly familiar with state machine concepts.

== Background
State machines are powerful because behaviour is always guaranteed to be
consistent and relatively easily debugged due to how operational
rules are written in stone when machine is started. The idea is that your
application is and may exist in a finite number of states and then something
happens which takes your application from one state to the next. What
will drive a state machine are triggers, which are either based on
events or timers.

It is much easier to design high level logic outside of your
application and then interact with a state machine in various
different ways. You can simply interact with a state machine by
sending events, listening to what a state machine does or simply requesting
the current state.

Traditionally state machines are added to an existing project when
developers realize that the code base is starting to look like a plate
full of spaghetti. Spaghetti code looks like a never ending, hierarchical
structure of IFs, ELSEs and BREAK clauses and probably compilers should
ask developers to go home when things are starting to look too complex.

== Usage Scenarios

A project is a good candidate to use a state machine if:

* The application or part of its structure can be represented as states.
* You want to split complex logic into smaller manageable tasks.
* The application is already suffering concurrency issues with i.e.
  something happening asynchronously.

You are already trying to implement a state machine if:

* Using boolean flags or enums to model situations.
* Having variables which only have meaning for some part of your
  application lifecycle.
* Looping through if/else structure and checking if a particular flag or
  enum is set and then making further exceptions about what to do when certain
  combinations of your flags and enums exist or don't exist together.

