DP44/enriched-partialglm/Common/DTS.Common.Import/Interfaces.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Import/Interfaces/IPersistImport.cs Common/DTS.Common.Import/Interfaces/IParseImport.cs Common/DTS.Common.Import/Interfaces/IParseVariant.cs Common/DTS.Common.Import/Interfaces/IParseCSVTest.cs Common/DTS.Common.Import/Interfaces/IParseCSVSensor.cs Common/DTS.Common.Import/Interfaces/ICalibrationImport.cs Common/DTS.Common.Import/Interfaces/ILockImport.cs Common/DTS.Common.Import/Interfaces/IGroupImport.cs	2026-04-16T11:46:21.980624+00:00	zai-org/GLM-5-FP8	1	4d7a3572ba82cd30

DTS.Common.Import Interfaces Documentation

1. Purpose

This module defines the core abstraction layer for the DTS import subsystem. It provides interfaces for parsing import files (CSV, variants), persisting imported data, managing database locks during concurrent imports, handling sensor calibration records, and organizing sensors into test groups. These interfaces establish the contract between import data sources and the domain model, enabling extensibility for different import formats and workflows.

---

2. Public Interface

IPersistImport

Signature:

public interface IPersistImport
{
    void Save();
}

Behavior: Persists the imported data. Implementations are expected to commit the import state to a data store.

---

IParseImport

Signature:

public interface IParseImport
{
    ImportObject Parse(IEnumerable<string> importFiles);
}

Behavior: Accepts a collection of file paths and returns a populated ImportObject representing the parsed import data.

---

IParseVariant

Signature:

public interface IParseVariant
{
    string FileName { get; set; }
    void Parse(ref ImportObject importObject);
}

Behavior: Parses variant-specific import data. The FileName property indicates the source file. The Parse method modifies the passed ImportObject by reference.

---

IParseCSVTest

Signature:

public interface IParseCSVTest
{
    int Version { get; }
    void ParseVersion(CsvReader csvReader, TestSetupImportData tsid);
}

Behavior: Handles versioned CSV test setup parsing. Version indicates the parser version supported. ParseVersion reads from a CsvReader and populates TestSetupImportData.

---

IParseCSVSensor

Signature:

public interface IParseCSVSensor
{
    int Version { get; }
    void Initialize(ICalibrationImport import, ZeroMethodOptions zmOptions,
        IImportNotification importNotification, bool importCreateDynamicGroups,
        bool useIsoCodeFilterMapping, bool useZeroForUnfiltered);
    void ParseVersion(CSVImportTags.Tags field, string val, ParseParameters pp);
}

Behavior: Handles versioned CSV sensor parsing. Initialize must be called to configure calibration handling, zero method options, notification callbacks, and filtering options before parsing. ParseVersion processes individual field/value pairs using ParseParameters.

---

ICalibrationImport

Signature:

public interface ICalibrationImport
{
    SensorCalibration AddLinearCalRecordIfNeeded(SensorCalibration sc, bool savedIsProportional, bool savedRemoveOffset);
    SensorCalibration AddLinearZeroMethodIfNeeded(SensorCalibration sc, ZeroMethodType zeroMethodType, double zeroMethodStart, double zeroMethodEnd);
    SensorCalibration CheckForExcitationCalibration(SensorCalibration sc, double sensitivity, ExcitationVoltageOptions.ExcitationVoltageOption excitation, string EU);
}

Behavior: Manages sensor calibration during import. Methods conditionally add calibration records (linear calibration, zero method, excitation calibration) to a SensorCalibration object and return the modified instance.

---

ILockImport

Signature:

public interface ILockImport
{
    bool Contended { get; }
    void SetLock(ref ImportObject importObject, ref StringBuilder message);
    void FreeLock(ref ImportObject importObject);
    bool StealLock(bool proceed);
}

Behavior: Manages database locks during import operations. Contended indicates whether lock contention exists. SetLock acquires a lock and populates the message StringBuilder with any errors. FreeLock releases the lock. StealLock forcibly takes a lock if proceed is true.

---

IGroupImport

Signature:

public interface IGroupImport
{
    ParseParameters ParseParameters { get; set; }
    Tuple<TestTemplate, List<IGroup>> CreateGroups(List<SensorData> sensors, Dictionary<string, List<TsetSetupImportSensorInfo>> groupSensorLookup, TestTemplate testTemplate, bool createDynamicGroups, List<IGroup> staticGroups, Action<double> setProgress);
    Dictionary<string, List<TsetSetupImportSensorInfo>> GetGroupSensorLookup(List<SensorData> sensors, Dictionary<string, string> sensorGroupNameLookup, Dictionary<string, List<string>> groupNameSensorListLookup);
}

Behavior: Creates and manages sensor groupings during import. GetGroupSensorLookup builds a lookup dictionary mapping group names to sensor info. CreateGroups generates test groups (dynamic and/or static) and returns a tuple of the test template and group list. Progress reporting is supported via the setProgress callback.

---

3. Invariants

• IParseCSVSensor initialization ordering: The Initialize method must be called before ParseVersion can be meaningfully executed (inferred from parameter dependencies).
• ILockImport message sharing: The StringBuilder message parameter in SetLock is documented as shared between all types and accumulates all database lock errors.
• IParseVariant ref semantics: The ImportObject is passed by reference, implying the parser is expected to modify the existing object rather than replace it.
• ILockImport.Contended: Must return true if the internal collection of contended locks has any items (per source comment).

---

4. Dependencies

This module depends on:

• System.Collections.Generic (IEnumerable, Dictionary, List)
• System.Text (StringBuilder)
• System (Tuple, Action)
• CsvHelper (CsvReader)
• DTS.Common.Classes (TestSetupImportData)
• DTS.Common.Classes.Sensors (SensorData)
• DTS.Common.Enums (ExcitationVoltageOptions)
• DTS.Common.Enums.Sensors (ZeroMethodType, ZeroMethodOptions)
• DTS.Common.Import.ImportOptions (CSVImportTags, ParseParameters)
• DTS.Common.Interface.Groups.GroupList (IGroup)
• DTS.SensorDB (SensorCalibration)
• DataPROWin7.DataModel (TestTemplate, TsetSetupImportSensorInfo)

What depends on this module:

• Not determinable from the provided source files alone (these are interface definitions).

---

5. Gotchas

1. ILockImport error message accumulation: The message StringBuilder in SetLock is shared across all lock types. Errors accumulate, so callers should check the message contents after all lock operations complete rather than after each individual call.

2. FB 36740 reference: The ILockImport interface has a comment referencing "FB 36740" for database lock support. This appears to be a feature/bug tracking reference that may provide historical context for the locking implementation.

3. IParseVariant ref parameter: The use of ref for ImportObject in Parse is unusual for an interface pattern. Callers should be aware the object may be mutated in place.

4. IParseCSVSensor.Initialize complexity: The Initialize method accepts 6 parameters including flags for importCreateDynamicGroups, useIsoCodeFilterMapping, and useZeroForUnfiltered. The interaction between these flags and the parsing behavior is not documented in the interface.