enriched-qwen3-coder-next/Common/DTS.Common/Interface/TestSetups/CachedItemsList.md

---
source_files:
  - Common/DTS.Common/Interface/TestSetups/CachedItemsList/ICachedItemsListView.cs
  - Common/DTS.Common/Interface/TestSetups/CachedItemsList/ICachedItem.cs
  - Common/DTS.Common/Interface/TestSetups/CachedItemsList/ICachedItemsListViewModel.cs
generated_at: "2026-04-16T03:12:02.925328+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "7a4cfa746af4994d"
---

# CachedItemsList

### **Purpose**  
This module defines the interface contracts for a cached items list feature within the test setup infrastructure. It establishes a standardized way to represent cached items (e.g., sensor or hardware configurations) along with metadata about their origin and validity, and provides a view-model layer to manage and expose the state of these cached items—including out-of-date or missing items—relative to current system data (sensors, calibrations, hardware). Its role is to decouple UI concerns (via `ICachedItemsListView`) from business logic (via `ICachedItemsListViewModel`) in a test setup context, enabling consistent handling of cached configuration data.

---

### **Public Interface**

#### `ICachedItemsListView`  
- **Signature**: `interface ICachedItemsListView : IBaseView`  
- **Behavior**: A view interface (likely consumed by a UI layer) representing the presentation layer for the cached items list. Inherits from `IBaseView`, implying standard view lifecycle or binding behavior (not detailed here). No additional members defined.

#### `ICachedItem`  
- **Signature**: `interface ICachedItem`  
- **Properties**:  
  - `string Name { get; }` – Human-readable identifier of the cached item.  
  - `string ObjectType { get; }` – Type of the underlying object (e.g., `"Sensor"`, `"Hardware"`), likely used for categorization or UI rendering.  
  - `DateTime CacheTime { get; }` – Timestamp when the item was last cached (i.e., written to the cache).  
  - `DateTime DBTime { get; }` – Timestamp of the item’s last modification in the database. `DateTime.MinValue` indicates the item no longer exists in the database; otherwise, it reflects the DB’s `LastModified` value.

#### `ICachedItemsListViewModel`  
- **Signature**: `interface ICachedItemsListViewModel : IBaseViewModel`  
- **Properties**:  
  - `ICachedItemsListView View { get; set; }` – Reference to the associated view instance (for view-model-to-view binding).  
  - `ICachedItem[] CachedItems { get; set; }` – Array of cached items currently managed by the view model.  
- **Methods**:  
  - `bool SetCachedItems(ISensorData[] sensors, ISensorCalibration[] sensorCalibrations, IDASHardware[] hardware, IDASHardware[] allDAS)` – Updates the cached items list by comparing/merging input data sources (current sensors, calibrations, and hardware). Returns `true` if the cached items list was modified as a result; `false` otherwise.  
- **Properties (read-only)**:  
  - `bool HasOutofDateCachedItems { get; }` – `true` if any cached item’s `DBTime` is newer than its `CacheTime`, indicating the cache is stale for that item.  
  - `bool HasMissingSensors { get; }` – `true` if any cached item references a sensor that no longer exists in the current `sensors` data (inferred from `DBTime == DateTime.MinValue` and `ObjectType == "Sensor"`).

---

### **Invariants**  
- `ICachedItem.DBTime == DateTime.MinValue` **iff** the item is no longer present in the database.  
- `ICachedItem.CacheTime` must be ≤ `ICachedItem.DBTime` for items still in the database (i.e., `DBTime != DateTime.MinValue`), as caching occurs *after* DB persistence.  
- `ICachedItemsListViewModel.CachedItems` must be populated *only* via `SetCachedItems(...)`, and its contents reflect the current state of the system’s sensors, calibrations, and hardware.  
- `HasOutofDateCachedItems` is `true` **iff** at least one `ICachedItem` in `CachedItems` has `DBTime > CacheTime`.  
- `HasMissingSensors` is `true` **iff** at least one `ICachedItem` in `CachedItems` has `ObjectType == "Sensor"` and `DBTime == DateTime.MinValue`.  
- `SetCachedItems(...)` must process *all* provided arrays (`sensors`, `sensorCalibrations`, `hardware`, `allDAS`) to determine cache validity; partial processing is not permitted.

