Implementation:Apache Shardingsphere ShadowRuleConfigurationChecker Check

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

Overview

Concrete validator for ensuring shadow rule configuration correctness and referential integrity, provided by the ShardingSphere shadow module.

Description

ShadowRuleConfigurationChecker is a final class that implements DatabaseRuleConfigurationChecker<ShadowRuleConfiguration>. Its check() method performs five sequential validation stages on a ShadowRuleConfiguration:

1. checkShadowAlgorithms (line 58-59): Iterates over all declared shadow algorithm configurations and verifies that each resolves to a valid SPI service via TypedSPILoader.checkService(ShadowAlgorithm.class, type, props).
2. checkDefaultShadowAlgorithm (lines 62-67): If a default shadow algorithm name is specified, verifies that the named algorithm exists and is of type "SQL_HINT". Throws NotImplementHintShadowAlgorithmException if the constraint is violated.
3. checkDataSources (lines 69-74): For each shadow data source configuration, verifies that both the production data source name and the shadow data source name exist in the provided dataSourceMap. Throws MissingRequiredProductionDataSourceException or MissingRequiredShadowDataSourceException if not found.
4. checkShadowTableDataSourcesReferences (lines 76-83): Collects the names of all declared shadow data source mappings, then verifies that every data source name referenced by every shadow table configuration exists in that set. Throws ShadowDataSourceMappingNotFoundException for missing references.
5. checkShadowTableAlgorithmsReferences (lines 85-91): For each shadow table, verifies that the table has at least one shadow algorithm name and that every referenced algorithm name exists in the declared shadow algorithms map. Throws MissingRequiredAlgorithmException for violations.

The class also implements getRequiredDataSourceNames() (lines 94-101), which collects all production and shadow data source names from the configuration for use by the infrastructure framework.

A companion class, ShadowRuleConfigurationEmptyChecker, implements DatabaseRuleConfigurationEmptyChecker and checks whether the configuration is substantively empty (no data sources or no tables).

Usage

Use ShadowRuleConfigurationChecker.check() after the swapper has produced a ShadowRuleConfiguration and before the rule builder constructs the ShadowRule. The framework discovers this checker via SPI and invokes it automatically during database initialization or rule modification.

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: features/shadow/core/src/main/java/org/apache/shardingsphere/shadow/checker/ShadowRuleConfigurationChecker.java
• Lines: 50-56

Signature

@Override
public void check(final String databaseName, final ShadowRuleConfiguration ruleConfig,
                  final Map<String, DataSource> dataSourceMap, final Collection<ShardingSphereRule> builtRules) {
    checkShadowAlgorithms(ruleConfig.getShadowAlgorithms());
    checkDefaultShadowAlgorithm(ruleConfig.getDefaultShadowAlgorithmName(), ruleConfig.getShadowAlgorithms());
    checkDataSources(ruleConfig.getDataSources(), dataSourceMap, databaseName);
    checkShadowTableDataSourcesReferences(ruleConfig.getTables(), ruleConfig.getDataSources());
    checkShadowTableAlgorithmsReferences(ruleConfig.getTables(), ruleConfig.getShadowAlgorithms(), databaseName);
}

Import

import org.apache.shardingsphere.shadow.checker.ShadowRuleConfigurationChecker;

I/O Contract

Inputs

Name	Type	Required	Description
databaseName	String	Yes	Name of the database being configured, used in exception messages
ruleConfig	ShadowRuleConfiguration	Yes	The shadow rule configuration to validate
dataSourceMap	Map<String, DataSource>	Yes	Map of available data source names to DataSource instances in the current database
builtRules	Collection<ShardingSphereRule>	Yes	Collection of previously built rules (not used by shadow checker but required by interface)

Outputs

Name	Type	Description
return	void	No return value; throws specific exceptions on validation failure

Exceptions thrown:

Exception	Condition
(SPI check failure)	A shadow algorithm type is not a registered SPI service
NotImplementHintShadowAlgorithmException	Default shadow algorithm is specified but is not of type SQL_HINT
MissingRequiredProductionDataSourceException	A production data source name does not exist in the data source map
MissingRequiredShadowDataSourceException	A shadow data source name does not exist in the data source map
ShadowDataSourceMappingNotFoundException	A table references a data source name not declared in shadow data source mappings
MissingRequiredAlgorithmException	A table has no algorithm names, or references an algorithm name not declared in shadow algorithms

Usage Examples

// Validate a shadow rule configuration before building the rule
ShadowRuleConfigurationChecker checker = new ShadowRuleConfigurationChecker();

Map<String, DataSource> dataSourceMap = new LinkedHashMap<>();
dataSourceMap.put("ds_prod", productionDataSource);
dataSourceMap.put("ds_shadow", shadowDataSource);

Collection<ShardingSphereRule> builtRules = Collections.emptyList();

// This will throw an exception if validation fails
checker.check("my_database", shadowRuleConfig, dataSourceMap, builtRules);

// If no exception is thrown, the configuration is valid and can be used to build a ShadowRule
ShadowRule rule = new ShadowRule(shadowRuleConfig);

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Configuration_Validation