Principle:Apache Shardingsphere Configuration Object Conversion

Knowledge Sources	Apache ShardingSphere ShardingSphere Shadow Docs
Domains	Configuration_Management, Shadow_Testing
Last Updated	2026-02-10 00:00 GMT

Overview

Converting between YAML representation objects and domain configuration objects using a bidirectional swapper pattern.

Description

Configuration Object Conversion is a design pattern in which a dedicated swapper class provides bidirectional transformation between two parallel object hierarchies: the YAML representation layer and the domain configuration layer. The YAML layer consists of classes annotated for deserialization (e.g., YamlShadowRuleConfiguration), while the domain layer consists of plain configuration classes used by the rule engine (e.g., ShadowRuleConfiguration).

The separation exists because:

• Persistence Concerns: YAML classes carry annotations for serialization, governance node mapping, and other infrastructure concerns that do not belong in domain configuration objects.
• Structural Differences: The YAML representation may use maps keyed by name for data sources, while the domain model may use a flat collection of named configuration objects. The swapper handles these structural translations.
• Default Value Application: During conversion, the swapper can apply default values (e.g., assigning a default data source to tables that omit one, or assigning a default algorithm to tables that lack explicit algorithm references).
• Decoupled Evolution: The YAML format and the domain model can evolve independently, with the swapper absorbing compatibility differences.

The swapper interface defines two core methods:

• swapToObject: Converts from YAML representation to domain configuration. This is the direction used during configuration loading.
• swapToYamlConfiguration: Converts from domain configuration back to YAML representation. This is the direction used when persisting configuration changes.

A rule-level swapper typically delegates to sub-swappers for data source configurations, table configurations, and algorithm configurations, creating a compositional conversion tree.

Usage

Use Configuration Object Conversion at the boundary between the YAML parsing layer and the rule engine. After YAML deserialization produces a YamlShadowRuleConfiguration, the swapper converts it to a ShadowRuleConfiguration that the rule builder and checker can consume. Conversely, when the system needs to persist the current rule configuration (e.g., after a DistSQL change), the swapper converts the domain object back to YAML form.

Theoretical Basis

The bidirectional swapper pattern follows this logic:

FUNCTION swapToObject(yamlConfig):
    result = new DomainConfiguration()

    // Convert data sources: YAML map entries -> domain collection
    FOR EACH (name, yamlDs) IN yamlConfig.dataSources:
        result.dataSources.add(new DataSourceConfig(name, yamlDs.production, yamlDs.shadow))

    // Convert tables: YAML map -> domain map via sub-swapper
    FOR EACH (tableName, yamlTable) IN yamlConfig.tables:
        result.tables.put(tableName, tableSwapper.swapToObject(yamlTable))

    // Convert algorithms: YAML map -> domain map via sub-swapper
    FOR EACH (algoName, yamlAlgo) IN yamlConfig.shadowAlgorithms:
        result.algorithms.put(algoName, algorithmSwapper.swapToObject(yamlAlgo))

    // Apply defaults: assign default data source and algorithm to tables
    applyDefaultDataSource(result.tables, result.dataSources)
    applyDefaultAlgorithm(result.tables, yamlConfig.defaultShadowAlgorithmName)

    result.defaultShadowAlgorithmName = yamlConfig.defaultShadowAlgorithmName
    RETURN result
END FUNCTION

Key design aspects:

• Compositional Sub-Swappers: The top-level swapper delegates to YamlShadowDataSourceConfigurationSwapper, YamlShadowTableConfigurationSwapper, and YamlAlgorithmConfigurationSwapper for their respective sub-structures.
• Default Propagation: When only one data source mapping exists, it is automatically assigned to any table that does not specify a data source. Similarly, the default shadow algorithm is assigned to tables without explicit algorithm references.
• Ordered SPI Integration: The swapper declares an order value and a rule tag name, allowing the infrastructure to discover and apply swappers in the correct sequence across multiple rule types.

Related Pages

Implemented By

• Implementation:Apache_Shardingsphere_YamlShadowRuleConfigurationSwapper_SwapToObject