Principle:Apache Shardingsphere Runtime Rule Object Initialization

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

Overview

Initializing runtime rule objects that materialize configuration into operational data structures for query-time routing decisions.

Description

Runtime Rule Object Initialization is the process of transforming a validated, static configuration object into a live rule object with fully materialized operational data structures. While the configuration object is a simple data container holding names, references, and property maps, the runtime rule object resolves all references, instantiates algorithm instances, and builds lookup structures optimized for query-time performance.

The initialization process involves several transformation steps:

• Algorithm Instantiation: Algorithm configuration entries (type name plus properties) are resolved through SPI to actual algorithm instances. Each AlgorithmConfiguration is transformed into a live ShadowAlgorithm object via TypedSPILoader.getService().
• Data Source Rule Construction: Data source configuration entries (pairs of production and shadow data source names) are transformed into ShadowDataSourceRule objects stored in a case-insensitive map for efficient lookup.
• Table Rule Construction: Table configuration entries are transformed into ShadowTableRule objects. During this transformation, each table rule classifies its associated algorithms into hint-based and column-based categories, and organizes column-based algorithms by operation type (INSERT, UPDATE, DELETE, SELECT) for efficient query-time dispatch.
• Rule Attribute Assembly: The rule assembles its attributes, including a ShadowDataSourceMapperRuleAttribute that exposes the production-to-shadow data source mappings for use by the routing engine.

The resulting rule object is immutable after construction and is designed for high-frequency, concurrent access during query processing. Internal maps use case-insensitive keys to support database-agnostic table and data source name matching.

Usage

Use Runtime Rule Object Initialization when constructing a ShadowRule from a validated ShadowRuleConfiguration. This occurs during database initialization, after configuration changes via DistSQL, or during rule rebuilds triggered by governance events. The initialized rule object is then installed in the database's rule registry and consulted by the shadow routing engine during every query that targets shadow-enabled tables.

Theoretical Basis

The runtime rule initialization pattern follows this logic:

FUNCTION initializeRule(ruleConfig):
    // Step 1: Instantiate algorithm objects from configuration
    algorithms = {}
    FOR EACH (name, algoConfig) IN ruleConfig.shadowAlgorithms:
        algorithms[name] = SPILoader.getService(ShadowAlgorithm, algoConfig.type, algoConfig.props)

    // Step 2: Build data source rules
    dataSourceRules = CaseInsensitiveMap()
    FOR EACH dsConfig IN ruleConfig.dataSources:
        dataSourceRules[dsConfig.name] = new DataSourceRule(dsConfig.production, dsConfig.shadow)

    // Step 3: Build table rules with algorithm classification
    tableRules = CaseInsensitiveMap()
    FOR EACH (tableName, tableConfig) IN ruleConfig.tables:
        tableRule = new TableRule(tableName, tableConfig.dataSourceNames, tableConfig.algorithmNames, algorithms)
        // TableRule constructor internally classifies algorithms:
        //   - HintShadowAlgorithm instances -> hintShadowAlgorithmNames
        //   - ColumnShadowAlgorithm instances -> columnShadowAlgorithmNames[operationType]
        tableRules[tableName] = tableRule

    // Step 4: Resolve default algorithm
    defaultAlgorithm = algorithms[ruleConfig.defaultShadowAlgorithmName]

    // Step 5: Assemble rule attributes
    attributes = new RuleAttributes(new DataSourceMapperAttribute(dataSourceRules))

    RETURN new ShadowRule(ruleConfig, algorithms, defaultAlgorithm, dataSourceRules, tableRules, attributes)
END FUNCTION

Key design aspects:

• Eager Resolution: All SPI lookups and algorithm instantiations happen at construction time, not at query time. This ensures that query-time routing incurs no SPI overhead.
• Case-Insensitive Maps: Data source and table rule maps use case-insensitive keys (CaseInsensitiveMap) to match SQL identifiers regardless of casing.
• Algorithm Classification: The ShadowTableRule constructor partitions algorithms into hint-based and column-based categories, and further indexes column-based algorithms by operation type using an EnumMap. This allows O(1) lookup of applicable algorithms for a given query type.
• Immutable After Construction: The rule object's internal state is fully determined at construction time and does not change thereafter, making it safe for concurrent access.

Related Pages

Implemented By

• Implementation:Apache_Shardingsphere_ShadowRule_Constructor