v0.7.0

WLDT - 0.7.0

Version 0.7.0 introduces the Augmentation Function framework, a major feature addition that extends Digital Twin capabilities beyond basic shadowing. This release adds a fully event-driven augmentation layer, comprehensive storage support for augmentation data, new event types on the WLDT Event Bus, and native augmentation-aware callbacks inside the DigitalTwinModel.

Key Updates:

• Augmentation Function Framework: A hierarchical, modular architecture enabling Stateless and Stateful augmentation functions to be registered, executed, and managed independently from the core shadowing logic
• Storage Layer Extension: WldtStorage now defines a full set of abstract methods to persist and query augmentation function requests, results, errors, registrations, and unregistrations
• WLDT Event Bus — Augmentation Events: Eight new event types added to WldtEventTypes covering the complete augmentation lifecycle (registration, execution, result, error)
• DigitalTwinModel Augmentation Integration: The DigitalTwinModel now subscribes to augmentation events automatically and exposes optional callback methods and invocation helpers for both Stateless and Stateful functions

---

Augmentation Function Framework

This release introduces the Augmentation Function framework, a first-class mechanism for extending Digital Twin behaviour with external computation units that operate independently from the shadowing logic.

The augmentation architecture is organized in four tiers:

Tier	Component	Role
1	DT Kernel	Hosts the DigitalTwinModel and the AugmentationManager
2	AugmentationManager	Central orchestrator; manages handlers, propagates lifecycle events, caps concurrent handlers at 5
3	AugmentationFunctionHandler	Manages a group of functions; handles execution, context provisioning, and result forwarding
4	AugmentationFunction	Performs actual computation (stateless or stateful)

Function Types

Stateless Functions

A Stateless Function does not maintain internal state between invocations. Each execute call is fully independent.

• Triggered via executeAugmentationFunction(...) from the DigitalTwinModel
• Context is built automatically from the function's AugmentationFunctionContextRequest
• Results are returned synchronously to the handler and forwarded to the DTM

Typical use cases: threshold checks, unit conversions, data validation, instantaneous calculations.

Stateful Functions

A Stateful Function maintains internal state across a continuous execution lifecycle managed through start / stop operations.

• Started via startAugmentationFunction(...), stopped via stopAugmentationFunction(...)
• Receives automatic updates with new DigitalTwinState and event notifications while running
• Produces results asynchronously; can request storage query refreshes via onStatefulAugmentationFunctionQueryResultRefresh

Typical use cases: pattern recognition, trend analysis, running averages, adaptive AI models.

AugmentationFunctionHandler

AugmentationFunctionHandler is the abstract base class for all handlers. The ready-to-use concrete implementation is DefaultAugmentationFunctionHandler:

// Create the handler
DefaultAugmentationFunctionHandler handler = new DefaultAugmentationFunctionHandler("sensor-handler");

// Register functions
handler.registerAugmentationFunction(new MyStatelessFunction());
handler.registerAugmentationFunction(new MyStatefulFunction());

// Attach to the AugmentationManager
DigitalTwin digitalTwin = new DigitalTwin("my-dt-id", new MyDigitalTwinModel());
digitalTwin.getAugmentationManager().addAugmentationFunctionHandler(handler);

Functions can be unregistered at runtime without stopping the handler:

handler.unRegisterAugmentationFunction(MyStatelessFunction.FUNCTION_ID);

Handlers can be removed from the manager entirely:

digitalTwin.getAugmentationManager().removeAugmentationFunctionHandler("sensor-handler");

Registration and Lifecycle

The augmentation lifecycle follows an event-driven, loosely coupled flow:

1. Pre-Start Registration: Functions are registered on a handler before the DT starts. Registration events are published on the Event Bus but not yet consumed.
2. DT Initialization: On start, the DigitalTwinModel subscribes to registration and result events.
3. Catch-Up at Sync: When the DT reaches the Synchronized state, the DTM queries the AugmentationManager to discover already-registered functions and fires the appropriate callbacks.
4. Dynamic Registration: New functions can be registered at any time. If the DT is already synchronized, the DTM receives the event immediately.
5. Dynamic Unregistration: Functions removed at runtime fire an unregistration event that the DTM handles to update its internal state.

AugmentationManager

The AugmentationManager is created automatically for each DigitalTwin instance and is accessible via:

AugmentationManager augmentationManager = digitalTwin.getAugmentationManager();

