110 lines
6.2 KiB
Markdown
110 lines
6.2 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common.SerializationPlus/Control/ReviewableAttribute.cs
|
||
- Common/DTS.Common.SerializationPlus/Control/IntervalSec.cs
|
||
generated_at: "2026-04-16T03:30:45.406675+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "1a23a7f0b15c8ac6"
|
||
---
|
||
|
||
# Documentation: `DTS.Slice.Control` Namespace – `ReviewableAttribute` and `IntervalSec`
|
||
|
||
---
|
||
|
||
## 1. Purpose
|
||
|
||
This module provides foundational types for representing *reviewable* attributes and time intervals within the DTS Slice Control subsystem. `ReviewableAttribute` is an abstract base class for attributes whose values are dynamically computed (e.g., for display in a UI review tab), while `IntervalSec` models a time interval with `Begin` and `End` times in seconds and supports conversion to/from a corresponding serialization type. Together, they support structured, dynamic data representation and time-based filtering or annotation in control/analysis workflows.
|
||
|
||
---
|
||
|
||
## 2. Public Interface
|
||
|
||
### `ReviewableAttribute` (abstract class)
|
||
|
||
- **`ReviewableAttribute(string name, DetermineValueString calculateValue)`**
|
||
Constructor. Initializes the attribute with a display `name` and a delegate `calculateValue` used to compute the `Value` on demand. Throws `ReviewableAttribute.Exception` on failure.
|
||
|
||
- **`public string Name { get; }`**
|
||
Read-only property returning the attribute’s display name (e.g., `"Temperature"`).
|
||
|
||
- **`public string Value { get; }`**
|
||
Read-only property that invokes the `CalculateValue` delegate to compute the current value. On delegate invocation failure, logs the exception and returns `"N/A"` (does *not* throw).
|
||
|
||
- **`public delegate string DetermineValueString();`**
|
||
Delegate type used for the `CalculateValue` property—represents a parameterless method returning a `string`.
|
||
|
||
- **`private DetermineValueString CalculateValue { get; set; }`**
|
||
Private property storing the delegate used to compute `Value`. Throws `ApplicationException` if accessed before initialization.
|
||
|
||
> **Note**: `ReviewableAttribute` inherits from `Exceptional` (from `DTS.Utilities`), implying exception-handling infrastructure is integrated (e.g., custom exception types like `ReviewableAttribute.Exception`).
|
||
|
||
---
|
||
|
||
### `IntervalSec` (concrete class)
|
||
|
||
- **`IntervalSec()`**
|
||
Parameterless constructor. Leaves `Begin` and `End` uninitialized (default to `0` due to `Property<double>` initialization).
|
||
|
||
- **`IntervalSec(double begin, double end)`**
|
||
Constructor initializing `Begin` and `End` to specified values. Throws generic `Exception` on failure.
|
||
|
||
- **`public double Begin { get; set; }`**
|
||
Read/write property for the interval’s start time in seconds.
|
||
|
||
- **`public double End { get; set; }`**
|
||
Read/write property for the interval’s end time in seconds.
|
||
|
||
- **`public static implicit operator Serialization.Test.IntervalSec(IntervalSec thisInterval)`**
|
||
Implicit conversion to `DTS.Serialization.Test.IntervalSec`, using `Begin` and `End`.
|
||
|
||
- **`public static implicit operator IntervalSec(Serialization.Test.IntervalSec thatInterval)`**
|
||
Implicit conversion from `DTS.Serialization.Test.IntervalSec`, constructing a new instance.
|
||
|
||
- **`public override bool Equals(object obj)`**
|
||
Memberwise equality test against another `IntervalSec`. Returns `false` if `obj` is `null` or not an `IntervalSec`.
|
||
|
||
- **`public override int GetHashCode()`**
|
||
Returns base hash code (no custom hashing logic—relies on `Exceptional` base behavior).
|
||
|
||
> **Note**: `IntervalSec` inherits from `Exceptional` and uses `Property<double>` (from `DTS.Utilities.DotNetProgrammingConstructs`) for its fields.
|
||
|
||
---
|
||
|
||
## 3. Invariants
|
||
|
||
- **`ReviewableAttribute`**
|
||
- `Name` is immutable after construction (only set in constructor).
|
||
- `CalculateValue` *must* be set during construction; accessing it before initialization throws `ApplicationException`.
|
||
- `Value` may return `"N/A"` on delegate failure but never throws (exceptions are logged and suppressed).
|
||
- `Name` and `CalculateValue` are required for valid initialization; partial initialization is disallowed.
|
||
|
||
- **`IntervalSec`**
|
||
- `Begin` and `End` default to `0` if not explicitly set (via `Property<double>` default value).
|
||
- No invariant enforces `Begin ≤ End`; callers must ensure logical consistency.
|
||
- Equality and hash code rely solely on `Begin` and `End` values.
|
||
|
||
---
|
||
|
||
## 4. Dependencies
|
||
|
||
### Dependencies *of* this module:
|
||
- `DTS.Utilities` (provides `Exceptional` base class and logging via `APILogger`)
|
||
- `DTS.Utilities.DotNetProgrammingConstructs` (provides `Property<T>` for property wrappers)
|
||
- `DTS.Serialization.Test.IntervalSec` (for implicit conversions in `IntervalSec`)
|
||
|
||
### Dependencies *on* this module:
|
||
- **`ReviewableAttribute`** is likely extended by concrete subclasses (not shown) to implement domain-specific attributes (e.g., for test result review).
|
||
- **`IntervalSec`** is used to model time ranges, likely in filtering or data selection logic (e.g., for time-windowed analysis). Its conversions suggest tight coupling with serialization layers.
|
||
|
||
---
|
||
|
||
## 5. Gotchas
|
||
|
||
- **`ReviewableAttribute.Value` suppresses exceptions silently**: If `CalculateValue` throws, the error is logged via `APILogger` but `Value` returns `"N/A"`. This may mask failures if callers do not check logs.
|
||
- **`CalculateValue` is not thread-safe**: No synchronization is evident; concurrent access to `Value` may yield inconsistent results if the delegate is stateful.
|
||
- **`IntervalSec` uses `double` for time**: Potential for floating-point precision issues (e.g., comparison errors); no tolerance-based equality is provided.
|
||
- **`Equals` does not handle `null` gracefully in the `that` cast**: While `obj` is checked for `null`, `that` is assigned via `as`, so `that` will be `null` if `obj` is not `IntervalSec`. The code then calls `that.Begin`, which will throw `NullReferenceException`.
|
||
- **Fix needed**: Add `&& that != null` before accessing `that.Begin`.
|
||
- **`GetHashCode()` is not overridden meaningfully**: Returns `base.GetHashCode()`, which may not align with `Equals` semantics (violating .NET best practices for value types).
|
||
- **`IntervalSec` parameterless constructor leaves properties uninitialized in a logical sense** (though technically initialized to `0`), which may cause unexpected behavior if used without explicit assignment. |