Implementation:Apache Shardingsphere ShadowAlgorithmDeterminer IsShadow

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

Overview

Concrete tools for evaluating hint-based and column-based shadow algorithms to produce a boolean shadow routing decision, provided by the ShardingSphere shadow module.

Description

This implementation covers two determiner classes that serve as the evaluation bridge between shadow routing conditions and SPI shadow algorithm implementations:

HintShadowAlgorithmDeterminer is a final utility class (@NoArgsConstructor(access = AccessLevel.PRIVATE)) annotated with @HighFrequencyInvocation. Its single static method isShadow accepts a HintShadowAlgorithm<Comparable<?>>, a ShadowCondition, a ShadowRule, and a boolean useShadow flag. It constructs a PreciseHintShadowValue from the condition's table name, operation type, and the useShadow flag, then delegates to shadowAlgorithm.isShadow(), passing the full set of shadow table names from the rule.

ColumnShadowAlgorithmDeterminer is also a final utility class (@NoArgsConstructor(access = AccessLevel.PRIVATE)) annotated with @HighFrequencyInvocation. Its isShadow method accepts a ColumnShadowAlgorithm<Comparable<?>> and a ShadowCondition. It first creates a collection of PreciseColumnShadowValue instances, one per value in the shadow condition's column condition. It then iterates over these values with a conjunctive (AND) check: if the shadow condition's table name does not match the column condition's table name, or if the algorithm returns false for any value, the method returns false immediately. Only if all values pass does it return true.

Both classes are stateless and designed for maximum performance on the hot path of SQL routing.

Usage

These determiners are invoked by the shadow data source mappings retrievers:

• HintShadowAlgorithmDeterminer.isShadow is called by ShadowTableHintDataSourceMappingsRetriever and ShadowHintDataSourceMappingsRetriever
• ColumnShadowAlgorithmDeterminer.isShadow is called by ShadowColumnDataSourceMappingsRetriever

They are not intended for direct invocation by application code.

Code Reference

Source Location: HintShadowAlgorithmDeterminer

• Repository: Apache ShardingSphere
• File: features/shadow/core/src/main/java/org/apache/shardingsphere/shadow/route/determiner/HintShadowAlgorithmDeterminer.java
• Lines: 44-47

Signature: HintShadowAlgorithmDeterminer.isShadow

public static boolean isShadow(final HintShadowAlgorithm<Comparable<?>> shadowAlgorithm, final ShadowCondition shadowCondition, final ShadowRule shadowRule, final boolean useShadow)

Source Location: ColumnShadowAlgorithmDeterminer

• Repository: Apache ShardingSphere
• File: features/shadow/core/src/main/java/org/apache/shardingsphere/shadow/route/determiner/ColumnShadowAlgorithmDeterminer.java
• Lines: 44-51

Signature: ColumnShadowAlgorithmDeterminer.isShadow

public static boolean isShadow(final ColumnShadowAlgorithm<Comparable<?>> shadowAlgorithm, final ShadowCondition shadowCondition)

Import

import org.apache.shardingsphere.shadow.route.determiner.HintShadowAlgorithmDeterminer;
import org.apache.shardingsphere.shadow.route.determiner.ColumnShadowAlgorithmDeterminer;

I/O Contract

Inputs: HintShadowAlgorithmDeterminer.isShadow

Name	Type	Required	Description
shadowAlgorithm	HintShadowAlgorithm<Comparable<?>>	Yes	The hint shadow algorithm SPI implementation to evaluate
shadowCondition	ShadowCondition	Yes	Contains the table name (empty string for default) and operation type (HINT_MATCH for default, DML type for table-specific)
shadowRule	ShadowRule	Yes	Provides the full set of shadow table names passed to the algorithm for contextual evaluation
useShadow	boolean	Yes	The shadow flag from the hint value context indicating whether the session/statement is marked as shadow traffic

Outputs: HintShadowAlgorithmDeterminer.isShadow

Name	Type	Description
return	boolean	True if the hint shadow algorithm determines this statement should route to the shadow database, false otherwise

Inputs: ColumnShadowAlgorithmDeterminer.isShadow

Name	Type	Required	Description
shadowAlgorithm	ColumnShadowAlgorithm<Comparable<?>>	Yes	The column shadow algorithm SPI implementation to evaluate
shadowCondition	ShadowCondition	Yes	Contains the table name, operation type, and a ShadowColumnCondition with the column name, source table, and collection of column values to evaluate

Outputs: ColumnShadowAlgorithmDeterminer.isShadow

Name	Type	Description
return	boolean	True if the shadow condition's table name matches the column condition's table name AND the algorithm returns true for every value in the column condition; false otherwise

Usage Examples

Hint Algorithm Evaluation

// Evaluating a hint shadow algorithm for a table-specific condition:
HintShadowAlgorithm<Comparable<?>> algorithm = rule.getHintShadowAlgorithms("t_order").get(0);
ShadowCondition condition = new ShadowCondition("t_order", ShadowOperationType.INSERT);
boolean isShadow = HintShadowAlgorithmDeterminer.isShadow(algorithm, condition, rule, true);
// isShadow = true if the algorithm accepts the hint with useShadow=true

// Evaluating a hint shadow algorithm for the default (global) condition:
ShadowCondition defaultCondition = new ShadowCondition(); // tableName="", operationType=HINT_MATCH
boolean isDefaultShadow = HintShadowAlgorithmDeterminer.isShadow(
    defaultAlgorithm, defaultCondition, rule, hintValueContext.isShadow());

Column Algorithm Evaluation

// Evaluating a column shadow algorithm:
ColumnShadowAlgorithm<Comparable<?>> columnAlgorithm =
    rule.getColumnShadowAlgorithms(ShadowOperationType.INSERT, "t_order", "shadow_flag").get(0);
ShadowColumnCondition columnCondition =
    new ShadowColumnCondition("t_order", "shadow_flag", Collections.singletonList(true));
ShadowCondition condition =
    new ShadowCondition("t_order", ShadowOperationType.INSERT, columnCondition);

boolean isShadow = ColumnShadowAlgorithmDeterminer.isShadow(columnAlgorithm, condition);
// isShadow = true if:
//   1. condition.tableName ("t_order") equals columnCondition.table ("t_order")
//   2. The algorithm returns true for value "true"

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Shadow_Algorithm_Evaluation