All features for @WithStateMachine can be enabled by using annotation @EnableWithStateMachine which simply imports needed configuration into Spring Application Context. Both @EnableStateMachine and @EnableStateMachineFactory are already annotated with this so there is no need for user to add it again. However if machine is build and configured without a use of configuration adapters, @EnableWithStateMachine must be used order to use features with @WithStateMachine. Idea for this is shown below.

public static StateMachine<String, String> buildMachine(BeanFactory beanFactory) throws Exception {
    Builder<String, String> builder = StateMachineBuilder.builder();

    builder.configureConfiguration()
        .withConfiguration()
            .machineId("myMachineId")
            .beanFactory(beanFactory);

    builder.configureStates()
        .withStates()
            .initial("S1")
            .state("S2");

    builder.configureTransitions()
        .withExternal()
            .source("S1")
            .target("S2")
            .event("E1");

    return builder.build();
}

@WithStateMachine(id = "myMachineId")
static class Bean17 {

    @OnStateChanged
    public void onStateChanged() {
    }
}

	Important
	If machine is not created as a Bean then it is mandatory to set BeanFactory for a machine as shown above. Otherwise machine will be unaware of handlers calling your @WithStateMachine methods.

Every annotation is supporting exactly same set of possible method parameters but runtime behaviour is different depending on an annotation itself and a stage where annotated method is called. To better understand how context works see Chapter 19, Using StateContext.

	Note
	For differences between method parameters, see individual annotation docs below.

Effectively all annotated methods are called using Spring SPel expressions which are build dynamically during the process. As to make this work these expressions needs to have a root object it evaluates against. This root object is a StateContext and we have also made some tweaks internally so that it is possible to access StateContext methods directly without going through the context handle.

Simplest method parameter would naturally be a StateContext itself.

@WithStateMachine
public class Bean3 {

    @OnTransition
    public void anyTransition(StateContext<String, String> stateContext) {
    }
}

Rest of the StateContext content can be accessed as shown below. Number of parameters or order of those doesn’t matter.

@WithStateMachine
public class Bean4 {

    @OnTransition
    public void anyTransition(
            @EventHeaders Map<String, Object> headers,
            ExtendedState extendedState,
            StateMachine<String, String> stateMachine,
            Message<String> message,
            Exception e) {
    }
}

Annotations for transitions are OnTransition, OnTransitionStart and OnTransitionEnd.

These annotations behave exactly same and let’s see how OnTransition is used. Within this annotation a property’s source and target can be used to qualify a transition. If source and target is left empty then any transition is matched.

@WithStateMachine
public class Bean5 {

    @OnTransition(source = "S1", target = "S2")
    public void fromS1ToS2() {
    }

    @OnTransition
    public void anyTransition() {
    }
}

Default @OnTransition annotation can’t be used with a state and event enums user have created due to java language limitations, thus string representation have to be used.

Additionally it is possible to access Event Headers and ExtendedState by adding needed arguments to a method. Method is then called automatically with these arguments.

@WithStateMachine
public class Bean6 {

    @StatesOnTransition(source = States.S1, target = States.S2)
    public void fromS1ToS2(@EventHeaders Map<String, Object> headers, ExtendedState extendedState) {
    }
}

However if you want to have a type safe annotation it is possible to create a new annotation and use @OnTransition as meta annotation. This user level annotation can make a reference to actual states and events enums and framework will try to match these in a same way.

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@OnTransition
public @interface StatesOnTransition {

    States[] source() default {};

    States[] target() default {};
}

Above we created a @StatesOnTransition annotation which defines source and target as a type safe manner.

@WithStateMachine
public class Bean7 {

    @StatesOnTransition(source = States.S1, target = States.S2)
    public void fromS1ToS2() {
    }
}

In your own bean you can then use this @StatesOnTransition as is and use type safe source and target.

Annotations for states are OnStateChanged, OnStateEntry and OnStateExit.

@WithStateMachine
public class Bean8 {

    @OnStateChanged
    public void anyStateChange() {
    }
}

In a same way that in transition annotations it’s possible to define target and source states.

@WithStateMachine
public class Bean9 {

    @OnStateChanged(source = "S1", target = "S2")
    public void stateChangeFromS1toS2() {
    }
}

For type safety a new annotation needs to be created for enums with OnStateChanged as a meta annotation.

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@OnStateChanged
public @interface StatesOnStates {

    States[] source() default {};

    States[] target() default {};
}

@WithStateMachine
public class Bean10 {

    @StatesOnStates(source = States.S1, target = States.S2)
    public void fromS1ToS2() {
    }
}

Methods for state entry and exit behave in a same way.

@WithStateMachine
public class Bean11 {

    @OnStateEntry
    public void anyStateEntry() {
    }

    @OnStateExit
    public void anyStateExit() {
    }
}

There is one event related annotation named OnEventNotAccepted. It is possible to listen only specific event by defining event property with the annotation.

@WithStateMachine
public class Bean12 {

    @OnEventNotAccepted
    public void anyEventNotAccepted() {
    }

    @OnEventNotAccepted(event = "E1")
    public void e1EventNotAccepted() {
    }
}

Annotations for state machine are OnStateMachineStart, OnStateMachineStop and OnStateMachineError.

During a state machine start and stop lifecycle methods are called.

@WithStateMachine
public class Bean13 {

    @OnStateMachineStart
    public void onStateMachineStart() {
    }

    @OnStateMachineStop
    public void onStateMachineStop() {
    }
}

In case a state machine goes into an error with exception, below annotation is called.

@WithStateMachine
public class Bean14 {

    @OnStateMachineError
    public void onStateMachineError() {
    }
}

There is one extended state related annotation named OnExtendedStateChanged. It’s also possible to listen changes only for specific key changes.

@WithStateMachine
public class Bean15 {

    @OnExtendedStateChanged
    public void anyStateChange() {
    }

    @OnExtendedStateChanged(key = "key1")
    public void key1Changed() {
    }
}