Update network state transition documentation

Signed-off-by: Chris Jackson <chris@cd-jackson.com>

com.zsmartsystems.zigbee/src/main/java/com/zsmartsystems/zigbee/ZigBeeNetworkManager.java

@@ -83,18 +83,29 @@
  * <h2>Lifecycle</h2>
  * The ZigBeeNetworkManager lifecycle is as follows -:
  * <ul>
- * <li>Instantiate a {@link ZigBeeTransportTransmit} class
+ * <li>Instantiate a {@link ZigBeeTransportTransmit} class. The network state will be initialised to
+ * {@link ZigBeeNetworkState#UNINITIALISED}.
  * <li>Instantiate a {@link ZigBeeNetworkManager} class passing the previously created {@link ZigBeeTransportTransmit}
- * class
- * <li>Optionally set the {@link ZigBeeSerializer} and {@link ZigBeeDeserializer} using the {@link #setSerializer}
- * method
- * <li>Call the {@link #initialize} method to perform the initial initialization of the ZigBee network
+ * class.
+ * <li>Set the {@link ZigBeeSerializer} and {@link ZigBeeDeserializer} using the {@link #} method.
+ * <li>Optionally call the {@link #setNetworkDataStore(ZigBeeNetworkDataStore)} method to set the
+ * {@link ZigBeeNetworkDataStore} that will be called to serialise network data to a persistent store.
+ * <li>Call the {@link #initialize()} method to perform the initial initialization of the ZigBee network. The network
+ * state will be set to {@link ZigBeeNetworkState#INITIALISING}.
  * <li>Set the network configuration (see below).
- * <li>Call the {@link #startup} method to start using the configured ZigBee network. Configuration methods may not be
- * used.
- * <li>Call the {@link shutdown} method to close the network
+ * <li>Call the {@link #startup(boolean)} method to start using the configured ZigBee network. Configuration methods may
+ * not be used following this call. The network state will be updated to {@link ZigBeeNetworkState#ONLINE} on success,
+ * or {@link ZigBeeNetworkState#OFFLINE} on failure.
+ * <li>Call the {@link #reinitialize()} method to reinitialise the network. This will take the transport
+ * {@link ZigBeeTransportState#OFFLINE} and place the network state in {@link ZigBeeNetworkState#INITIALISING}.
+ * <li>Call the {@link shutdown()} method to close the network and free all resources. The network will be placed in
+ * {@link ZigBeeNetworkState#SHUTDOWN} and may not be restarted.
  * </ul>
  * <p>
+ * See the {@link ZigBeeNetworkState} transition diagram below -:
+ * <p>
+ * <img src="./doc-files/ZigBeeNetworkStateTransitions.png" width="50%">
+ * <p>
  * Following a call to {@link #initialize} configuration calls can be made to configure the transport layer. This
  * includes -:
  * <ul>
@@ -110,7 +121,11 @@
  * <li>{@link #setZigBeeLinkKey(ZigBeeKey)}
  * </ul>
  * <p>
- * Once all transport initialization is complete, {@link #startup} must be called.
+ * Once all transport initialization is complete, {@link #startup()} must be called to bring the network
+ * {@link ZigBeeNetworkState#ONLINE}.
+ * <p>
+ * To shutdown the network and free all resources, call {@link #shutdown()}. The network may not be restarted and a new
+ * {@link ZigBeeNetworkManager} must be instantiated. The network state will be {@link ZigBeeNetworkState#SHUTDOWN}.
  *
  * @author Chris Jackson
  */
@@ -477,7 +492,7 @@ public ZigBeeStatus setZigBeeInstallKey(final ZigBeeKey key) {
     }
 
     /**
-     * Starts up ZigBee manager components.
+     * Starts up ZigBee manager components, and starts the transport layer to bring the network ONLINE.
      *
      * @param reinitialize true if the provider is to reinitialise the network with the parameters configured since the
      *            {@link #initialize} method was called.
@@ -497,10 +512,32 @@ public ZigBeeStatus startup(boolean reinitialize) {
         return ZigBeeStatus.SUCCESS;
     }
 
+    /**
+     * Reinitialises the network. This may take the transport layer OFFLINE, and will return the
+     * {@link ZigBeeNetworkState} to {@link ZigBeeNetworkState#INITIALISING}. Following this call, the system should be
+     * in the same state as if the {@link #initialize()} method had first been called. {@link #startup(boolean)} must be
+     * called to place the network back ONLINE.
+     * <p>
+     * Note that while this method will take the {@link ZigBeeTransportState} to {@link ZigBeeTransportState#OFFLINE}
+     * the {@link ZigBeeNetworkState} will be {@link ZigBeeNetworkState#INITIALISING} - the
+     * {@link ZigBeeTransportState#OFFLINE} will not be reflected through the the application.
+     *
+     * @return
+     */
+    public ZigBeeStatus reinitialize() {
+        // Set the state to INITIALISING before reconfiguring the transport layer
+        // to ensure we don't pass the OFFLINE state to the application
+        setNetworkState(ZigBeeNetworkState.INITIALISING);
+
+        return ZigBeeStatus.SUCCESS;
+    }
+
     /**
      * Shuts down ZigBee manager components.
      */
     public void shutdown() {
+        networkState = ZigBeeNetworkState.SHUTDOWN;
+
         executorService.shutdownNow();
 
         synchronized (this) {

com.zsmartsystems.zigbee/src/main/java/com/zsmartsystems/zigbee/ZigBeeNetworkState.java

@@ -8,7 +8,9 @@
 package com.zsmartsystems.zigbee;
 
 /**
- * An enumeration of possible network states
+ * An enumeration of possible network states.
+ * <p>
+ * <img src="./doc-files/ZigBeeNetworkStateTransitions.png" width="50%">
  *
  * @author Chris Jackson
  *
@@ -29,5 +31,9 @@ public enum ZigBeeNetworkState {
     /**
      * Network is offline and not able to be used
      */
-    OFFLINE
+    OFFLINE,
+    /**
+     * The network has been closed and may not be restarted
+     */
+    SHUTDOWN
 }

com.zsmartsystems.zigbee/src/test/java/com/zsmartsystems/zigbee/ZigBeeNetworkManagerTest.java

@@ -640,8 +640,11 @@ public void initialize() throws Exception {
         TestUtilities.setField(ZigBeeNetworkManager.class, manager, "networkState", ZigBeeNetworkState.INITIALISING);
         assertEquals(ZigBeeStatus.INVALID_STATE, manager.initialize());
 
+        assertEquals(ZigBeeNetworkState.INITIALISING, manager.getNetworkState());
+
         manager.shutdown();
         Mockito.verify(mockedTransport, Mockito.timeout(TIMEOUT).times(1)).shutdown();
+        assertEquals(ZigBeeNetworkState.SHUTDOWN, manager.getNetworkState());
     }
 
     @Test
@@ -673,6 +676,12 @@ public void startup() throws Exception {
         manager.setTransportState(ZigBeeTransportState.OFFLINE);
         Awaitility.await().until(() -> stateListenerUpdated());
         assertEquals(ZigBeeNetworkState.OFFLINE, manager.getNetworkState());
+
+        TestUtilities.setField(ZigBeeNetworkManager.class, manager, "networkState", ZigBeeNetworkState.ONLINE);
+        assertEquals(ZigBeeNetworkState.ONLINE, manager.getNetworkState());
+        assertEquals(ZigBeeStatus.SUCCESS, manager.reinitialize());
+        Awaitility.await().until(() -> stateListenerUpdated());
+        assertEquals(ZigBeeNetworkState.INITIALISING, manager.getNetworkState());
     }
 
     @Test
@@ -684,7 +693,6 @@ public void getTransportVersionString() throws Exception {
         Mockito.when(mockedTransport.getVersionString()).thenReturn("Version!");
 
         assertEquals("Version!", manager.getTransportVersionString());
-
     }
 
     @Test