Implementation:Apache Shardingsphere ShadowRule Constructor

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

Overview

Concrete runtime rule constructor that materializes shadow configuration into operational data structures for query-time routing, provided by the ShardingSphere shadow module.

Description

The ShadowRule constructor (lines 65-72) accepts a ShadowRuleConfiguration and performs four initialization steps to build the runtime data structures:

1. createShadowAlgorithms (lines 74-77): Converts the Map<String, AlgorithmConfiguration> into a Map<String, ShadowAlgorithm> by resolving each algorithm through TypedSPILoader.getService(ShadowAlgorithm.class, type, props). This eagerly instantiates all algorithm objects at construction time.

1. createDataSourceRules (lines 79-82): Converts the Collection<ShadowDataSourceConfiguration> into a CaseInsensitiveMap<String, ShadowDataSourceRule>. Each ShadowDataSourceRule is a simple pair of production and shadow data source names. The case-insensitive map ensures that data source lookups at query time are case-agnostic.

1. createTableRules (lines 84-88): Converts the Map<String, ShadowTableConfiguration> into a CaseInsensitiveMap<String, ShadowTableRule>. Each ShadowTableRule receives the table name, associated data source names, algorithm names, and the full algorithm map. The ShadowTableRule constructor (in ShadowTableRule.java, lines 46-51) classifies algorithms into:
   • hintShadowAlgorithmNames: Names of algorithms that are instances of HintShadowAlgorithm.
   • columnShadowAlgorithmNames: An EnumMap<ShadowOperationType, Collection<ShadowAlgorithmNameRule>> that indexes ColumnShadowAlgorithm instances by their operation type (INSERT, UPDATE, DELETE, SELECT) and shadow column name.

1. Attribute assembly (line 71): Creates a RuleAttributes wrapping a ShadowDataSourceMapperRuleAttribute, which exposes production-to-shadow data source mappings to the routing engine.

The defaultShadowAlgorithm field (line 68) is resolved by looking up the configured default algorithm name in the instantiated algorithms map. It may be null if no default is configured.

ShadowRule implements DatabaseRule and exposes numerous query-time methods annotated with @HighFrequencyInvocation: filterShadowTables(), getHintShadowAlgorithms(), getColumnShadowAlgorithms(), getShadowDataSourceMappings(), and others. These methods are designed for concurrent access and perform lookups against the pre-built maps.

Usage

Use the ShadowRule constructor (typically via ShadowRuleBuilder.build()) after the ShadowRuleConfiguration has been validated. The resulting rule object is installed in the database's rule registry and consulted by the shadow routing engine during query processing.

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: features/shadow/core/src/main/java/org/apache/shardingsphere/shadow/rule/ShadowRule.java
• Lines: 65-72

Signature

public ShadowRule(final ShadowRuleConfiguration ruleConfig) {
    configuration = ruleConfig;
    shadowAlgorithms = createShadowAlgorithms(ruleConfig.getShadowAlgorithms());
    defaultShadowAlgorithm = shadowAlgorithms.get(ruleConfig.getDefaultShadowAlgorithmName());
    dataSourceRules = createDataSourceRules(ruleConfig.getDataSources());
    tableRules = createTableRules(ruleConfig.getTables());
    attributes = new RuleAttributes(new ShadowDataSourceMapperRuleAttribute(dataSourceRules));
}

Import

import org.apache.shardingsphere.shadow.rule.ShadowRule;

I/O Contract

Inputs

Name	Type	Required	Description
ruleConfig	ShadowRuleConfiguration	Yes	Validated shadow rule configuration containing data sources (Collection<ShadowDataSourceConfiguration>), tables (Map<String, ShadowTableConfiguration>), shadow algorithms (Map<String, AlgorithmConfiguration>), and an optional default shadow algorithm name (String)

Outputs

Name	Type	Description
(constructed object)	ShadowRule	A fully initialized runtime rule with the following internal state:

Internal state after construction:

Field	Type	Description
configuration	ShadowRuleConfiguration	Reference to the original configuration
shadowAlgorithms	Map<String, ShadowAlgorithm>	Instantiated algorithm objects keyed by name
defaultShadowAlgorithm	ShadowAlgorithm (nullable)	The default shadow algorithm instance, or null if not configured
dataSourceRules	CaseInsensitiveMap<String, ShadowDataSourceRule>	Data source rules keyed by logical data source name
tableRules	CaseInsensitiveMap<String, ShadowTableRule>	Table rules keyed by table name, with classified algorithms
attributes	RuleAttributes	Rule attributes including data source mapper for the routing engine

Usage Examples

// Build a ShadowRule from a validated configuration
ShadowRuleConfiguration config = new ShadowRuleConfiguration();

// Add a data source mapping
ShadowDataSourceConfiguration dsConfig = new ShadowDataSourceConfiguration("shadow_ds", "ds_prod", "ds_shadow");
config.getDataSources().add(dsConfig);

// Add an algorithm
AlgorithmConfiguration algoConfig = new AlgorithmConfiguration("SQL_HINT", new Properties());
config.getShadowAlgorithms().put("sql-hint-algorithm", algoConfig);
config.setDefaultShadowAlgorithmName("sql-hint-algorithm");

// Add a table
ShadowTableConfiguration tableConfig = new ShadowTableConfiguration(
    Collections.singletonList("shadow_ds"), Collections.singletonList("sql-hint-algorithm"));
config.getTables().put("t_order", tableConfig);

// Construct the rule
ShadowRule shadowRule = new ShadowRule(config);

// Query-time usage
Collection<String> shadowTables = shadowRule.filterShadowTables(Arrays.asList("t_order", "t_user"));
// shadowTables contains ["t_order"]

Map<String, String> mappings = shadowRule.getShadowDataSourceMappings("t_order");
// mappings contains {"ds_prod" -> "ds_shadow"}

Optional<ShadowAlgorithm> defaultAlgo = shadowRule.getDefaultShadowAlgorithm();
// defaultAlgo contains the SQL_HINT algorithm instance

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Runtime_Rule_Object_Initialization

Requires Environment

• Environment:Apache_Shardingsphere_Java_Runtime_Environment