⚠️ Warning: The AugmentationManager limits concurrent handlers to 5. Exceeding this limit throws an AugmentationFunctionException.

Listener Interfaces

Three listener interfaces decouple functions from their handlers:

Interface	Implemented By	Purpose
AugmentationLifeCycleListener	AugmentationFunctionHandler	Receives relevant DT lifecycle events
StatelessAugmentationListener	AugmentationFunctionHandler	Receives error notifications from stateless functions
StatefulAugmentationListener	AugmentationFunctionHandler	Receives results, errors, and query refresh requests from stateful functions

Result and Error Structures

• AugmentationFunctionResult<?>: Carries the output of a function execution together with type metadata (AugmentationFunctionResultType) and optional performance metrics (AugmentationFunctionResultMetrics)
• AugmentationFunctionError: Carries error information with an associated AugmentationFunctionErrorType, used by both stateless and stateful functions to report failures

---

Context & Context Request

AugmentationFunctionContext

AugmentationFunctionContext encapsulates the runtime data provided to a function during execution.

public class AugmentationFunctionContext {
    private DigitalTwinState digitalTwinState;
    private QueryResult<?> queryResult;
}

Field	Type	Description
digitalTwinState	DigitalTwinState	Current DT state at the time of invocation
queryResult	QueryResult<?>	Results from storage queries defined in the AugmentationFunctionContextRequest (optional)

The context is built automatically by the framework and injected into run() (stateless) or start() (stateful) — developers never create it directly.

---

AugmentationFunctionContextRequest

AugmentationFunctionContextRequest is the configuration that each augmentation function declares to tell the framework what data it needs at runtime. It is typically set once in the function's constructor.

public class AugmentationFunctionContextRequest {
    private boolean observeState;               // default: true
    private boolean observeEventNotifications;  // default: true
    private List<String> propertyNameFilter;    // null = observe all
    private List<String> eventNameFilter;       // null = observe all
    private List<String> relationshipNameFilter;// null = observe all
    private QueryRequest queryRequest;          // null = no storage query
}

⚠️ Note: propertyNameFilter, eventNameFilter, and relationshipNameFilter are declared but currently not enforced by the framework. Use observeState: false or observeEventNotifications: false to fully suppress the corresponding data stream.

Constructors:

// Default: observes state and events, no storage query
new AugmentationFunctionContextRequest()

// With a storage query only
new AugmentationFunctionContextRequest(QueryRequest queryRequest)

// With explicit observation flags and optional query
new AugmentationFunctionContextRequest(boolean observeState,
                                       boolean observeEventNotifications,
                                       QueryRequest queryRequest)

Example — function that queries the last 10 minutes of DT state history:

public MyStatelessFunction() {
    super("my-fn", "My Function", "Analyzes history", "1.0.0",
          new AugmentationFunctionContextRequest(
              new QueryRequest()
                  .setResourceType(QueryResourceType.DIGITAL_TWIN_STATE)
                  .setRequestType(QueryRequestType.TIME_RANGE)
                  .setStartTimestampMs(System.currentTimeMillis() - 600_000)
                  .setEndTimestampMs(System.currentTimeMillis())
          ));
}

⚠️ Note: timestamps are computed once at construction time. For a truly sliding time window, build and pass a fresh QueryRequest at each invocation instead.

---

AugmentationFunctionRequest

AugmentationFunctionRequest is the runtime object passed to every lifecycle method (run(), start(), stop()). It bundles the context with invocation metadata.