---

### **Dependencies**  
- **Depends on**:  
  - `DTS.Common.Base.IBaseView`, `DTS.Common.Base.IBaseViewModel` (base interfaces for view/view-model).  
  - `DTS.Common.Interface.DataRecorders.ISensorData`, `ISensorCalibration` (for sensor and calibration metadata).  
  - `DTS.Common.Interface.Sensors.IDASHardware` (for DAS hardware metadata).  
- **Depended on by**:  
  - UI layers implementing `ICachedItemsListView` (e.g., WPF/WinForms views).  
  - Higher-level view models or controllers that coordinate test setup workflows and need to validate cached configurations.  
  - Likely consumed by a test setup wizard or configuration manager (not visible in source, but implied by naming).

---

### **Gotchas**  
- `HasMissingSensors` is **not** a general "missing items" flag—it specifically tracks *sensors* only (based on `ObjectType == "Sensor"`), per the `DBTime == DateTime.MinValue` convention. Missing hardware or calibration items are not covered by this property.  
- `SetCachedItems(...)` accepts `IDASHardware[] hardware` and `IDASHardware[] allDAS`—the distinction between these two arrays is not clarified in the source (e.g., whether `hardware` is a subset of `allDAS`), making it unclear how overlap or precedence is handled.  
- The return value of `SetCachedItems(...)` (`true`/`false`) indicates whether the `CachedItems` array *changed*, but does not indicate *why* (e.g., whether changes were due to staleness, missing items, or new items).  
- No explicit thread-safety guarantees are defined; concurrent access to `CachedItems` or `SetCachedItems(...)` may require external synchronization.  
- `ObjectType` values are not enumerated or validated—consumers must assume string literals (e.g., `"Sensor"`, `"Hardware"`) are used consistently elsewhere.
-												init

											
										
										
											2026-04-17 14:55:32 -04:00
