Merged with augmentation function feature

Author: piconem

.gitignore

@@ -206,4 +206,6 @@ gradle-app.setting
 *.hprof
 
 # End of https://www.toptal.com/developers/gitignore/api/gradle,java,intellij,macos
-.idea
+.idea
+
+.claude

README.md

@@ -54,6 +54,7 @@ that led the design and development of the WLDT library.
 - ️️⚙️ [Resources & Management Interface](docs/resources_management_interface.md): Provides the details about 
 the management interface of the WLDT library and how to use it to handle the manageable DT's resource through its life cycle.
 - 📝 [Logging in WLDT](docs/wldt_logger.md): Describes the logging system of the WLDT library, including how to configure, customize and use it.
+- 🧠 [Augmentation Functions](docs/augmentation_function.md): Provides the details about the Augmentation Functions, which are used to enhance the capabilities of the Digital Twin by adding new stateless or stateful functionalities.
 
 ---
 

docs/augmentation_function.md

@@ -0,0 +1,54 @@
+---
+config:
+  theme: neo
+---
+sequenceDiagram
+    actor Dev as Developer
+    participant AM as Augmentation Manager
+    participant AFH as Augmentation Function Handler
+    participant EB as Event Bus
+    participant DT as Digital Twin
+    participant DTM as Digital Twin Model
+    actor EAF as External Augmentation Function
+
+    %% Phase 1: Developer registers first Augmentation Function (DT not yet started)
+    Dev->>AM: getAugmentationFunctionHandler(handlerId)
+    AM-->>Dev: AugmentationFunctionHandler
+
+    Dev->>AFH: register(AugmentationFunction1)
+    AFH->>EB: publish(RegistrationEvent1)
+    Note over EB: No subscribers — event is ignored
+
+    %% Phase 2: Developer starts the Digital Twin
+    Dev->>DT: start()
+    DT->>DTM: start()
+    DTM->>EB: subscribe(RegistrationEvent, UnregistrationEvent)
+
+    DTM->>AM: getAugmentationFunctionHandlers()
+    AM-->>DTM: [AugmentationFunctionHandler]
+
+    DTM->>AFH: getRegisteredAugmentationFunctions()
+    AFH-->>DTM: [AugmentationFunction1]
+    DTM->>DTM: Internal notification new AF List registered for an Handler
+
+    %% Phase 3: Developer registers a second Augmentation Function
+    Note over Dev, EAF: Some time passes...
+
+    Dev->>AFH: register(AugmentationFunction 2)
+    AFH->>EB: publish(RegistrationEvent 2)
+    EB-->>DTM: notify(RegistrationEvent 2)
+    Note over DTM: AF 2 Registered Notified
+
+    %% Phase 4: External Augmentation Function self-registers
+    EAF->>AFH: register(self)
+    AFH->>EB: publish(RegistrationEvent 3)
+    EB-->>DTM: notify(RegistrationEvent 3)
+    Note over DTM: External AF Registered Notified
+
+    %% Phase 5: Developer unregisters the Augmentation Function
+    Note over Dev, EAF: Some time passes...
+
+    Dev->>AFH: unregister(AugmentationFunction 2)
+    AFH->>EB: publish(UnRegistrationEvent 2)
+    EB-->>DTM: notify(UnRegistrationEvent 2)
+    Note over DTM: AF 2 Unregistered Notified

docs/changelogs/v0.7.0.md

@@ -32,7 +32,7 @@ The main module of the Storage Layer is the one associated to Storage Capabiliti
         * Physical Asset Action Request storage and retrieval;
         * Physical Asset Event Notification storage and retrieval;
     * Each WldtStorage instance can be configured (using the right constructor method) to:
-        * Observe all Wldt events (`stateEvents`,  `physicalAssetEvents`,  `physicalAssetActionEvents`,  `physicalAssetDescriptionEvents`,  `digitalActionEvents`,  `lifeCycleEvents`)
+        * Observe all Wldt events (`stateEvents`,  `physicalAssetEvents`,  `physicalAssetActionEvents`,  `physicalAssetDescriptionEvents`,  `digitalActionEvents`,  `lifeCycleEvents`, `augmentationFunctionEvents`)
         * Filter only for specific class of events
         * Once the WldtStorage has been properly configured to receive target events the `StorageManager` automatically save information of interest for that specific storage. For example we can have a `StorageA` (e.g, REDIS) configured to receive all the generated events and a `StorageB` (e.g., MongoDB) in charge of saving only DT's state variation over time.
     * The default implementation of the `WldtStorage` is the class `DefaultWldtStorage`. This class provides a simple storage solution for digital twin states,  digital twin state changes, physical asset events, and digital twin events. The class provides **ONLY** a memory based  approach for storage using ArrayLists and HashMaps and more advanced solution should be implemented for production oriented Digital Twins for examples using external storage and memorization solutions.
@@ -96,6 +96,32 @@ The main module of the Storage Layer is the one associated to Storage Capabiliti
                 * `getPhysicalAssetRelationshipInstanceDeletedNotificationCount()`: Get the number of Physical Asset Relationship Instance Updated Event
                 * `getPhysicalAssetRelationshipInstanceDeletedNotificationInTimeRange(long startTimestampMs, long endTimestampMs)`: Get the Physical Asset Relationship Instance Updated Event in the specified time range
                 * `getPhysicalAssetRelationshipInstanceDeletedNotificationInRange(int startIndex, int endIndex)`: Get the Physical Asset Relationship Instance Updated Event in the specified range of indices
