203: Finite state machine pattern

finite-state-machine/README.md

@@ -0,0 +1,25 @@
+---
+layout: pattern
+title: Finite state machine
+folder: Finite-state-machine
+permalink: /patterns/Finite-state-machine/
+categories: Behavioral
+tags:
+ - Decoupling
+---
+
+## Intent
+It represents a mathematical model of a finite number of states and their transitions and actions, 
+and is an efficient programming method within a logical unit. Make the program logic clear and easy
+to understand.
+
+
+## Applicability
+Use the Finite-state-machine pattern when
+
+* There are finite state for our model or software.
+
+
+## Credits
+
+* [State Machine Design Pattern](http://community.wvu.edu/~hhammar//rts/adv%20rts/statecharts%20patterns%20papers%20and%20%20examples/paper%20on%20state%20pattern%20B31-full.pdf)

finite-state-machine/etc/finite-state-machine.urm.puml

@@ -0,0 +1,66 @@
+@startuml
+package com.iluwatar.finite.state.machine {
+  class App {
+    + App()
+    + main(args : String[]) {static}
+  }
+  class Context {
+    - state : State
+    + Context(state : State)
+    + getState() : State
+    + request(event : Event)
+    + setState(state : State)
+  }
+  class CoolState {
+    + CoolState()
+    - Cool()
+    - Stop()
+    + handle(context : Context, event : Event)
+  }
+  enum Event {
+    + MOVING_ON_OFF {static}
+    + MOVING_RUN {static}
+    + valueOf(name : String) : Event {static}
+    + values() : Event[] {static}
+  }
+  class OffState {
+    + OffState()
+    - Start()
+    + handle(context : Context, event : Event)
+  }
+  class OnState {
+    + OnState()
+    - Cool()
+    - Stop()
+    + handle(context : Context, event : Event)
+  }
+  class RunState {
+    + RunState()
+    - cool_down()
+    + handle(context : Context, event : Event)
+    - stop()
+  }
+  class StandState {
+    + StandState()
+    + handle(context : Context, event : Event)
+    - start_running()
+    - start_walking()
+  }
+  interface State {
+    + handle(Context, Event) {abstract}
+  }
+  class WalkState {
+    + WalkState()
+    + handle(context : Context, event : Event)
+    - start_running()
+    - stop()
+  }
+}
+Context -->  "-state" State
+CoolState ..|> State 
+OffState ..|> State 
+OnState ..|> State 
+RunState ..|> State 
+StandState ..|> State 
+WalkState ..|> State 
+@enduml

finite-state-machine/pom.xml

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    The MIT License
+    Copyright © 2014-2019 Ilkka Seppälä
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>java-design-patterns</artifactId>
+        <groupId>com.iluwatar</groupId>
+        <version>1.23.0-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>finite-state-machine</artifactId>
+    <dependencies>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+</project>

finite-state-machine/src/main/java/com/iluwatar/finite/state/machine/App.java

@@ -0,0 +1,52 @@
+/*
+ * The MIT License
+ * Copyright © 2014-2019 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package com.iluwatar.finite.state.machine;
+
+/**.
+ * This model named finite state machine model, which uses finite state machine to
+ * implement one thing that pull out all the states, events and actions, and manage
+ * the complex state migration logic uniformly.
+ * <p></p>
+ * In this demo, I create a scenario that there is a game character, who has three states.
+ * States: Standing;Walking;Running
+ * And also there are two events, which means you can create requests to control it.
+ * Events: MOVING_ON;MOVING_OFF
+ * In this demo I use state pattern to implement this FSM pattern. For the meaning of every class,
+ * refer to the class's Javadoc.
+ */
+public class App {
+  /**.
+   * Launcher of this demo.
+   * @param args is default for main method.
+   */
+  public static void main(String[]args) {
+    var initState = new StandState();
+    var context = new Context(initState);
+
+    context.request(Event.MOVING_ON_OFF);
+    context.request(Event.MOVING_RUN);
+    context.request(Event.MOVING_ON_OFF);
+    context.request(Event.MOVING_ON_OFF);
+  }
+}

finite-state-machine/src/main/java/com/iluwatar/finite/state/machine/Context.java

@@ -0,0 +1,64 @@
+/*
+ * The MIT License
+ * Copyright © 2014-2019 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package com.iluwatar.finite.state.machine;
+
+/**.
+ * This class is a context for the State.
+ * It defines the State that we focus on.
+ */
+public class Context {
+  private State state;
+
+  /**.
+   * Constructor for Context.
+   * @param state is state data.
+   */
+  public Context(State state) {
+    setState(state);
+  }
+
+  /**.
+   * getter for state.
+   * @return state of this context.
+   */
+  public State getState() {
+    return state;
+  }
+
+  /**.
+   * setter for state.
+   * @param state is a state data
+   */
+  public void setState(State state) {
+    this.state = state;
+  }
+
+  /**.
+   * request method for an event, then it will call handle method.
+   * @param event is an event.
+   */
+  public void request(Event event) {
+    state.handle(this,event);
+  }
+}

finite-state-machine/src/main/java/com/iluwatar/finite/state/machine/Event.java

@@ -0,0 +1,34 @@
+/*
+ * The MIT License
+ * Copyright © 2014-2019 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package com.iluwatar.finite.state.machine;
+
+/**.
+ * This enum event is the event for the game character.
+ */
+public enum Event {
+  //Event for the game character moving or stop moving
+  MOVING_ON_OFF,
+  //Event for the game character run.
+  MOVING_RUN
+}

finite-state-machine/src/main/java/com/iluwatar/finite/state/machine/RunState.java

@@ -0,0 +1,64 @@
+/*
+ * The MIT License
+ * Copyright © 2014-2019 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package com.iluwatar.finite.state.machine;
+
+/**.
+ * A running state for the game character.
+ */
+public class RunState implements State {
+  /**.
+   * This method is a handler for event.
+   * @param context is context data.
+   * @param event is an event.
+   */
+  @Override
+  public void handle(Context context, Event event) {
+    switch (event) {
+      case MOVING_ON_OFF:
+        context.setState(new StandState());
+        stop();
+        break;
+      case MOVING_RUN:
+        context.setState(new WalkState());
+        cool_down();
+        break;
+      default:
+        break;
+    }
+  }
+
+  /**.
+   * A method which simulates Game character stop.
+   */
+  private void stop() {
+    System.out.println("Stop running! Game character is standing now!");
+  }
+
+  /**.
+   * A method which simulates Game character change from run to walk.
+   */
+  private void cool_down() {
+    System.out.println("Stop running! Game character is walking now!");
+  }
+}