init

enriched-qwen3-coder-next/Common/DTS.Common.Import/Factories.md

@@ -0,0 +1,110 @@
+---
+source_files:
+  - Common/DTS.Common.Import/Factories/CSVTestParserFactory.cs
+  - Common/DTS.Common.Import/Factories/DatabaseLocksFactory.cs
+  - Common/DTS.Common.Import/Factories/CSVSensorParserFactory.cs
+  - Common/DTS.Common.Import/Factories/SaveVariantFactory.cs
+  - Common/DTS.Common.Import/Factories/XmlParserFactory.cs
+generated_at: "2026-04-16T02:07:25.656251+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "23d838f43f91b04f"
+---
+
+# Import Factories Module Documentation
+
+## 1. Purpose  
+This module provides factory classes responsible for constructing and configuring domain-specific parsers and persistence handlers used during data import operations. It centralizes the logic for instantiating versioned CSV and XML parsers (for tests, sensors), database lock objects, and save handlers for various import entities (e.g., sensors, groups, test setups). Its role is to decouple object creation from consumption, enabling version-aware and context-aware instantiation of import components based on input data format, version, and configuration options.
+
+## 2. Public Interface  
+
+### `CSVTestParserFactory.CreateCSVParsers()`  
+**Signature:** `public static IParseCSVTest[] CreateCSVParsers()`  
+**Behavior:** Returns an array of versioned CSV test parsers (`Version0CSVTestParser`, `Version5CSVTestParser`, `Version6CSVTestParser`) implementing `IParseCSVTest`. Parsers are returned in version order (v0, v5, v6). No initialization parameters are required.
+
+### `DatabaseLocksFactory.Create(ImportObject, User, double)`  
+**Signature:** `public static List<ILockImport> Create(ImportObject importObject, User user, double strandedLockTimeoutMinutes)`  
+**Behavior:** Returns a list of database lock objects implementing `ILockImport`, conditionally instantiated based on the presence of data in the `ImportObject`. Lock types created include:
+- `LockImportTestSetups` (if `importObject.TestSetups()` is non-empty)
+- `LockImportSensors` (if `importObject.Sensors()` is non-empty)
+- `LockImportGroups` (if `importObject.StaticGroups()` is non-empty)  
+Each lock is initialized with the provided `user` and `strandedLockTimeoutMinutes`.
+
+### `CSVSensorParserFactory.CreateCSVParsers(...)`  
+**Signature:**  
+```csharp
+public static IReadOnlyDictionary<int, IParseCSVSensor> CreateCSVParsers(
+    ICalibrationImport import,
+    ZeroMethodOptions zmOptions,
+    IImportNotification importNotification,
+    bool importCreateDynamicGroups,
+    bool useISOCodeFilterMapping,
+    bool useZeroForUnfiltered)
+```  
+**Behavior:** Returns a dictionary mapping parser version numbers (int) to initialized `IParseCSVSensor` implementations (`Version0CSVSensorParser`, `Version2CSVSensorParser`, `Version3CSVSensorParser`, `Version4CSVSensorParser`). Each parser is initialized via its `Initialize(...)` method with the provided parameters. Keys are the parsers’ `Version` property values.
+
+### `SaveVariantFactory.CreateVariants(...)`  
+**Signature:**  
+```csharp
+public static List<IPersistImport> CreateVariants(
+    ImportObject importObject,
+    ImportNotification importNotification,
+    User user,
+    Func<bool> isCanceled,
+    bool showCheckoutButton)
+```  
+**Behavior:** Returns a list of `IPersistImport` implementations (save handlers) for various import entities, conditionally instantiated based on content in `importObject`. Includes:
+- `SaveCustomerDetails`, `SaveTestEngineerDetails`, `SaveLabDetails`, `SaveSensorModels`, `SaveUsers`, `SaveGlobalSettings`
+- `SaveCsvSourceSensor` or `SaveNonCsvSourceSensor` (based on `importObject.SourceFormat == ImportFormats.DTS_CSV`)
+- `SaveHardware`, `SaveGroupTemplates`, `SaveGroups`, `SaveCustomChannels`
+- `SaveTestSetup` and optionally `SaveCheckoutTestSetup` (if `importObject.TestSetups()` is non-empty and `showCheckoutButton` is true)  
+The `SaveTestSetup` name is modified by appending `Serialization.RDF.File.SUFFIX_RUNTEST`. If `showCheckoutButton` is true, a second `SaveCheckoutTestSetup` is created with `SUFFIX_CHECKOUT`. All handlers receive `isCanceled` and `importNotification`, and some receive `user` or other dependencies (e.g., `saveHardware`, `saveGroups`). A shared `PersistCalculator` instance is used to track progress totals.
+
+### `XmlParserFactory.CreateXMLParsers(...)`  
+**Signature:**  
+```csharp
+public static IEnumerable<IParseVariant> CreateXMLParsers(
+    string fileName,
+    IImportNotification importNotification,
+    Func<bool> isCanceled,
+    bool skipNormalizing)
+```  
+**Behavior:** Returns an enumeration of `IParseVariant` implementations based on the XML file version (determined via `FileUtils.GetImportXmlNode(...)`).  
+- For versions **< `FileUtils.DataPRO20XmlVersion`**: Calls `LessThan20XMLVersion(...)`, wrapping parsers in pre-20-specific adapters (e.g., `XMLPre20ParseSensors`, `XMLPre20ParseCalibrations`).  
+- For versions **≥ `FileUtils.DataPRO20XmlVersion`**: Calls `GreaterOrEqual20XMLVersion(...)`, using direct parsers (e.g., `XMLParseSensors`, `XMLParseCalibrations`).  
+Supported `TopLevelFields` include: `CustomChannels`, `CustomMainLocs`, `DASList`, `Sensors`, `Calibrations`, `GroupTemplates`, `Groups`, `TestSetups`, `LabDetails`, `CustomerDetails`, `TestEngineerDetails`, `Users`.  
+Parsers are initialized with `importNotification`, `isCanceled`, and version-specific parameters. Static properties `UIItems` and `ImportNotification` are set before parsing.
+
+## 3. Invariants  
+
+- **Parser versioning**: CSV parsers are versioned and returned in ascending order (e.g., v0, v5, v6 for tests; v0, v2, v3, v4 for sensors). XML parsers are selected based on a hard-coded version threshold (`FileUtils.DataPRO20XmlVersion`).
+- **Conditional instantiation**: All factories instantiate components only when corresponding data exists in `ImportObject` (e.g., `TestSetups().Any()`, `Sensors().Any()`), avoiding unnecessary object creation.
+- **Initialization consistency**: For `CSVSensorParserFactory`, all parsers are initialized with identical parameters and must be fully initialized before use (via `Initialize(...)`).
+- **Progress tracking**: `SaveVariantFactory` uses a shared `PersistCalculator` instance to accumulate total item counts across all save handlers.
+- **Checkout behavior**: `SaveCheckoutTestSetup` is created *only* if `showCheckoutButton` is true and `TestSetups()` is non-empty. The test setup name is modified using `Serialization.RDF.File.SUFFIX_RUNTEST`/`SUFFIX_CHECKOUT`.
+
+## 4. Dependencies  
+
+### This module depends on:
+- `DTS.Common.Import.Interfaces` (`IParseCSVTest`, `IParseCSVSensor`, `ILockImport`, `IPersistImport`, `IParseVariant`, `IImportNotification`, `ICalibrationImport`)
+- `DTS.Slice.Users` (`User`)
+- `DTS.Common.Import.DatabaseLocks` (`LockImportTestSetups`, `LockImportSensors`, `LockImportGroups`)
+- `DTS.Common.Import.Parsers.CSV` (`Version0CSVTestParser`, `Version5CSVTestParser`, `Version6CSVTestParser`, `Version0CSVSensorParser`, `Version2CSVSensorParser`, `Version3CSVSensorParser`, `Version4CSVSensorParser`)
+- `DTS.Common.Import.Persist` (`SaveCustomerDetails`, `SaveTestEngineerDetails`, `SaveLabDetails`, `SaveSensorModels`, `SaveCsvSourceSensor`, `SaveNonCsvSourceSensor`, `SaveUsers`, `SaveGlobalSettings`, `SaveHardware`, `SaveGroupTemplates`, `SaveGroups`, `SaveCustomChannels`, `SaveTestSetup`, `SaveCheckoutTestSetup`, `PersistCalculator`)
+- `DTS.Common.Import.XML` (XML parser types, e.g., `XMLParseSensors`, `XMLPre20ParseSensors`)
+- `DTS.Common.Enums.DBExport` (`TopLevelFields`)
+- `DTS.Common.Utils` (`FileUtils`, `Serialization.RDF.File`)
+- `System.Xml` (`XmlElement`, `XmlDocument`)
+
+### This module is depended upon by:
+- Import orchestration logic (e.g., `ImportService`, `ImportProcessor`) that consumes these factories to build import pipelines.  
+  *(Exact callers are not visible in the provided source but are implied by the factory pattern usage.)*
+
+## 5. Gotchas  
+
+- **Static state in `XmlParserFactory`**: The factory uses static properties (`UIItems`, `ImportNotification`) and a static field (`_isCancelled`) to pass context into parsers. This introduces thread-safety concerns if `CreateXMLParsers` is called concurrently.  
+- **`SaveVariantFactory` mutates `SaveCsvSourceSensor`/`SaveNonCsvSourceSensor`**: The `CurrentUser` property is assigned *after* construction, not via constructor. Callers must ensure this is set before use.  
+- **`SaveTestSetup.TestSetupName` modification**: The test setup name is modified *only* when `showCheckoutButton` is true, appending `SUFFIX_RUNTEST`. This behavior is tied to GM parse mode (per comment `//FB 38039`), but the condition is `showCheckoutButton`, not a dedicated flag.  
+- **XML version threshold**: The version split (`< 20` vs `>= 20`) is based on `FileUtils.DataPRO20XmlVersion`, but the constant itself is not defined in the provided source—its value must be verified externally.  
+- **`LessThan20XMLVersion` early exit**: Returns an empty list if `node == null || node.ChildNodes == null`, but does not log or signal an error. Callers must handle empty results gracefully.  
+- **`SaveGroups` and `SaveTestSetup` dependencies**: `SaveGroups` and `SaveTestSetup` constructors require `saveHardware` and `saveGroups` (respectively) as parameters, but these are instantiated *after* their dependencies in the factory method. This implies the factory method must construct them in dependency order (e.g., `saveHardware` before `saveGroups`, `saveGroups` before `saveTestSetup`).