Apply updates alternative (#135)

* Rename "serialize" and "deserialize" functions to "read" and "update" to reflect API in StatefulService
* Move new definitions to StatefulService.h so it is obvious it is not general purpose
* Update README

Author: rjwats

README.md

@@ -350,7 +350,9 @@ The following diagram visualises how the framework's modular components fit toge
 
 #### Stateful service
 
-The [StatefulService.h](lib/framework/StatefulService.h) class is a responsible for managing state and interfacing with code which wants to change or respond to changes in that state. You can define a data class to hold some state, then build a StatefulService class to manage its state:
+The [StatefulService.h](lib/framework/StatefulService.h) class is responsible for managing state. It has an API which allows other code to update or respond to updates in the state it manages. You can define a data class to hold state, then build a StatefulService class to manage it. After that you may attach HTTP endpoints, WebSockets or MQTT topics to the StatefulService instance to provide commonly required features.
+
+Here is a simple example of a state class and a StatefulService to manage it:
 
 ```cpp
 class LightState {
@@ -369,15 +371,16 @@ You may listen for changes to state by registering an update handler callback. I
 // register an update handler
 update_handler_id_t myUpdateHandler = lightStateService.addUpdateHandler(
   [&](const String& originId) {
-    Serial.println("The light's state has been updated"); 
+    Serial.print("The light's state has been updated by: "); 
+    Serial.println(originId); 
   }
 );
 
 // remove the update handler
 lightStateService.removeUpdateHandler(myUpdateHandler);
 ```
 
-An "originId" is passed to the update handler which may be used to identify the origin of the update. The default origin values the framework provides are:
+An "originId" is passed to the update handler which may be used to identify the origin of an update. The default origin values the framework provides are:
 
 Origin                | Description
 --------------------- | -----------
@@ -393,17 +396,35 @@ lightStateService.read([&](LightState& state) {
 });
 ```
 
-StatefulService also exposes an update function which allows the caller to update the state with a callback. This approach automatically calls the registered update handlers when complete. The example below turns on the lights using the arbitrary origin "timer":
+StatefulService also exposes an update function which allows the caller to update the state with a callback. This function automatically calls the registered update handlers if the state has been changed. The example below changes the state of the light (turns it on) using the arbitrary origin "timer" and returns the "CHANGED" state update result, indicating that a change was made:
 
 ```cpp
 lightStateService.update([&](LightState& state) {
-  state.on = true;  // turn on the lights!
+   if (state.on) {
+    return StateUpdateResult::UNCHANGED; // lights were already on, return UNCHANGED
+  }
+  state.on = true;  // turn on the lights
+  return StateUpdateResult::CHANGED; // notify StatefulService by returning CHANGED
 }, "timer");
 ```
 
+There are three possible return values for an update function which are as follows:
+
+Origin                        | Description
+----------------------------- | ---------------------------------------------------------------------------
+StateUpdateResult::CHANGED    | The update changed the state, propagation should take place if required
+StateUpdateResult::UNCHANGED  | The state was unchanged, propagation should not take place
+StateUpdateResult::ERROR      | There was an error updating the state, propagation should not take place
+
 #### Serialization
 
-When transmitting state over HTTP, WebSockets, or MQTT it must to be marshalled into a serializable form (JSON). The framework uses ArduinoJson for serialization and the functions defined in [JsonSerializer.h](lib/framework/JsonSerializer.h) and [JsonDeserializer.h](lib/framework/JsonDeserializer.h) facilitate this.
+When reading or updating state from an external source (HTTP, WebSockets, or MQTT for example) the state must be marshalled into a serializable form (JSON). SettingsService provides two callback patterns which facilitate this internally:
+
+Callback         | Signature                                                | Purpose
+---------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------
+JsonStateReader  | void read(T& settings, JsonObject& root)                 | Reading the state object into a JsonObject
+JsonStateUpdater | StateUpdateResult update(JsonObject& root, T& settings)  | Updating the state from a JsonObject, returning the appropriate StateUpdateResult
+
 
 The static functions below can be used to facilitate the serialization/deserialization of the light state:
 
@@ -413,32 +434,33 @@ class LightState {
   bool on = false;
   uint8_t brightness = 255;
 
-  static void serialize(LightState& state, JsonObject& root) {
+  static void read(LightState& state, JsonObject& root) {
     root["on"] = state.on;
     root["brightness"] = state.brightness;
   }
 
-  static void deserialize(JsonObject& root, LightState& state) {
+  static StateUpdateResult update(JsonObject& root, LightState& state) {
     state.on = root["on"] | false;
     state.brightness = root["brightness"] | 255;
+    return StateUpdateResult::CHANGED;
   }
 };
 ```
 
 For convenience, the StatefulService class provides overloads of its `update` and `read` functions which utilize these functions.
 
-Copy the state to a JsonObject using a serializer:
+Read the state to a JsonObject using a serializer:
 
 ```cpp
 JsonObject jsonObject = jsonDocument.to<JsonObject>();
-lightStateService->read(jsonObject, serializer);
+lightStateService->read(jsonObject, LightState::read);
 ```
 
 Update the state from a JsonObject using a deserializer:
 
 ```cpp
 JsonObject jsonObject = jsonDocument.as<JsonObject>();
-lightStateService->update(jsonObject, deserializer, "timer");
+lightStateService->update(jsonObject, LightState::update, "timer");
 ```
 
 #### Endpoints
@@ -451,7 +473,7 @@ The code below demonstrates how to extend the LightStateService class to provide
 class LightStateService : public StatefulService<LightState> {
  public:
   LightStateService(AsyncWebServer* server) :
-      _httpEndpoint(LightState::serialize, LightState::deserialize, this, server, "/rest/lightState") {
+      _httpEndpoint(LightState::read, LightState::update, this, server, "/rest/lightState") {
   }
 
  private:
@@ -471,7 +493,7 @@ The code below demonstrates how to extend the LightStateService class to provide
 class LightStateService : public StatefulService<LightState> {
  public:
   LightStateService(FS* fs) :
-      _fsPersistence(LightState::serialize, LightState::deserialize, this, fs, "/config/lightState.json") {
+      _fsPersistence(LightState::read, LightState::update, this, fs, "/config/lightState.json") {
   }
 
  private:
@@ -489,7 +511,7 @@ The code below demonstrates how to extend the LightStateService class to provide
 class LightStateService : public StatefulService<LightState> {
  public:
   LightStateService(AsyncWebServer* server) :
-      _webSocket(LightState::serialize, LightState::deserialize, this, server, "/ws/lightState"), {
+      _webSocket(LightState::read, LightState::update, this, server, "/ws/lightState"), {
   }
 
  private:
@@ -508,15 +530,16 @@ The framework includes an MQTT client which can be configured via the UI. MQTT r
 The code below demonstrates how to extend the LightStateService class to interface with MQTT:
 
 ```cpp
+
 class LightStateService : public StatefulService<LightState> {
  public:
   LightStateService(AsyncMqttClient* mqttClient) :
-    _mqttPubSub(LightState::serialize, 
-                    LightState::deserialize,
-                    this,
-                    mqttClient,
-                    "homeassistant/light/my_light/set",
-                    "homeassistant/light/my_light/state") {
+      _mqttPubSub(LightState::read,
+                  LightState::update,
+                  this,
+                  mqttClient,
+                  "homeassistant/light/my_light/set",
+                  "homeassistant/light/my_light/state") {
   }
 
  private:

lib/framework/APSettingsService.cpp

@@ -1,13 +1,8 @@
 #include <APSettingsService.h>
 
 APSettingsService::APSettingsService(AsyncWebServer* server, FS* fs, SecurityManager* securityManager) :
-    _httpEndpoint(APSettings::serialize,
-                  APSettings::deserialize,
-                  this,
-                  server,
-                  AP_SETTINGS_SERVICE_PATH,
-                  securityManager),
-    _fsPersistence(APSettings::serialize, APSettings::deserialize, this, fs, AP_SETTINGS_FILE),
+    _httpEndpoint(APSettings::read, APSettings::update, this, server, AP_SETTINGS_SERVICE_PATH, securityManager),
+    _fsPersistence(APSettings::read, APSettings::update, this, fs, AP_SETTINGS_FILE),
     _dnsServer(nullptr),
     _lastManaged(0) {
   addUpdateHandler([&](const String& originId) { reconfigureAP(); }, false);

lib/framework/APSettingsService.h

@@ -36,13 +36,13 @@ class APSettings {
   String ssid;
   String password;
 
-  static void serialize(APSettings& settings, JsonObject& root) {
+  static void read(APSettings& settings, JsonObject& root) {
     root["provision_mode"] = settings.provisionMode;
     root["ssid"] = settings.ssid;
     root["password"] = settings.password;
   }
 
-  static void deserialize(JsonObject& root, APSettings& settings) {
+  static StateUpdateResult update(JsonObject& root, APSettings& settings) {
     settings.provisionMode = root["provision_mode"] | FACTORY_AP_PROVISION_MODE;
     switch (settings.provisionMode) {
       case AP_MODE_ALWAYS:
@@ -54,6 +54,7 @@ class APSettings {
     }
     settings.ssid = root["ssid"] | FACTORY_AP_SSID;
     settings.password = root["password"] | FACTORY_AP_PASSWORD;
+    return StateUpdateResult::CHANGED;
   }
 };
 

lib/framework/FSPersistence.h

@@ -2,21 +2,19 @@
 #define FSPersistence_h
 
 #include <StatefulService.h>
-#include <JsonSerializer.h>
-#include <JsonDeserializer.h>
 #include <FS.h>
 
 template <class T>
 class FSPersistence {
  public:
-  FSPersistence(JsonSerializer<T> jsonSerializer,
-                JsonDeserializer<T> jsonDeserializer,
+  FSPersistence(JsonStateReader<T> stateReader,
+                JsonStateUpdater<T> stateUpdater,
                 StatefulService<T>* statefulService,
                 FS* fs,
                 char const* filePath,
                 size_t bufferSize = DEFAULT_BUFFER_SIZE) :
-      _jsonSerializer(jsonSerializer),
-      _jsonDeserializer(jsonDeserializer),
+      _stateReader(stateReader),
+      _stateUpdater(stateUpdater),
       _statefulService(statefulService),
       _fs(fs),
       _filePath(filePath),
@@ -33,7 +31,7 @@ class FSPersistence {
       DeserializationError error = deserializeJson(jsonDocument, settingsFile);
       if (error == DeserializationError::Ok && jsonDocument.is<JsonObject>()) {
         JsonObject jsonObject = jsonDocument.as<JsonObject>();
-        _statefulService->updateWithoutPropagation(jsonObject, _jsonDeserializer);
+        _statefulService->updateWithoutPropagation(jsonObject, _stateUpdater);
         settingsFile.close();
         return;
       }
@@ -49,7 +47,7 @@ class FSPersistence {
     // create and populate a new json object
     DynamicJsonDocument jsonDocument = DynamicJsonDocument(_bufferSize);
     JsonObject jsonObject = jsonDocument.to<JsonObject>();
-    _statefulService->read(jsonObject, _jsonSerializer);
+    _statefulService->read(jsonObject, _stateReader);
 
     // serialize it to filesystem
     File settingsFile = _fs->open(_filePath, "w");
@@ -79,21 +77,21 @@ class FSPersistence {
   }
 
  private:
-  JsonSerializer<T> _jsonSerializer;
-  JsonDeserializer<T> _jsonDeserializer;
+  JsonStateReader<T> _stateReader;
+  JsonStateUpdater<T> _stateUpdater;
   StatefulService<T>* _statefulService;
-  FS* _fs;  
+  FS* _fs;
   char const* _filePath;
   size_t _bufferSize;
   update_handler_id_t _updateHandlerId;
 
  protected:
-  // We assume the deserializer supplies sensible defaults if an empty object
+  // We assume the updater supplies sensible defaults if an empty object
   // is supplied, this virtual function allows that to be changed.
   virtual void applyDefaults() {
     DynamicJsonDocument jsonDocument = DynamicJsonDocument(_bufferSize);
     JsonObject jsonObject = jsonDocument.as<JsonObject>();
-    _statefulService->updateWithoutPropagation(jsonObject, _jsonDeserializer);
+    _statefulService->updateWithoutPropagation(jsonObject, _stateUpdater);
   }
 };