spring-statemachine/index.html

---
# The name of your project
title: Spring Statemachine

badges:

  # Customize your project's badges. Delete any entries that do not apply.
  custom:
    - name: Source (GitHub)
      url:  https://github.com/spring-projects/spring-statemachine
      icon: github

    - name: Issues (GitHub)
      url:  https://github.com/spring-projects/spring-statemachine/issues
      icon: tracking

    - name: CI (Bamboo)
      url:  https://build.spring.io/browse/SDG
      icon: ci

    - name: CI (Travis)
      url:  https://travis-ci.org/spring-projects/spring-statemachine
      icon: ci

    - name: StackOverflow
      url:  https://stackoverflow.com/questions/tagged/spring-statemachine
      icon: stackoverflow

    - name: Gitter
      url:  https://gitter.im/spring-projects/spring-statemachine
      icon: forum

---
<!DOCTYPE HTML>
<html lang="en-US">

{% capture billboard_description %}

Spring Statemachine is a framework for application developers to use state machine concepts with Spring applications.

{% endcapture %}

{% capture main_content %}

Spring Statemachine aims to provide 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.
* Builder pattern for easy instantiation for use outside of Spring Application context
* Recipes for usual use cases
* Distributed state machine based on a Zookeeper
* State machine event listeners.
* UML Eclipse Papyrus modeling.
* Store machine config in a persistent storage.
* Spring IOC integration to associate beans with a state machine.

State machines are powerful because behaviour is always guaranteed to be consistent, making it relatively easy to debug. This is because operational rules are written in stone when the machine is started. The idea is that your application may exist in a finite number of states and certain predefined triggers can take your application from one state to the next. Such triggers can be based on either events or timers.

It is much easier to define high level logic outside of your application and then rely on the state machine to manage state. You can interact with the state machine by sending an event, listening for changes or simply request a current state.

Do you want to ask a question? Go to [StackOverflow](https://stackoverflow.com) and use a tag [spring-statemachine](https://stackoverflow.com/questions/tagged/spring-statemachine) or [Gitter](https://gitter.im/spring-projects/spring-statemachine).

<span id="quick-start"></span>
## Quick Start

{% include download_widget.md %}

Following samples should give an idea how statemachine is configured and used. Assuming we have states **STATE1**, **STATE2** and events **EVENT1**, **EVENT2**.

<img class="styled-image" src="img/statechart0.png" alt="Statechart" title="Statechart"/>

```java
static enum States {
    STATE1, STATE2
}

static enum Events {
    EVENT1, EVENT2
}
```

### Builder

```java
public StateMachine<States, Events> buildMachine() throws Exception {
    Builder<States, Events> builder = StateMachineBuilder.builder();

    builder.configureStates()
        .withStates()
            .initial(States.STATE1)
            .states(EnumSet.allOf(States.class));

    builder.configureTransitions()
        .withExternal()
            .source(States.STATE1).target(States.STATE2)
            .event(Events.EVENT1)
            .and()
        .withExternal()
            .source(States.STATE2).target(States.STATE1)
            .event(Events.EVENT2);

    return builder.build();
}
```

```java
StateMachine<States, Events> stateMachine = buildMachine();
stateMachine.start();
stateMachine.sendEvent(Events.EVENT1);
stateMachine.sendEvent(Events.EVENT2);
```

### JavaConfig

```java
@Configuration
@EnableStateMachine
static class Config1 extends EnumStateMachineConfigurerAdapter<States, Events> {

    @Override
    public void configure(StateMachineStateConfigurer<States, Events> states)
            throws Exception {
        states
            .withStates()
                .initial(States.STATE1)
                .states(EnumSet.allOf(States.class));
    }

    @Override
    public void configure(StateMachineTransitionConfigurer<States, Events> transitions)
            throws Exception {
        transitions
            .withExternal()
                .source(States.STATE1).target(States.STATE2)
                .event(Events.EVENT1)
                .and()
            .withExternal()
                .source(States.STATE2).target(States.STATE1)
                .event(Events.EVENT2);
    }
}
```

```java
@WithStateMachine
static class MyBean {

    @OnTransition(target = "STATE1")
    void toState1() {
    }

    @OnTransition(target = "STATE2")
    void toState2() {
    }
}
```

```java
static class MyApp {

    @Autowired
    StateMachine<States, Events> stateMachine;

    void doSignals() {
        stateMachine.start();
        stateMachine.sendEvent(Events.EVENT1);
        stateMachine.sendEvent(Events.EVENT2);
    }
}
```

{% endcapture %}

{% capture related_resources %}

### Resources

* [Samples](https://github.com/spring-projects/spring-statemachine/tree/master/spring-statemachine-samples)

{% endcapture %}


{% include project_page.html %}
</html>