+        * **Augmentation Function**:
+            * Error
+                * `saveAugmentationFunctionError(String augmentationFunctionId, String augmentationFunctionHandlerId, AugmentationFunctionError augmentationFunctionError)`: Save the Augmentation Function Error
+                * `getAugmentationFunctionErrorCount()`: Get the number of errors occurred during the execution of the Augmentation Functions
+                * `getAugmentationFunctionErrorsInTimeRange(long startTimestampMs, long endTimestampMs)`: Get the errors in the specified time range
+                * `getAugmentationFunctionErrorsInRange(int startIndex, int endIndex)`: Get the errors in the specified range of indices
+            * Request
+                * `saveAugmentationFunctionRequest(String augmentationFunctionId, String augmentationFunctionHandlerId, AugmentationFunctionRequest augmentationFunctionRequest)`: Save the Augmentation Function Request
+                * `getAugmentationFunctionRequestCount()`: Get the number of Augmentation Function Requests stored
+                * `getAugmentationFunctionRequestInTimeRange(long startTimestampMs, long endTimestampMs)`: Get the requests in the specified time range
+                * `getAugmentationFunctionRequestInRange(int startIndex, int endIndex)`: Get the requests in the specified range of indices
+            * Result
+                * `saveAugmentationFunctionResult(String augmentationFunctionId, String augmentationFunctionHandlerId, AugmentationFunctionResult<?> augmentationFunctionResult)`: Save the Augmentation Function Result
+                * `getAugmentationFunctionResultCount()`: Get the number of Augmentation Function Results stored
+                * `getAugmentationFunctionResultInTimeRange(long startTimestampMs, long endTimestampMs)`: Get the results in the specified time range
+                * `getAugmentationFunctionResultInRange(int startIndex, int endIndex)`: Get the results in the specified range of indices
+            * Registration
+                * `saveAugmentationFunctionRegistration(String augmentationFunctionId, String augmentationFunctionHandlerId, AugmentationFunctionType augmentationFunctionType)`: Save the Augmentation Function Registration
+                * `getAugmentationFunctionRegistrationCount()`: Get the number of Augmentation Function Registrations stored
+                * `getAugmentationFunctionRegistrationInTimeRange(long startTimestampMs, long endTimestampMs)`: Get the registrations in the specified time range
+                * `getAugmentationFunctionRegistrationInRange(int startIndex, int endIndex)`: Get the registrations in the specified range of indices
+            * Unregistration
+                * `saveAugmentationFunctionUnregistration(String augmentationFunctionId, String augmentationFunctionHandlerId, AugmentationFunctionType augmentationFunctionType)`: Save the Augmentation Function Unregistration
+                * `getAugmentationFunctionUnregistrationCount()`: Get the number of Augmentation Function Unregistrations stored
+                * `getAugmentationFunctionUnregistrationInTimeRange(long startTimestampMs, long endTimestampMs)`: Get the unregistrations in the specified time range
+                * `getAugmentationFunctionUnregistrationInRange(int startIndex, int endIndex)`: Get the unregistrations in the specified range of indices
 
 Some examples of usage for the Storage Layer are the following:
 
@@ -143,7 +169,7 @@ myRedisStorage.setRedisConfiguration(myRedisConfiguration);
 digitalTwin.getStorageManager().putStorage(myRedisStorage);
 
 // Create a new MongoDbWldtStorage instance using the default implementation and observing only State and LifeCycle Events
-MongoDbWldtStorage myMongoDbStorage = new MongoDbWldtStorage("mongo_db_storage", true, false, false, false, false, true);
+MongoDbWldtStorage myMongoDbStorage = new MongoDbWldtStorage("mongo_db_storage", true, false, false, false, false, true, false);
 myMongoDbStorage.setMongoDbConfiguration(myMongoDbConfiguration);
 
 // Add the new MongoDb Storage Instance to the Digital Twin Storage Manager 
@@ -240,6 +266,26 @@ The main classes associated to the Query System are the following:
         - SAMPLE_RANGE
         - COUNT
         - LAST_VALUE
+    - AUGMENTATION_FUNCTION_ERROR
+        - TIME_RANGE
+        - SAMPLE_RANGE
+        - COUNT
+    - AUGMENTATION_FUNCTION_REQUEST
+        - TIME_RANGE
+        - SAMPLE_RANGE
+        - COUNT
+    - AUGMENTATION_FUNCTION_RESULT
+        - TIME_RANGE
+        - SAMPLE_RANGE
+        - COUNT
+    - AUGMENTATION_FUNCTION_REGISTRATION
+        - TIME_RANGE
+        - SAMPLE_RANGE
+        - COUNT
+    - AUGMENTATION_FUNCTION_UNREGISTRATION
+        - TIME_RANGE
+        - SAMPLE_RANGE
+        - COUNT
     - STORAGE_STATS
         - LAST_VALUE
 - `QueryExecutor`: This class represents the Query Executor used to execute queries on the storage system supporting both synchronous and asynchronous query execution. Internally is implemented through an event-based mechanism to handle the query request and response