Principle:Apache Shardingsphere Change Handler Dispatch
| Knowledge Sources | |
|---|---|
| Domains | Configuration_Management, Distributed_Systems |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Change handler dispatch is the mechanism that routes filtered data change events to type-specific handlers capable of resolving the event to the correct rule item processor and applying the configuration change.
Description
After an event passes through listener filtering and active version validation, it must be directed to a handler that understands the specific type of configuration change represented by the event. Change handler dispatch accomplishes this by:
- Path-based resolution: The handler receives the database name and the full event, then uses a RuleItemChangedNodePathBuilder to parse the event's registry key into a structured DatabaseRuleNodePath. This path object encodes the rule type (e.g., sharding, encrypt, readwrite_splitting), the item type (e.g., tables, algorithms, key_generators), and the specific item name.
- Event type routing: Based on the event's type (ADDED, UPDATED, or DELETED), the handler invokes the appropriate operation on the DatabaseRuleItemManager:
- ADDED and UPDATED events trigger an alter operation, which loads the new configuration content from the versioned repository, finds the appropriate RuleItemConfigurationChangedProcessor via the SPI mechanism, and applies the change to the current rule configuration.
- DELETED events trigger a drop operation, which removes the rule item from the current configuration.
- SPI-driven processing: The actual configuration mutation is delegated to RuleItemConfigurationChangedProcessor implementations discovered through the SPI (Service Provider Interface) mechanism. Each processor is keyed by a RuleChangedItemType composed of the rule type and item type, allowing the system to automatically route changes to the correct processor without hardcoded type checks.
This design follows the Chain of Responsibility pattern at the handler level (multiple handler types registered in the listener) combined with the Strategy pattern at the processor level (SPI-discovered processors for each rule item type).
The handler types in ShardingSphere include:
- NamedRuleItemConfigurationChangedHandler: Handles changes to named rule items (e.g., specific sharding table rules identified by name).
- UniqueRuleItemConfigurationChangedHandler: Handles changes to unique rule items (singleton items within a rule type).
- RuleTypeConfigurationChangedHandler: Handles changes at the rule type level (e.g., entire rule type deletion).
Usage
Change handler dispatch is invoked automatically when a filtered event is forwarded from the listener layer. It applies to:
- Any alteration to a specific rule item (adding a sharding algorithm, modifying an encryption column rule).
- Deletion of rule items or entire rule types.
- Structural changes to rule configuration that require SPI-based processor resolution.
Theoretical Basis
The dispatch mechanism follows a parse-route-delegate pattern:
PROCEDURE handle(database_name, event):
// Step 1: Parse the event key into a structured path
rule_node_path = parse_rule_node_path(database_name, event.key, event.type)
IF rule_node_path IS NOT PRESENT:
RETURN // event key does not match any known rule item pattern
// Step 2: Route based on event type
SWITCH event.type:
CASE ADDED, UPDATED:
// Step 3a: Delegate to alter operation
rule_item_manager.alter(rule_node_path)
// -> Loads SPI processor for (rule_type, item_type)
// -> Reads versioned content from repository
// -> Mutates current RuleConfiguration
// -> Triggers rule rebuild via DatabaseRuleConfigurationManager
BREAK
CASE DELETED:
// Step 3b: Delegate to drop operation
rule_item_manager.drop(rule_node_path)
// -> Loads SPI processor for (rule_type, item_type)
// -> Removes item from current RuleConfiguration
// -> Triggers rule rebuild if configuration is non-empty
BREAK
DEFAULT:
// No action for IGNORED or unknown types
BREAK
END PROCEDURE
The use of SPI for processor discovery means that new rule types can be added to the system without modifying the handler dispatch code. A new rule module only needs to provide RuleItemConfigurationChangedProcessor implementations with the appropriate type keys, and the dispatch mechanism will automatically route events to them.