+								---
 								source_files:
 								  - Common/DTS.Common/Interface/TestSetups/CachedItemsList/ICachedItemsListView.cs
 								  - Common/DTS.Common/Interface/TestSetups/CachedItemsList/ICachedItem.cs
 								  - Common/DTS.Common/Interface/TestSetups/CachedItemsList/ICachedItemsListViewModel.cs
 								generated_at: "2026-04-16T03:12:02.925328+00:00"
 								model: "Qwen/Qwen3-Coder-Next-FP8"
 								schema_version: 1
 								sha256: "7a4cfa746af4994d"
 								---
 								# CachedItemsList
 								### **Purpose**
 								This module defines the interface contracts for a cached items list feature within the test setup infrastructure. It establishes a standardized way to represent cached items (e.g., sensor or hardware configurations) along with metadata about their origin and validity, and provides a view-model layer to manage and expose the state of these cached items—including out-of-date or missing items—relative to current system data (sensors, calibrations, hardware). Its role is to decouple UI concerns (via `ICachedItemsListView`) from business logic (via `ICachedItemsListViewModel`) in a test setup context, enabling consistent handling of cached configuration data.
 								---
 								### **Public Interface**
 								#### `ICachedItemsListView`
 								- **Signature**: `interface ICachedItemsListView : IBaseView`
 								- **Behavior**: A view interface (likely consumed by a UI layer) representing the presentation layer for the cached items list. Inherits from `IBaseView`, implying standard view lifecycle or binding behavior (not detailed here). No additional members defined.
 								#### `ICachedItem`
 								- **Signature**: `interface ICachedItem`
 								- **Properties**:
 								  - `string Name { get; }` – Human-readable identifier of the cached item.
 								  - `string ObjectType { get; }` – Type of the underlying object (e.g., `"Sensor"`, `"Hardware"`), likely used for categorization or UI rendering.
 								  - `DateTime CacheTime { get; }` – Timestamp when the item was last cached (i.e., written to the cache).
 								  - `DateTime DBTime { get; }` – Timestamp of the item’s last modification in the database. `DateTime.MinValue` indicates the item no longer exists in the database; otherwise, it reflects the DB’s `LastModified` value.
 								#### `ICachedItemsListViewModel`
 								- **Signature**: `interface ICachedItemsListViewModel : IBaseViewModel`
 								- **Properties**:
 								  - `ICachedItemsListView View { get; set; }` – Reference to the associated view instance (for view-model-to-view binding).
 								  - `ICachedItem[] CachedItems { get; set; }` – Array of cached items currently managed by the view model.
 								- **Methods**:
 								  - `bool SetCachedItems(ISensorData[] sensors, ISensorCalibration[] sensorCalibrations, IDASHardware[] hardware, IDASHardware[] allDAS)` – Updates the cached items list by comparing/merging input data sources (current sensors, calibrations, and hardware). Returns `true` if the cached items list was modified as a result; `false` otherwise.
 								- **Properties (read-only)**:
 								  - `bool HasOutofDateCachedItems { get; }` – `true` if any cached item’s `DBTime` is newer than its `CacheTime`, indicating the cache is stale for that item.
 								  - `bool HasMissingSensors { get; }` – `true` if any cached item references a sensor that no longer exists in the current `sensors` data (inferred from `DBTime == DateTime.MinValue` and `ObjectType == "Sensor"`).
 								---
 								### **Invariants**
 								- `ICachedItem.DBTime == DateTime.MinValue` **iff** the item is no longer present in the database.
 								- `ICachedItem.CacheTime` must be ≤ `ICachedItem.DBTime` for items still in the database (i.e., `DBTime != DateTime.MinValue`), as caching occurs *after* DB persistence.
 								- `ICachedItemsListViewModel.CachedItems` must be populated *only* via `SetCachedItems(...)`, and its contents reflect the current state of the system’s sensors, calibrations, and hardware.
 								- `HasOutofDateCachedItems` is `true` **iff** at least one `ICachedItem` in `CachedItems` has `DBTime > CacheTime`.
 								- `HasMissingSensors` is `true` **iff** at least one `ICachedItem` in `CachedItems` has `ObjectType == "Sensor"` and `DBTime == DateTime.MinValue`.
 								- `SetCachedItems(...)` must process *all* provided arrays (`sensors`, `sensorCalibrations`, `hardware`, `allDAS`) to determine cache validity; partial processing is not permitted.
 								---
 								### **Dependencies**
 								- **Depends on**:
 								  - `DTS.Common.Base.IBaseView`, `DTS.Common.Base.IBaseViewModel` (base interfaces for view/view-model).
 								  - `DTS.Common.Interface.DataRecorders.ISensorData`, `ISensorCalibration` (for sensor and calibration metadata).
 								  - `DTS.Common.Interface.Sensors.IDASHardware` (for DAS hardware metadata).
 								- **Depended on by**:
 								  - UI layers implementing `ICachedItemsListView` (e.g., WPF/WinForms views).
 								  - Higher-level view models or controllers that coordinate test setup workflows and need to validate cached configurations.
 								  - Likely consumed by a test setup wizard or configuration manager (not visible in source, but implied by naming).
 								---
 								### **Gotchas**
 								- `HasMissingSensors` is **not** a general "missing items" flag—it specifically tracks *sensors* only (based on `ObjectType == "Sensor"`), per the `DBTime == DateTime.MinValue` convention. Missing hardware or calibration items are not covered by this property.
 								- `SetCachedItems(...)` accepts `IDASHardware[] hardware` and `IDASHardware[] allDAS`—the distinction between these two arrays is not clarified in the source (e.g., whether `hardware` is a subset of `allDAS`), making it unclear how overlap or precedence is handled.
 								- The return value of `SetCachedItems(...)` (`true`/`false`) indicates whether the `CachedItems` array *changed*, but does not indicate *why* (e.g., whether changes were due to staleness, missing items, or new items).
 								- No explicit thread-safety guarantees are defined; concurrent access to `CachedItems` or `SetCachedItems(...)` may require external synchronization.
 								- `ObjectType` values are not enumerated or validated—consumers must assume string literals (e.g., `"Sensor"`, `"Hardware"`) are used consistently elsewhere.