Minor changes and comments improved.

Author: piconem

README.md

@@ -1989,4 +1989,12 @@ public class TestDigitalTwin {
         }
     }
 }
-````
+````
+## Storage Layer 
+
+The storage layer is a fundamental component of the WLDT library that allows the storage of the Digital Twin's state
+and the related events (both from physical and digital spaces). The package associated to the Storage Layer are the following:
+
+- ```it.wldt.storage```: Contains the main interfaces and classes to manage the storage layer.
+- ```it.wldt.storage.model```: Contains the main classes and data structure to manage the storage layer data model.
+- ```it.wldt.storage.query```: Contains the main classes and data structure to query the storage layer from other WLDT components (e.g., Digital Adapters).

src/main/java/it/wldt/core/engine/DigitalTwin.java

@@ -40,7 +40,6 @@ public class DigitalTwin implements ShadowingModelListener, PhysicalAdapterListe
 
     private static final String EVENT_PUBLISHER_ID = "dt_core";
 
-
     // Internal TAG fo Logs
     private static final String TAG = "[WLDT-DigitalTwin]";
 
@@ -134,6 +133,9 @@ public class DigitalTwin implements ShadowingModelListener, PhysicalAdapterListe
      */
     private String digitalTwinId;
 
+    /**
+     * Object used to synchronize the state of the Digital Twin
+     */
     private Object syncStateObject = new Object();
 
     /**
@@ -229,6 +231,8 @@ private void init(ShadowingFunction shadowingFunction) throws ModelException, Wl
         //Set ShadowingListener, Init Model Engine & Add to the List of Workers
         this.shadowingFunction = shadowingFunction;
         this.shadowingFunction.setShadowingModelListener(this);
+
+        // Initialize the Digital Twin Model with digital twin ID, state manager, and shadowing function
         this.modelEngine = new ModelEngine(this.digitalTwinId, this.digitalTwinStateManager, this.shadowingFunction);
 
         //Save the Model Engine as Digital Twin Life Cycle Listener

src/main/java/it/wldt/core/event/EventManager.java

@@ -9,16 +9,24 @@
 import org.slf4j.LoggerFactory;
 import java.util.HashMap;
 
+/**
+ * Author: Marco Picone (picone.m@gmail.com)
+ * Date: 01/08/2024
+ * Project: WLDT Framework
+ * Event Manager class used centralize and simplify the event management in the WLDT Framework.
+ * The Event Manager class provides a set of static methods to publish events associated to a target digital twin
+ * and publisher (e.g., the physical adapter of the twin).
+ */
 public class EventManager {
 
     private static final Logger logger = LoggerFactory.getLogger(EventManager.class);
 
     /**
-     *
-     * @param digitalTwinId
-     * @param publisherId
-     * @param event
-     * @throws EventBusException
+     * Publishes an Event associated to a target digital twin and publisher
+     * @param digitalTwinId Digital Twin Id
+     * @param publisherId Publisher Id
+     * @param event Event to be published
+     * @throws EventBusException EventBus Exception in case of error
      */
     private static void publishEvent(String digitalTwinId,
                                           String publisherId,
@@ -28,11 +36,12 @@ private static void publishEvent(String digitalTwinId,
     }
 
     /**
-     *
-     * @param digitalTwinId
-     * @param publisherId
-     * @param adapterId
-     * @param physicalAssetDescription
+     * Notifies that a new Physical Asset Description (PAD) is available from a Physical Adapter associated
+     * to a Digital Twin. The notification generates a Physical Asset Description Available Event.
+     * @param digitalTwinId Digital Twin Id
+     * @param publisherId Publisher Id
+     * @param adapterId Adapter Id
+     * @param physicalAssetDescription Physical Asset Description
      */
     public static void notifyPhysicalAdapterPadAvailable(String digitalTwinId,
                                                          String publisherId,
@@ -61,11 +70,11 @@ public static void notifyPhysicalAdapterPadAvailable(String digitalTwinId,
     }
 
     /**
-     * Publishes a Physical Asset Description Updated Event
-     * @param digitalTwinId
-     * @param publisherId
-     * @param adapterId
-     * @param physicalAssetDescription
+     * Publishes a Physical Asset Description Updated Event associated to a target digital twin and publisher
+     * @param digitalTwinId Digital Twin Id
+     * @param publisherId Publisher Id
+     * @param adapterId Adapter Id
+     * @param physicalAssetDescription Physical Asset Description
      */
     public static void notifyPhysicalAdapterPadUpdated(String digitalTwinId,
                                                          String publisherId,
@@ -94,10 +103,10 @@ public static void notifyPhysicalAdapterPadUpdated(String digitalTwinId,
     }
 
     /**
-     * Publishes a Life Cycle Event
-     * @param digitalTwinId
-     * @param publisherId
-     * @param lifeCycleState
+     * Publishes a Life Cycle Event associated to a target digital twin and publisher
+     * @param digitalTwinId Digital Twin Id
+     * @param publisherId Publisher Id
+     * @param lifeCycleState Life Cycle State
      */
     public static void publishLifeCycleEvent(String digitalTwinId,
                                              String publisherId,

src/main/java/it/wldt/core/event/WldtEventBus.java

@@ -29,12 +29,20 @@ private WldtEventBus(){
         this.subscriberMap = new HashMap<>();
     }
 
+    /**
+     * Get the current instance of the WLDT Event Bus
+     * @return the current instance of the WLDT Event Bus
+     */
     public static WldtEventBus getInstance(){
         if(instance == null)
             instance = new WldtEventBus();
         return instance;
     }
 
+    /**
+     * Set the Event Logger for the current EventBus instance
+     * @param eventLogger the Event Logger to set
+     */
     public void setEventLogger(IWldtEventLogger eventLogger){
         this.eventLogger = eventLogger;
     }
@@ -51,6 +59,13 @@ private Optional<SubscriptionDescriptor> getSubscriptionForDigitalTwin(String di
             return Optional.empty();
     }
 
+    /**
+     * Publish a new event on the event bus
+     * @param digitalTwinId the digital twin id
+     * @param publisherId the publisher id
+     * @param wldtEvent the event to publish
+     * @throws EventBusException in case of error contains the exception with the error message
+     */
     public void publishEvent(String digitalTwinId, String publisherId, WldtEvent<?> wldtEvent) throws EventBusException {
 
         if(this.subscriberMap == null)
@@ -97,6 +112,11 @@ public void publishEvent(String digitalTwinId, String publisherId, WldtEvent<?>
         }
     }
 
+    /**
+     * Check if the provided event type is a WildCard Type
+     * @param filterEventType the event type to check
+     * @return true if the event type is a WildCard Type, false otherwise
+     */
     private boolean isWildCardType(String filterEventType){
         try{
             if(filterEventType != null){
@@ -115,6 +135,12 @@ private boolean isWildCardType(String filterEventType){
         }
     }
 
+    /**
+     * Check if the provided event type match the WildCard Type
+     * @param eventType the event type to check
+     * @param filterType the filter type to check
+     * @return true if the event type is a WildCard Type, false otherwise
+     */
     public boolean matchWildCardType(String eventType, String filterType){
         // If the filter type is a wild card filter
         if(isWildCardType(filterType)){
@@ -126,6 +152,14 @@ public boolean matchWildCardType(String eventType, String filterType){
             return false;
     }
 
+    /**
+     * Subscribe a new client to the event bus
+     * @param digitalTwinId the digital twin id
+     * @param subscriberId the subscriber id
+     * @param wldtEventFilter the event filter
+     * @param wldtEventListener the event listener
+     * @throws EventBusException in case of error contains the exception with the error message
+     */
     public void subscribe(String digitalTwinId, String subscriberId, WldtEventFilter wldtEventFilter, WldtEventListener wldtEventListener) throws EventBusException{
 
         if(this.subscriberMap == null)
@@ -162,6 +196,14 @@ public void subscribe(String digitalTwinId, String subscriberId, WldtEventFilter
         }
     }
 
+    /**
+     * Unsubscribe a client from the event bus
+     * @param digitalTwinId the digital twin id
+     * @param subscriberId the subscriber id
+     * @param wldtEventFilter the event filter
+     * @param wldtEventListener the event listener
+     * @throws EventBusException in case of error contains the exception with the error message
+     */
     public void unSubscribe(String digitalTwinId, String subscriberId, WldtEventFilter wldtEventFilter, WldtEventListener wldtEventListener) throws EventBusException{
 
         if(this.subscriberMap == null)

src/main/java/it/wldt/core/event/WldtEventTypes.java

@@ -1,5 +1,10 @@
 package it.wldt.core.event;
 
+/**
+ * Author: Marco Picone (picone.m@gmail.com)
+ * Date: 01/08/2024
+ * This class contains all the event types used in the WLDT Framework
+ */
 public class WldtEventTypes {
 
     public static final String MULTI_LEVEL_WILDCARD_VALUE = "*";

src/main/java/it/wldt/core/event/observer/IWldtEventObserverListener.java

@@ -2,6 +2,9 @@
 
 import it.wldt.core.event.WldtEvent;
 
+/**
+ * Interface for the WldtEventObserverListener allowing to listen to the events of the WldtEventObserver
+ */
 public interface IWldtEventObserverListener {
 
     public void onEventSubscribed(String eventType);

src/main/java/it/wldt/core/event/observer/WldtEventObserver.java

@@ -8,7 +8,18 @@
 import java.util.Arrays;
 
 /**
- *
+ * Author: Marco Picone (picone.m@gmail.com)
+ * Date: 01/08/2024
+ * Wldt Event Observer Class
+ * This class is used to observe specific events generated by the Digital Twin Model and the Physical Adapters
+ * Main mapped events and filters are:
+ * - State Events: State Update and State Event Notifications
+ * - Physical Asset Events: Physical Property Variation, Physical Event Notification, Physical Relationship Instance Creation and Deletion
+ * - Physical Asset Action Events: Physical Action Trigger
+ * - Digital Action Events: Digital Action Event
+ * - Physical Asset Description Events: Physical Asset Description Available and Updated
+ * - Life Cycle Events: Digital Twin Life Cycle Events
+ * - Query Request Events: Storage Query Request Events
  */
 public class WldtEventObserver implements WldtEventListener {
 
@@ -39,6 +50,13 @@ public class WldtEventObserver implements WldtEventListener {
     private WldtEventObserver() {
     }
 
+    /**
+     * Wldt Event Observer Constructor
+     * @param digitalTwinId Digital Twin Id
+     * @param observerId Observer Id
+     * @param observerListener Observer Listener
+     * @throws WldtRuntimeException Wldt Runtime Exception
+     */
     public WldtEventObserver(String digitalTwinId, String observerId, IWldtEventObserverListener observerListener) throws WldtRuntimeException {
 
         this.digitalTwinId = digitalTwinId;
@@ -66,6 +84,12 @@ public WldtEventObserver(String digitalTwinId, String observerId, IWldtEventObse
         this.observerListener = observerListener;
     }
 
+    /**
+     * Trigger the observation of events generated from the Digital Twin Model related to State Variations and Event
+     * Notifications
+     * @param eventTypeList List of Event Types to Observe
+     * @throws EventBusException Event Bus Exception
+     */
     private void observeEventsWithFilter(WldtEventFilter targetFilter, String... eventTypeList){
         try{
             if(eventTypeList == null || eventTypeList.length == 0)
@@ -88,6 +112,12 @@ private void observeEventsWithFilter(WldtEventFilter targetFilter, String... eve
         }
     }
 
+    /**
+     * Cancel the observation of events generated from the Digital Twin Model related to State Variations and Event
+     * Notifications
+     * @param targetFilter Filter to Cancel
+     * @throws EventBusException Event Bus Exception
+     */
     public void unObserveEventsWithFilter(WldtEventFilter targetFilter) throws EventBusException {
         try{
             if (targetFilter != null && !targetFilter.isEmpty()) {