public class AugmentationFunctionRequest {
    private final String requestId;                // Auto-generated or developer-provided UUID
    private final AugmentationFunctionContext context;
    private final AugmentationFunctionReque...

v0.6.0

WLDT - 0.6.0

Version 0.6.0 introduces a major architectural refactoring of the WLDT core framework alongside critical bug fixes and functional enhancements. This release focuses on improving semantic clarity, fixing data accessibility issues, and enhancing adapter capabilities.

Core Architecture Refactoring

Comprehensive reorganization of Digital Twin components with clearer naming (DigitalTwinKernel and DigitalTwinModel) that accurately distinguishes orchestration from behavioral logic.

The key architectural changes are:

1. DigitalTwinModel → DigitalTwinKernel: The core orchestrator has been renamed to accurately reflect its role as the fundamental nucleus coordinating all DT components
2. ShadowingFunction → DigitalTwinModel: The behavioral definition component now properly claims the "Model" terminology, representing the actual logic that defines how the Digital Twin behaves

Bug Fixes & Enhancements

This release focuses on stability improvements and expanded extensibility for multi-adapter
configurations. Key highlights include the resolution of known storage query limitations,
the introduction of Physical Adapter lifecycle callbacks, automatic source identification
in multi-adapter setups, and richer metadata support in PhysicalAssetEvent.

In particular we have in the release:

• Storage Query Limitations Resolved: A set of limitations affecting storage queries has been identified and resolved. Queries that previously returned incomplete or inconsistent results under specific conditions now behave
  correctly, ensuring reliable access to persisted Digital Twin state, events, and lifecycle data.
• Physical Adapter Lifecycle Callbacks: Physical Adapters now expose lifecycle callbacks, giving developers explicit hooks into the adapter's initialization, execution, and termination phases. This enables more fine-grained control over adapter behavior and simplifies the implementation of setup and teardown logic directly within the adapter itself.
• Automatic Source Identification for Multi-Adapter Configurations: In scenarios where multiple Physical Adapters are active simultaneously, the framework now automatically identifies and associates the source adapter for each incoming event or update.
  This removes the need for manual tagging at the application level and improves traceability in complex, multi-source Digital Twin architectures.
• Content-Type Support in PhysicalAssetEvent: A new contentType field (String) has been added to the PhysicalAssetEvent class. This field allows Physical Adapters to communicate the content type of the event body (e.g.
  application/json, application/cbor) to the Shadowing Function and downstream consumers. The field can be set directly by the developer and is accessible via standard getter and setter methods.

v0.5.0

WLDT v0.5.0

WLDT v0.5.0 introduces significant enhancements to the Digital Twin framework, emphasizing flexible resource management and a modular logging system. This release enables runtime-configurable resources that can be managed internally by Digital Twin logic and accessed externally via a customizable Management Interface. The new logging layer has been designed to make the library independent from external logging frameworks while allowing developers to fully customize how logs are generated and which logging libraries to use.

Resource Management

New classes introduce a unified, runtime-configurable resource model for Digital Twins (DTs). Resources can be managed internally by DT logic and accessed or updated externally through an abstract Management Interface. The system supports CRUD operations, observers for change notifications, and flexible integration with protocols like REST, MQTT, or gRPC. Key classes include ManagedResource, ResourceManager, ResourceRequest, ResourceResponse, and ManagementInterface. Resources can be dynamically configured at startup or during runtime, enabling adaptable DT behavior and external interaction.

Logging

WLDT now provides a modular logging layer designed for flexibility and easy integration. Developers can use the default console-based logger or implement custom loggers through the WldtLogger, WldtLoggerFactory, and WldtLoggerProvider interfaces. This layer supports multiple log levels, timestamped output, and can be seamlessly replaced or extended to integrate with frameworks like SLF4J, Log4j, or Logback without changing core DT code.

v0.4.0

New Features

WldtEventObserver

A new class called WldtEventObserver has been introduced to allow a simplified observation of target specific events generated by the Digital Twin and its components such as adapters and the model. 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 (See next sections for additional information)

For each event type dedicated observation and un-observation methods (e.g., observePhysicalAssetEvents() and unObservePhysicalAssetEvents()) are available in order to create an instance of the observer and decide which events to receive.

To build a WldtEventObserver a dedicated listener IWldtEventObserverListener should be implemented by the developer to receive the callbacks related to the incoming events. All the events are of the generic type WldtEvent and it is up to the developer the validate and check the received object and if it match with the expected one.

The WldtEventObserver has been currently used internally within the library to simplify the implementation and usage of the Storage Layer and the associated Storage Query System as described in the dedicated sections.

Storage Layer

A new storage layer has been integrated into the core WLDT library, enabling Digital Twins (DTs) to store data related to the evolution of their state, generated events, and any variations involving properties, events, actions, relationships, and life cycle. The Storage Layer consists of two main components:

• Storage Manager: This is the central component of the storage system, facilitating the structured and modular storage and retrieval of information. It allows developers to create and utilize various storage systems (e.g., in-memory, file-based, or DBMS) simultaneously. The Storage Layer is accessible in both read and write modes internally by the DT's Model, and in read-only mode via the Query System by Digital Adapters.
• Query System: To delegate and encapsulate the responsibility of data storage within the DT's model, a query system has been integrated. This system enables Digital Adapters to retrieve stored data and expose it according to their specific logic and implementation.

The storage layer is designed for easy extension, allowing developers to create and share new storage layers (e.g., using Redis, MySQL, or MongoDB). The provided in-memory implementation serves only for basic development and testing purposes. Similarly, the Query Manager can be extended and customized by developers to implement additional query management features or to enhance the default functionalities provided by the library.

Migration Info: 0.3.0 - 0.4.0

• Now PhysicalAssetRelationship constructor has also the type in order to match the DigitalTwinStateRelationship and simplify its management
• The method notifyDigitalTwinStateEvent throws only the Exception WldtDigitalTwinStateEventNotificationException while EventBusException has been removed

Additional Improvements & Fixed Bugs

• Synchronized the update of the current DT Life Cycle State in order to avoid wrong data
• The WldtEventBus now supports the use of topics Wildcard (at the moment only multi-level with the character *). For example with this approach is possible to subscribe to all the events associated to property variations (topic: dt.physical.event.property.*). New methods added to WldtEventBus are:
  • matchWildCardType(String eventType, String filterType): Check if the provided event type match the WildCard Type
  • isWildCardType(String filterEventType): Check if the provided event type is a WildCard Type
• The class WldtEventTypes has been introduced to contain all the event types in the WLDT Framework and support internal message exchange. Includes types for events associated and adopted by: i) Physical Adapters; ii) Model and Shadowing Function; and iii) Digital Adapters.
• The EventManager class has been added to centralize and simplify the event management in the WLDT Framework providing a set of static methods to publish events associated to a target digital twin and publisher (e.g., the physical adapter of the twin).
• Now PhysicalAssetRelationship class has also the type in order to match the DigitalTwinStateRelationship and simplify its management
• The internal class ModelEngine has been renamed into DigitalTwinModel as an initial update for further development of the next version 0.5.0 where the structure of the DT's Model and the associated classes will be improved

