Merge pull request #11 from aljoshakoecher/prepare-for-release

New release 1.2.0 bringing StateChangeObservers

Author: aljoshakoecher

README.md

@@ -133,7 +133,19 @@ You can pass in an action and the name of an active state to add this action to
 
 
 ### Getting notified on state changes
-Work in progress, coming soon
+You can create an observer that is notified whenever the state machine changes its state. To do that, you have to create your observer implementing the IStateChangeOberser interface. This interface's method is called on every state change, you can do whatever you like in this function. Here's an example for such a class:
+
+```java
+class ExampleObserver implements IStateChangeObserver {
+		
+	@Override
+	public void onStateChanged(IState newState) {
+		System.out.println("State has changed, new State is: " + newState.getClass().getSimpleName());
+	}
+};
+```
+
+To add a new observer to the state machine simply call `stateMachine.addStateChangeObserver(IStateChangeObserver observer)` passing in an instance of you observer class. In case an observer should no longer be notified on state changes, simply remove it by calling `stateMachine.removeStateChangeObserver(IStateChangeObserver observer)`.
 
 
 ## Usage
@@ -146,7 +158,7 @@ Releases can be found on the Maven Central repository. Just add this dependency
 <dependency>
 	<groupId>com.github.aljoshakoecher</groupId>
 	<artifactId>isa88-state-machine</artifactId>
