{"id":55965,"date":"2022-12-09T10:20:08","date_gmt":"2022-12-09T04:50:08","guid":{"rendered":"https:\/\/www.tothenew.com\/blog\/?p=55965"},"modified":"2022-12-09T10:20:08","modified_gmt":"2022-12-09T04:50:08","slug":"spring-state-machine","status":"publish","type":"post","link":"https:\/\/www.tothenew.com\/blog\/spring-state-machine\/","title":{"rendered":"Spring State Machine"},"content":{"rendered":"

State Machine Overview<\/strong><\/h2>\n

Spring state machine is a spring-module that allows us to describe well known, well understood transitions from one state to another. You have probably built a million state machines in your life if you have ever done any kind of programming. For example any kind of if-then-else statement at some point will constitute a state machine. So, any transition which is predictable, or deterministic from one state to another which may have actions associated with it is a state machine and is a very fundamental part of what we do.<\/p>\n

But things can go ugly with these if-else statements, if state transitions just become a little complex where a developer will get lost in the nested structure of if-else statements instead of solving a business problem. And to make life worse, if workflow has changes, the developer needs to scour different layers of the codebase where all complex decisions reside.<\/p>\n

State machines are a nice way to think about the progressions of our applications, how things should happen, and how they should move. Modelling your business project in terms of the state machine is useful even if you don\u2019t plan to. State machines describe state over a long running process, so if you have a long-running process with lots of moving parts, the state machine comes into picture.<\/p>\n

State machine has the benefit of being queryable. You can interrogate where we are in the fulfilment flow. For example, I am fulfilling an order and we have a number of steps involved from tons of actors. Being able to poke at the state machine to check where we are and where we will proceed after the actor performs any deterministic action.<\/p>\n

We will be building the State machine using the spring state machine project.<\/strong><\/p>\n

\u00a0\"\"<\/p>\n

Step 1<\/strong><\/h2>\n

We will be building a gradle project with the following build.gradle.<\/p>\n

 plugins {\r\n id 'java'<\/span>\r\n id 'org.springframework.boot'<\/span> version '3.0.0'<\/span>\r\n id 'io.spring.dependency-management'<\/span> version '1.1.0'<\/span>\r\n }\r\n\r\n group = 'com.ttn'<\/span>\r\n version = '0.0.1-SNAPSHOT'<\/span>\r\n sourceCompatibility = '17'<\/span>\r\n\r\n configurations {\r\n compileOnly {\r\n extendsFrom annotationProcessor\r\n }\r\n }\r\n\r\n repositories {\r\n   mavenCentral()\r\n }\r\n\r\n dependencies {\r\n   implementation 'org.springframework.boot:spring-boot-starter-data-jpa'<\/span>\r\n   implementation 'org.springframework.boot:spring-boot-starter-web'<\/span>\r\n   compileOnly 'org.projectlombok:lombok'<\/span>\r\n   runtimeOnly 'com.mysql:mysql-connector-j'<\/span>\r\n   annotationProcessor 'org.projectlombok:lombok'<\/span>\r\n   testImplementation 'org.springframework.boot:spring-boot-starter-test'<\/span>\r\n   implementation group: 'org.springframework.statemachine'<\/span>, name: 'spring-statemachine-core'<\/span>, version: '3.2.0'<\/span>\r\n   }<\/pre>\n
Step 2<\/strong><\/h2>\n
Let\u2019s define the states of Order<\/p>\n
public<\/span> enum<\/span> OrderStates<\/span> {\r\n   SUBMITTED, PAID, FULFILLED, CANCELED\r\n}<\/span><\/pre>\n
Step 3<\/strong><\/h2>\n
Let\u2019s create some Events<\/p>\n
public<\/span> enum<\/span> OrderEvents<\/span> {\r\n   PAY, FULFILL, CANCEL;\r\n}<\/span><\/pre>\n
Our state are changing like below:<\/p>\n
1. When the order is created it will be in SUBMITTED state.<\/span><\/p>\n
2. From there, if PAY event happens, state will change to PAID<\/span><\/p>\n
3. From PAID, if FULFILL event happens, state will change to FULFILLED<\/span><\/p>\n
4. FULFILLED state is the end state<\/span><\/p>\n
5. But from FULFILLED, if CANCEL event happens, state will change to CANCELED<\/span><\/p>\n
6. Also, from PAID, if CANCEL event happens, state will change to CANCELED<\/span><\/p>\n
7. CANCELED state is also the end state<\/span><\/p>\n
We need to cover the above transition. First we create a State machine with Order States.<\/p>\n
Step 4:<\/strong><\/p>\n
Configuring Spring State Machine<\/p>\n
 @Slf4j<\/span>\r\n @Configuration<\/span>\r\n @EnableStateMachineFactory<\/span>\r\n class<\/span> SimpleStateMachineConfiguration<\/span> extends<\/span> StateMachineConfigurerAdapter<\/span><OrderStates,OrderEvents> {..<\/span><\/pre>\n
We need to\u00a0override<\/strong> methods of the above\u00a0StateMachineConfigurerAdapter<\/strong>\u00a0to configure our state machine<\/p>\n
The below override method helps us define the states of the machine<\/strong><\/p>\n
 @Override<\/span>\r\n public<\/span> void<\/span> configure<\/span>(StateMachineStateConfigurer<OrderStates, OrderEvents> states)<\/span> throws<\/span> Exception {\r\n    states.withStates()\r\n            .initial(OrderStates.SUBMITTED)\r\n            .state(OrderStates.PAID)\r\n            .end(OrderStates.FULFILLED)\r\n            .end(OrderStates.CANCELLED);\r\n }<\/span><\/pre>\n
The below override method help us to define the transitions we have discussed above<\/strong><\/p>\n
 @Override<\/span>\r\n public<\/span> void<\/span> configure<\/span>(StateMachineTransitionConfigurer<OrderStates,\r\n       OrderEvents> transitions)<\/span> throws<\/span> Exception {\r\n   transitions\r\n           .withExternal()\r\n           .source(OrderStates.SUBMITTED)\r\n           .target(OrderStates.PAID)\r\n           .event(OrderEvents.PAY)\r\n           .guard(ctx -> {\r\n               log.info(\u201ctrue<\/span>->statechanged. false<\/span>->do<\/span> not change \u201d);\r\n               var<\/span> paymentType<\/span> =<\/span> String.class.cast(ctx.getExtendedState()\r\n                       .getVariables().get(\"paymentType\"<\/span>));\r\n               if<\/span> (!StringUtils.isEmpty(paymentType) && paymentType.equals(\"cod\"<\/span>))\r\n                   return<\/span> false<\/span>;\r\n               else<\/span> return<\/span> true<\/span>;\r\n           })\r\n\r\n           .and()\r\n           .withExternal()\r\n           .source(OrderStates.PAID)\r\n           .target(OrderStates.FULFILLED)\r\n           .event(OrderEvents.FULFILL)\r\n           .action(ctx -> {\r\n             log.info(\"This PAID handler where we can perform some logging\"<\/span>);\r\n           })\r\n\r\n           .and()\r\n           .withExternal()\r\n           .source(OrderStates.SUBMITTED)\r\n           .target(OrderStates.CANCELLED)\r\n           .event(OrderEvents.CANCEL)\r\n           .action(ctx -> {\r\n             log.info(\"This SUBMITTED handler where we can perform some logging\"<\/span>);\r\n           })\r\n\r\n\r\n           .and()\r\n           .withExternal()\r\n           .source(OrderStates.PAID)\r\n           .target(OrderStates.CANCELLED)\r\n           .event(OrderEvents.CANCEL)\r\n           .action(ctx -> {\r\n               log.info(\"This PAID handler where we can perform some logging\"<\/span>);\r\n           });\r\n\r\n }\r\n<\/span><\/pre>\n
Here we define first the source state, from source we define the destination state when a particular event is triggered. Along with source, target and event we have also defined\u00a0Guards<\/strong>\u00a0and\u00a0Actions<\/strong>.<\/p>\n
Here, we can see that for state\u00a0FULFILLED<\/strong>,\u00a0CANCELLED<\/strong>,\u00a0PAID<\/strong>\u00a0we have used an\u00a0Action<\/strong>\u00a0which can be used for cross cutting concerns like logging.<\/p>\n
Also, we have used\u00a0Guard<\/strong>, which can be used to make a decision whether we want to block the state from being changed. If true, the state will change, otherwise it will not.<\/p>\n
Guard<\/strong><\/p>\n
We can define a guard as a separate bean and then call it from guard directly.<\/p>\n
Guard is a functional interface and hence we have used lambda for its implementation. The implementing method needs to return true or false. True means the state will change and false means the state will not change.<\/p>\n
 @Bean<\/span>\r\n public<\/span> Guard<OrderStates, OrderEvents> guard() {\r\n   return<\/span> ctx -> return<\/span> true<\/span>;\r\n }<\/span><\/pre>\n
Action<\/strong><\/p>\n
We can define action as a separate bean and then call it directly from action. Action is a functional interface and hence we have used lambda for its implementation. It\u2019s just taking a consumer.<\/p>\n
 @Bean<\/span>\r\n public<\/span> Action<OrderStates, OrderEvents> guard<\/span>()<\/span> {\r\n   return<\/span> ctx -> log.inf(\"logging\"<\/span>);\r\n }<\/span><\/pre>\n
Step 5<\/strong><\/h2>\n
Let\u2019s create a simple\u00a0OrderInvoice<\/strong>\u00a0Entity for which we are going to change the state using our state machine.<\/p>\n
 @Entity<\/span>\r\n @Getter<\/span>\r\n @Setter<\/span>\r\n public<\/span> class<\/span> OrderInvoice<\/span> {\r\n\r\n   @Id<\/span>\r\n   @GeneratedValue<\/span>\r\n   private<\/span>  Long id;\r\n   private<\/span> LocalDate localDate;\r\n   private<\/span> String state;\r\n\r\n   @Transient<\/span>\r\n   String event;\r\n\r\n   @Transient<\/span>\r\n   String paymentType;\r\n\r\n }<\/span><\/pre>\n
 public<\/span> interface<\/span> OrderRepository<\/span> extends<\/span> JpaRepository<\/span><OrderInvoice,Long> {}<\/span><\/pre>\n
Step 6<\/strong><\/h2>\n
We will create simple controller class to first create a OrderInvoice for which state will be in\u00a0SUBMITTED<\/strong>\u00a0state<\/p>\n
 @PostMapping(\"\/createOrder\")<\/span>\r\n public<\/span> OrderInvoice createOrder<\/span>()<\/span>{\r\n   OrderInvoice<\/span> order<\/span> =<\/span> new<\/span> OrderInvoice<\/span>();\r\n   order.setState(OrderStates.SUBMITTED.name());\r\n   order.setLocalDate(LocalDate.now());\r\n   return<\/span> orderRepository.save(order);\r\n }<\/span><\/pre>\n
Step 7<\/strong><\/h2>\n
Now we need to create another handler that will use state machine to change the state of this order<\/p>\n
 @RestController<\/span>\r\n @RequiredArgsConstructor<\/span>\r\n public<\/span> class<\/span> WorkflowController<\/span> {\r\n\r\n\r\n   private<\/span> final<\/span> OrderRepository orderRepository;\r\n\r\n   private<\/span> final<\/span> StateMachineFactory<OrderStates, OrderEvents> stateMachineFactory;\r\n\r\n\r\n\r\n   @PutMapping(\"\/change\"<\/span>)<\/span>\r\n   public<\/span> String changeState(@RequestBody<\/span> OrderInvoice order){\r\n\r\n        \/\/making the machine in current state of the order<\/span>\r\n         StateMachine<OrderStates, OrderEvents> sm =    build(order);\r\n         sm.getExtendedState().getVariables().put(\"paymentType\"<\/span>,order.getPaymentType());\r\n         sm.sendEvent(\r\n                 MessageBuilder.withPayload(OrderEvents.valueOf(order.getEvent()))\r\n                         .setHeader(\"orderId\"<\/span>,order.getId())\r\n                         .setHeader(\"state\"<\/span>,order.getState())\r\n                         .build()\r\n                 );\r\n        return<\/span> \"state changed\"<\/span>;\r\n    }\r\n }\r\n<\/span><\/pre>\n
Here we can see the build(order) method which is very important. This method aims to get the state machine from state machine factory and set it to a state in which our current order is in. Usually current state is pulled from the database.<\/p>\n
Spring MessageBuilder<\/strong>\u00a0is quite useful in sending events as it allows us to attach headers which we have used to send events. In the following steps we would be defining an interceptor where we will be using the header inputs.<\/p>\n
Step 8<\/strong><\/h2>\n
(Most important step)<\/strong><\/p>\n
Pulling the state from the database and reset the machine to that state. This is the most important part and may look cumbersome at first glance.<\/p>\n
 public<\/span> StateMachine<OrderStates,OrderEvents> build<\/span>(final<\/span> OrderInvoice orderDto)<\/span>{\r\n   var<\/span> orderDb<\/span> =<\/span>  this<\/span>.orderRepository.findById(orderDto.getId());\r\n   var<\/span> stateMachine<\/span> =<\/span>  this<\/span>.stateMachineFactory.getStateMachine(orderDto.getId().toString());\r\n   stateMachine.stop();\r\n   stateMachine.getStateMachineAccessor()\r\n      .doWithAllRegions(sma -> {\r\n        sma.resetStateMachine(new<\/span> DefaultStateMachineContext<\/span><>(OrderStates.valueOf(orderDb.get().getState()), null<\/span>, null<\/span>, null<\/span>));\r\n     });\r\n    stateMachine.start();\r\n    return<\/span> stateMachine;\r\n }<\/span><\/pre>\n
As, we can see that we have pulled the state machine first from stateMachineFactory which we have injected already, then we have stopped it, then we have reset the machine to a state of OrderInvoice which we have pulled from the database.<\/p>\n
Step 9<\/strong><\/h2>\n
Once we have reset the machine to existing state with help of db, we just have to send the event which we have received in the request.<\/p>\n
But we still need to persist the order state in our db when the state machine has altered the state of the order. We may take help of some interceptors as shown below<\/p>\n
 public<\/span> StateMachine<OrderStates,OrderEvents> build<\/span>(final<\/span> OrderInvoice orderDto)<\/span>{\r\n   var<\/span> orderDb<\/span> =<\/span>  this<\/span>.orderRepository.findById(orderDto.getId());\r\n   var<\/span> stateMachine<\/span> =<\/span>  this<\/span>.stateMachineFactory.getStateMachine(orderDto.getId().toString());\r\n   stateMachine.stop();\r\n   stateMachine.getStateMachineAccessor()\r\n           .doWithAllRegions(sma -> {\r\n               sma.addStateMachineInterceptor(new<\/span> StateMachineInterceptorAdapter<\/span><>() {\r\n                   @Override<\/span>\r\n                   public<\/span> void<\/span> preStateChange<\/span>(State<OrderStates, OrderEvents> state, Message<OrderEvents> message, Transition<OrderStates, OrderEvents> transition, StateMachine<OrderStates, OrderEvents> stateMachine, StateMachine<OrderStates, OrderEvents> rootStateMachine)<\/span> {\r\n                      var<\/span> orderId<\/span> =<\/span> Long.class.cast(message.getHeaders().get(\"orderId\"<\/span>));\r\n                      var<\/span> order<\/span> =<\/span>  orderRepository.findById(orderId);\r\n                       if<\/span>(order.isPresent()){\r\n                           order.get().setState(state.getId().name());\r\n                           orderRepository.save(order.get());\r\n                       }\r\n                   }\r\n               });\r\n               sma.resetStateMachine(new<\/span> DefaultStateMachineContext<\/span><>(OrderStates.valueOf(orderDb.get().getState()), null<\/span>, null<\/span>, null<\/span>));\r\n           });\r\n\r\n    stateMachine.start();\r\n    return<\/span> stateMachine;\r\n\r\n }<\/span><\/pre>\n
Here we have added the\u00a0addStateMAchineInterceptorAdaptor<\/strong> and override preStateChange<\/strong>\u00a0method.<\/p>\n
It\u2019s time to test our application through curl commands<\/p>\n
Test Step 1:<\/strong><\/p>\n
First we simply create the order. This will persist the order in SUBMITTED state<\/p>\n
curl --location --request POST 'localhost:8080\/createOrder'<\/span> \\\r\n--data<\/span>-raw ''<\/span><\/span><\/pre>\n
Test Step 2:<\/strong><\/p>\n
We simply send an event of PAY for order id 1<\/p>\n
 curl --location --request PUT 'localhost:8080\/change' \\<\/span>\r\n --header 'Content-Type: application\/json' \\<\/span>\r\n --data-raw '{<\/span>\r\n     \"id\"<\/span>: 1<\/span>,\r\n     \"event\"<\/span>: \"PAY\"<\/span>,\r\n     \"paymentType\"<\/span> : \"cash\"<\/span>\r\n }'<\/span><\/span><\/pre>\n
The above curl will change the state to PAID as payment type is cash<\/p>\n
But if the curl is as below<\/p>\n
 curl --location --request PUT 'localhost<\/span>:8080<\/span>\/change' \\\r\n --header 'Content<\/span>-Type: application\/json' \\\r\n --data-raw '{\r\n     \"id\"<\/span>: 1<\/span>,\r\n     \"event\"<\/span>: \"PAY\"<\/span>,\r\n     \"paymentType\"<\/span> : \"cod\"<\/span>\r\n }'\r\n<\/span><\/pre>\n
Since we have a guard which will not allow to change the state if the action payment type is \u201ccod<\/strong>\u201d.<\/p>\n
This blog is originally published <\/span>here<\/a>.<\/span><\/p>\n
<\/div>","protected":false},"excerpt":{"rendered":"
State Machine Overview Spring state machine is a spring-module that allows us to describe well known, well understood transitions from one state to another. You have probably built a million state machines in your life if you have ever done any kind of programming. For example any kind of if-then-else statement at some point will […]<\/p>\n","protected":false},"author":1520,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"iawp_total_views":629},"categories":[446],"tags":[5053],"aioseo_notices":[],"_links":{"self":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts\/55965"}],"collection":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/users\/1520"}],"replies":[{"embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/comments?post=55965"}],"version-history":[{"count":5,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts\/55965\/revisions"}],"predecessor-version":[{"id":58431,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts\/55965\/revisions\/58431"}],"wp:attachment":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/media?parent=55965"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/categories?post=55965"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/tags?post=55965"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}