v0.3.0

Release of the WLDT Library version 0.3.0.

This release brings significant enhancements, improvements, and new features to further empower developers in designing, developing, and deploying Digital Twins within Internet of Things (IoT) ecosystems.

For detailed information about these changes and their impact, please refer to the information provided:

• Official Changelog
• Official Documentation

Key changes and updates included in this release:

Migration Digital Adapters

In version 0.3.0, we've made several enhancements and adjustments to the Digital Adapter class to improve its functionality and usability. Notable changes include:

• Discontinued Methods: Several methods have been discontinued and removed from the DigitalAdapter class to streamline its interface and improve clarity.
  Method Signature Changes: The signatures of certain methods have been updated for consistency and clarity, ensuring a more intuitive developer experience.
• New Methods: We've introduced new methods to provide additional functionality and flexibility for handling state updates and event notifications.

Migration Shadowing Function

We've made significant improvements to the ShadowingModelFunction, which is now renamed to ShadowingFunction. Additionally, we've introduced changes to how the DigitalTwinState is managed within the Shadowing Function, providing developers with more control and flexibility.

Migrating WLDT Engine & DT Creation

In version 0.3.0, the WldtEngine class has been renamed to DigitalTwin, offering improved clarity and consistency. We've also made adjustments to the lifecycle management of Digital Twins, streamlining the process and enhancing usability.

Digital Twin & Digital Twin Engine

We've introduced enhancements to the Digital Twin and Digital Twin Engine classes, providing developers with improved functionality and ease of use. Notable updates include:

• Simplified Digital Twin Creation: Creating and managing Digital Twins is now more intuitive and streamlined.
• Lifecycle Management: We've enhanced the lifecycle management of Digital Twins, making it easier to start, stop, and manage multiple instances.

Digital Twin State Manager

The DigitalTwinStateManager class has been improved to provide better support for managing the state of Digital Twins. With features such as transaction support and event notification, developers can more effectively manage changes to Digital Twin states and respond to events.

To learn more about the capabilities of the DigitalTwinStateManager, please refer to the Digital Twin State Manager section.

Digital Adapter

We've extended and improved the Digital Adapter base class to provide enhanced support for handling Digital Twin state updates and event notifications. With the introduction of the onStateUpdate and onEventNotificationReceived methods, developers can more effectively respond to changes in Digital Twin states and events.

v0.2.1

First Manual Release - v0.2.1