-	<version>1.1.0</version>
+	<version>1.2.0</version>
 </dependency>
 ```
 

pom.xml

@@ -4,7 +4,7 @@
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>com.github.aljoshakoecher</groupId>
 	<artifactId>isa88-state-machine</artifactId>
-	<version>1.1.1</version>
+	<version>1.2.0</version>
  	<packaging>bundle</packaging>
 
 	<name>ISA 88 State Machine</name>
@@ -108,7 +108,7 @@
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-javadoc-plugin</artifactId>
-				<version>2.9.1</version>
+				<version>3.2.0</version>
 				<executions>
 					<execution>
 						<id>attach-javadocs</id>

src/main/java/statemachine/IStateChangeObserver.java

@@ -0,0 +1,15 @@
+package statemachine;
+
+import states.IState;
+
+/**
+ * Defines an Observer that can be attached to a state machine in order to get notified on state changes
+ */
+public interface IStateChangeObserver {
+
+	/**
+	 * Gets called every time the state of a state machine changes
+	 * @param newState The new state that the state machine is in.
+	 */
+	public void onStateChanged(IState newState);
+}

src/main/java/statemachine/StateMachine.java

@@ -1,12 +1,15 @@
 package statemachine;
 
+import java.util.ArrayList;
+
 import states.State;
 import states.TransitionName;
 
 public class StateMachine {
 
 	private State currentState;
 	private StateActionManager stateActionManager = new StateActionManager();
+	private ArrayList<IStateChangeObserver> stateChangeObservers = new ArrayList<>();
 
 	/**
 	 * Instantiates a new {@link StateMachine} with the a given initial state
@@ -16,9 +19,10 @@ public class StateMachine {
 	StateMachine(State initialState) {
 		this.currentState = initialState;
 	}
-	
+
 	/**
 	 * Invokes a transition on the state machine.
+	 * 
 	 * @param transitionName Name of the transition that shall be invoked.
 	 */
 	public void invokeTransition(TransitionName transitionName) {
@@ -105,7 +109,8 @@ public void stop() {
 	}
 
 	/**
-	 * Execute an abort command. Can be used to transition from all 'normal' and 'stopping'-states to Aborted. Alias for invokeTransition(TransitionName.abort).
+	 * Execute an abort command. Can be used to transition from all 'normal' and 'stopping'-states to Aborted. Alias for
+	 * invokeTransition(TransitionName.abort).
 	 */
 	public void abort() {
 		this.currentState.abort(this);
@@ -144,6 +149,10 @@ protected void setState(State state) {
 	public void setStateAndRunAction(State state) {
 		this.currentState = state;
 
+		for (IStateChangeObserver observer : stateChangeObservers) {
+			observer.onStateChanged(state);
+		}
+
 		new Thread(() -> {
 			state.executeActionAndComplete(this);
 		}).start();
@@ -158,4 +167,22 @@ public StateActionManager getStateActionManager() {
 		return this.stateActionManager;
 	}
 
+	/**
+	 * Adds a new {@link IStateChangeObserver} instance to the list of observers.
+	 * 
+	 * @param observer The new observer to add.
+	 */
+	public void addStateChangeObserver(IStateChangeObserver observer) {
+		this.stateChangeObservers.add(observer);
+	}
+
+	/**
+	 * Removes a given {@link IStateChangeObserver} instance from the list of observers.
+	 * 
+	 * @param observer The observer that is going to be removed.
+	 */
+	public void removeStateChangeObserver(IStateChangeObserver observer) {
+		this.stateChangeObservers.remove(observer);
+	}
+
 }

src/test/java/observer/TestObserving.java

@@ -0,0 +1,107 @@
+package observer;
+
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Order;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestMethodOrder;
+import org.junit.jupiter.api.MethodOrderer.OrderAnnotation;
+
+import statemachine.IStateChangeObserver;
+import statemachine.StateMachine;
+import statemachine.StateMachineBuilder;
+import states.IState;
+import states.IStateAction;
+
+@TestMethodOrder(OrderAnnotation.class)
+class TestObserving {
+	
+	static class ExampleObserver implements IStateChangeObserver {
+		public String observedStateName;
+		@Override
+		public void onStateChanged(IState newState) {
+			observedStateName = newState.getClass().getSimpleName();
+		}
+	};
+	
+	private final static int dummyActionTime = 300;
+	private static IStateAction dummyAction;
+	private static StateMachine stateMachine;
+	private static ExampleObserver firstObserver;
+	private static ExampleObserver secondObserver;
+
+	@BeforeAll
+	static void setUp() {
+		firstObserver = new ExampleObserver();
+		secondObserver = new ExampleObserver();
+//		ExampleObserver secondObserver = new ExampleObserver();
+		// Create a dummy action that just pauses the thread
+		dummyAction = new IStateAction() {
+			@Override
+			public void execute() {
+				try {
+					Thread.sleep(dummyActionTime);
+				} catch (InterruptedException e) {
+					e.printStackTrace();
+				}
+			}
+		};
+		
+		StateMachineBuilder builder = new StateMachineBuilder();
+		stateMachine = builder.withActionInAborting(dummyAction).withActionInClearing(dummyAction).withActionInCompleting(dummyAction)
+				.withActionInExecute(dummyAction).withActionInHolding(dummyAction).withActionInResetting(dummyAction).withActionInStarting(dummyAction)
+				.withActionInStopping(dummyAction).withActionInSuspending(dummyAction).withActionInUnholding(dummyAction).withActionInUnsuspending(dummyAction)
+				.build();
+
+	}
+	
+	@Test
+	@Order(1)
+	void addFirstObserverAndTestStart() {
+		stateMachine.addStateChangeObserver(firstObserver);
+		stateMachine.start();
+		assertEquals(firstObserver.observedStateName, "StartingState", "Observer should be notified that the state machine is now in Starting");
+	}
+	
+	@Test
+	@Order(2)
+	void testResetWithFirstObserver() throws InterruptedException {
+		Thread.sleep(dummyActionTime*4);		// Wait for execution of starting, execute, completing + safetyTime 
+		stateMachine.reset();
+		Thread.sleep(dummyActionTime*2);		// Wait for execution of resetting + safetyTime
+		assertEquals(firstObserver.observedStateName, "IdleState", "Observer should be notified that the state machine is now in Idle");
+	}
+	
+	
+	@Test
+	@Order(3)
+	void addSecondObserverAndTestStart() {
+		stateMachine.addStateChangeObserver(secondObserver);
+		stateMachine.start();
+		assertEquals(secondObserver.observedStateName, "StartingState", "Second observer should be notified that the state machine is now in Starting");
+	}
+	
+	@Test
+	@Order(4)
+	void makeSureFirstObserverStillWorking() throws InterruptedException {
+		Thread.sleep(dummyActionTime*4);		// Wait for execution of starting, execute, completing + safetyTime
+		assertEquals(firstObserver.observedStateName, "CompleteState", "First observer should have tracked changes and should now be in CompleteState");
+	}
+	
+	@Test
+	@Order(5)
+	void removeSecondObserverAndMakeSureFirstObserverStillWorking() throws InterruptedException {
+		stateMachine.removeStateChangeObserver(secondObserver);
+		stateMachine.reset();
+		Thread.sleep(dummyActionTime*2);		// Wait for execution of resetting + safetyTime
+		assertEquals(firstObserver.observedStateName, "IdleState", "First observer should now be in IdleState");
+	}
+	
+	@Test
+	@Order(6)
+	void testSecondOberserverNoLongerNotified() throws InterruptedException {
+		assertEquals(secondObserver.observedStateName, "CompleteState", "Second observer should not have been notified after removal and should still be in CompleteState");
+	}
+}