Implementation:Apache Shardingsphere RuleItemConfigurationChangedHandler Handle

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

Overview

Concrete tool for dispatching filtered change events to the rule item manager based on event type, provided by the ShardingSphere cluster mode module.

Description

The handle method on RuleItemConfigurationChangedHandler is the abstract base handler that dispatches rule item configuration changes to the DatabaseRuleItemManager. It is declared as a final method in the abstract class, meaning subclasses (NamedRuleItemConfigurationChangedHandler, UniqueRuleItemConfigurationChangedHandler) inherit the dispatch logic without overriding it.

The method performs the following steps:

1. Path resolution: Uses a RuleItemChangedNodePathBuilder to parse the event's registry key into a DatabaseRuleNodePath object. This builder analyzes the event key and the event type to construct a path that identifies the specific rule type, item type, and item name. If the key does not correspond to a recognized rule item pattern, an empty Optional is returned and the method exits.
2. Event type routing: Switches on the event's type to determine the appropriate action:
   • ADDED / UPDATED: Calls contextManager.getMetaDataContextManager().getDatabaseRuleItemManager().alter(databaseRuleNodePath). The alter method on DatabaseRuleItemManager loads the SPI-based RuleItemConfigurationChangedProcessor for the rule type and item type, reads the new configuration content from the versioned repository, mutates the current RuleConfiguration, and triggers a rule rebuild via DatabaseRuleConfigurationManager.refresh().
   • DELETED: Calls contextManager.getMetaDataContextManager().getDatabaseRuleItemManager().drop(databaseRuleNodePath). The drop method loads the appropriate processor, removes the item from the current configuration, and triggers a rebuild (or rule removal if the configuration becomes empty).
   • Default: No action is taken for IGNORED or other event types.

This class implements the DatabaseLeafValueChangedHandler interface, which means the listener layer uses active version path matching to determine subscription. The handler's getSubscribedNodePath method (inherited from subclasses) provides the path pattern used for subscription matching.

The three concrete subclasses registered in DatabaseMetaDataChangedListener are:

• NamedRuleItemConfigurationChangedHandler: Subscribes to named rule item paths (items with specific names under a rule type).
• UniqueRuleItemConfigurationChangedHandler: Subscribes to unique (singleton) rule item paths.
• RuleTypeConfigurationChangedHandler: Subscribes to rule type-level paths (handles entire rule type deletion).

Usage

This handler is invoked by DatabaseMetaDataChangedListener.onChange() when an event matches a rule item configuration path and passes active version validation. It processes:

• Sharding table rule additions and modifications
• Algorithm configuration changes
• Key generator and auditor changes
• Encryption column rule changes
• Read-write splitting and shadow rule item changes
• Any SPI-registered rule item type

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: mode/type/cluster/core/src/main/java/org/apache/shardingsphere/mode/manager/cluster/dispatch/handler/database/rule/RuleItemConfigurationChangedHandler.java
• Lines: 40-56

Signature

@Override
public final void handle(final String databaseName, final DataChangedEvent event)

Import

import org.apache.shardingsphere.mode.manager.cluster.dispatch.handler.database.rule.RuleItemConfigurationChangedHandler;

I/O Contract

Inputs

Name	Type	Required	Description
databaseName	String	Yes	The name of the database extracted from the event key by the listener. Identifies which database's rule configuration should be modified.
event	DataChangedEvent	Yes	The data change event containing the registry path (key), the new value, and the change type. The key is parsed to determine the rule type and item name.

Outputs

Name	Type	Description
return	void	No return value. The method delegates to DatabaseRuleItemManager.alter() or DatabaseRuleItemManager.drop() based on the event type. Throws SQLWrapperException if the downstream rule rebuild fails.

Usage Examples

// The handler is called by DatabaseMetaDataChangedListener after event filtering
// This is internal framework code, not typically called directly

// Example: handling an UPDATED event for a sharding table rule
DataChangedEvent event = new DataChangedEvent(
    "/metadata/my_db/rules/sharding/tables/t_order/active_version",
    "3",
    DataChangedEvent.Type.UPDATED
);

// The listener calls:
handler.handle("my_db", event);

// Internally:
// 1. ruleItemChangedNodePathBuilder.build("my_db", event.getKey(), event.getType())
//    -> Optional<DatabaseRuleNodePath> with ruleType="sharding", itemType="tables", name="t_order"
//
// 2. Switch on UPDATED:
//    contextManager.getMetaDataContextManager().getDatabaseRuleItemManager().alter(databaseRuleNodePath)
//      -> TypedSPILoader.getService(RuleItemConfigurationChangedProcessor.class, new RuleChangedItemType("sharding", "tables"))
//      -> processor.swapRuleItemConfiguration("t_order", yamlContent)
//      -> processor.changeRuleItemConfiguration("t_order", currentConfig, newItemConfig)
//      -> databaseRuleConfigManager.refresh("my_db", currentConfig, true)

// Example: handling a DELETED event for a sharding algorithm
DataChangedEvent deleteEvent = new DataChangedEvent(
    "/metadata/my_db/rules/sharding/algorithms/my_hash_mod",
    "",
    DataChangedEvent.Type.DELETED
);

handler.handle("my_db", deleteEvent);

// Internally:
// 1. Parse path -> ruleType="sharding", itemType="algorithms", name="my_hash_mod"
// 2. Switch on DELETED:
//    contextManager.getMetaDataContextManager().getDatabaseRuleItemManager().drop(databaseRuleNodePath)
//      -> processor.dropRuleItemConfiguration("my_hash_mod", currentConfig)
//      -> databaseRuleConfigManager.refresh("my_db", currentConfig, !isEmpty)

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Change_Handler_Dispatch