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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T02:07:25.656251+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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:

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:

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:

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).