From 47d56d6845e515522d780d1e155cbe6eeaab23ae Mon Sep 17 00:00:00 2001 From: Robert von Burg Date: Fri, 16 Sep 2016 13:32:51 +0200 Subject: [PATCH] [Project] Extended documentation with observer and versioning --- .../www.strolch.li/documentation.html | 5 +- .../documentation_observers.html | 149 ++++++++++++++++++ .../documentation_versioning.html | 146 +++++++++++++++++ 3 files changed, 298 insertions(+), 2 deletions(-) create mode 100644 li.strolch.website/www.strolch.li/documentation_observers.html create mode 100644 li.strolch.website/www.strolch.li/documentation_versioning.html diff --git a/li.strolch.website/www.strolch.li/documentation.html b/li.strolch.website/www.strolch.li/documentation.html index ea06900c5..434d82943 100644 --- a/li.strolch.website/www.strolch.li/documentation.html +++ b/li.strolch.website/www.strolch.li/documentation.html @@ -64,10 +64,11 @@
  • Strolch Queries
  • Strolch Transactions
  • Strolch Policies
    • - diff --git a/li.strolch.website/www.strolch.li/documentation_observers.html b/li.strolch.website/www.strolch.li/documentation_observers.html new file mode 100644 index 000000000..645fc89d6 --- /dev/null +++ b/li.strolch.website/www.strolch.li/documentation_observers.html @@ -0,0 +1,149 @@ + + + + + + + + + + + + Strolch: Observers + + + + + + + + + + + + +
    + +
    +

    Documentation: Observers

    + +

    This page discusses the Strolch Observers

    +
    + +
    + +

    All changes done in a Strolch transaction are recorded and then propagated to any registered observers.

    + +

    The observer feature is opt-in and is configured for each realm. In the StrolchConfiguration.xml + file enable observers by adding the enableObserverUpdates propery per realm:

    + 
    +<StrolchConfiguration>
+  <env id="dev">
+    ...
+    <Component>
+      <name>RealmHandler</name>
+      <api>li.strolch.agent.api.RealmHandler</api>
+      <impl>li.strolch.agent.impl.DefaultRealmHandler</impl>
+      <depends>PrivilegeHandler</depends>
+      <Properties>
+        <realms>defaultRealm, otherRealm</realms>
+        <enableObserverUpdates>true</enableObserverUpdates>
+        <dataStoreMode>TRANSIENT</dataStoreMode>
+        <dataStoreFile>StrolchModel.xml</dataStoreFile>
+        <enableObserverUpdates.otherRealm>true</enableObserverUpdates.otherRealm>
+        <dataStoreMode.otherRealm>TRANSIENT</dataStoreMode.otherRealm>
+        <dataStoreFile.otherRealm>StrolchModel.xml</dataStoreFile.otherRealm>
+      </Properties>
+    </Component>
+  </env>
+  ...
+</StrolchConfiguration>
    + +
    +

    Registering for updates is done by registering an Observer on the ObserverHandler + of the realm itself:

    + 
    +ObserverHandler observerHandler = container.getRealm(StrolchConstants.DEFAULT_REALM).getObserverHandler();
+observerHandler.registerObserver(Tags.RESOURCE, new Observer() {
+
+  @Override
+  public void update(String key, List<StrolchRootElement> elements) {
+    logger.info(elements.size() + " resources were updated!");
+  }
+
+  @Override
+  public void remove(String key, List<StrolchRootElement> elements) {
+    logger.info(elements.size() + " resources were removed!");
+  }
+
+  @Override
+  public void add(String key, List<StrolchRootElement> elements) {
+    logger.info(elements.size() + " resources were added!");
+  }
+});
    + +
    +

    Observer updates can be suppressed on the transaction by calling tx.setSuppressUpdates()

    + + + + +
    + + + + +
    + + + + + + + + + + + + + + diff --git a/li.strolch.website/www.strolch.li/documentation_versioning.html b/li.strolch.website/www.strolch.li/documentation_versioning.html new file mode 100644 index 000000000..35078005a --- /dev/null +++ b/li.strolch.website/www.strolch.li/documentation_versioning.html @@ -0,0 +1,146 @@ + + + + + + + + + + + + Strolch: Versioning + + + + + + + + + + + + +
    + +
    +

    Documentation: Versioning

    + +

    This page discusses the Strolch Versioning

    +
    + +
    + +

    One of Strolch's features that sets it apart from other frameworks, is that versioning is baked into + Strolch's fabric. The feature is opt-in, as it is not required in all projects, but it only needs enabling, + for all modifications to objects to be versioned, so that rollbacks can be done when needed.

    + +

    The feature is enabled for each realm. In the StrolchConfiguration.xml file enable it by adding + the enableVersioning propery per realm:

    + 
    +<StrolchConfiguration>
+  <env id="dev">
+    ...
+    <Component>
+      <name>RealmHandler</name>
+      <api>li.strolch.agent.api.RealmHandler</api>
+      <impl>li.strolch.agent.impl.DefaultRealmHandler</impl>
+      <depends>PrivilegeHandler</depends>
+      <Properties>
+        <realms>defaultRealm, otherRealm</realms>
+        <enableVersioning>true</enableVersioning>
+        <dataStoreMode>TRANSIENT</dataStoreMode>
+        <dataStoreFile>StrolchModel.xml</dataStoreFile>
+        <enableVersioning.otherRealm>true</enableVersioning.otherRealm>
+        <dataStoreMode.otherRealm>TRANSIENT</dataStoreMode.otherRealm>
+        <dataStoreFile.otherRealm>StrolchModel.xml</dataStoreFile.otherRealm>
+      </Properties>
+    </Component>
+  </env>
+  ...
+</StrolchConfiguration>
    + +
    +

    Once versioning is enabled, versioning is handled automatically. The API for versioning is implemented on the + ElementMaps.

    + +

    Example: Revert to previous version of a Resource:

    + 
    +Resource res = tx.getResourceBy("TestType", "MyTestResource");
+ResourceMap resourceMap = tx.getResourceMap();
+Resource previousVersion = resourceMap.revertToVersion(tx, res);
+// or
+Resource previousVersion = resourceMap.revertToVersion(tx, "TestType", "MyTestResource", 1);
    + +

    Example: Retrieve all versions of a Resource:

    + 
    +List<Resource> versions = resourceMap.getVersionsFor(tx, "TestType", "MyTestResource");
    + +
    +

    Note: When reverting to a previous version, it is important to remember, that any references on an + element to other elements will also be restored. As long as the relationship is to the same element, then + this is not an issue, but should the relationship have changed, then it this must be handled and the user + performing a revert be allowed to decided which element to reference in the reverted version.

    + + + +
    + + + + +
    + + + + + + + + + + + + + +