Principle:Apache Shardingsphere SPI Rule Building

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

Overview

Using the SPI-based rule builder framework to construct rule objects from validated configuration in a pluggable manner.

Description

SPI Rule Building is a design pattern in which the construction of runtime rule objects is delegated to pluggable builder classes discovered through Java's Service Provider Interface (SPI) mechanism. Rather than hard-coding the creation of specific rule types in a central factory, each rule module provides its own DatabaseRuleBuilder implementation that the framework discovers and invokes automatically.

The pattern works as follows:

• Builder Registration: Each rule module declares a DatabaseRuleBuilder implementation in its SPI service file. The builder is annotated with @SingletonSPI, indicating that only one instance is needed per type.
• Type Association: The builder declares which RuleConfiguration type it handles via getTypeClass(). The framework matches incoming configuration objects to their corresponding builder by configuration class type.
• Ordered Execution: Each builder declares an order value via getOrder(). When multiple rules are configured, their builders are invoked in order, allowing rules that depend on other rules to be built after their dependencies.
• Uniform Interface: All builders implement the same build() method signature, receiving the rule configuration along with contextual information (database name, protocol type, resource metadata, previously built rules, and the compute node instance context). This uniform interface allows the framework to treat all rule builders interchangeably.
• Delegation to Rule Constructor: In practice, many builders simply delegate to the rule class constructor, passing the configuration object. The builder serves as the SPI discovery point, while the actual construction logic lives in the rule class itself.

This architecture enables new rule types to be added without modifying the core framework. Adding a new rule requires only providing a new builder implementation and registering it via SPI.

Usage

Use SPI Rule Building when the system loads database configurations and needs to construct the corresponding rule objects. The framework iterates over all configured rule types, finds the matching builder for each, and invokes it. This happens during database initialization and when rules are dynamically added or modified via DistSQL.

Theoretical Basis

The SPI-based rule building pattern follows this logic:

FUNCTION buildRules(ruleConfigurations, databaseContext):
    builders = SPILoader.loadAll(DatabaseRuleBuilder)
    sortByOrder(builders)
    builtRules = []

    FOR EACH ruleConfig IN ruleConfigurations:
        builder = findBuilder(builders, ruleConfig.getClass())
        rule = builder.build(
            ruleConfig,
            databaseContext.name,
            databaseContext.protocolType,
            databaseContext.resourceMetaData,
            builtRules,
            databaseContext.computeNodeInstanceContext
        )
        builtRules.add(rule)

    RETURN builtRules
END FUNCTION

// Each module provides:
CLASS ShadowRuleBuilder IMPLEMENTS DatabaseRuleBuilder<ShadowRuleConfiguration>:
    FUNCTION build(ruleConfig, ...):
        RETURN new ShadowRule(ruleConfig)

    FUNCTION getOrder(): RETURN SHADOW_ORDER
    FUNCTION getTypeClass(): RETURN ShadowRuleConfiguration.class
END CLASS

Key design aspects:

• Loose Coupling: The core framework has no compile-time dependency on any specific rule module. All rule modules are discovered at runtime through SPI.
• Order Determinism: The getOrder() method ensures that rules are built in a deterministic sequence, respecting inter-rule dependencies.
• Configuration Type Dispatch: The getTypeClass() method enables type-safe dispatch from configuration to builder without downcasting.

Related Pages

Implemented By

• Implementation:Apache_Shardingsphere_ShadowRuleBuilder_Build