Implementation:Apache Shardingsphere DatabaseMetaDataChangedListener OnChange

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

Overview

Concrete tool for filtering incoming data change events by path matching and active version validation before dispatching to type-specific handlers, provided by the ShardingSphere cluster mode module.

Description

The onChange method on DatabaseMetaDataChangedListener is the central event processing entry point for all database-scoped configuration changes in cluster mode. It implements the DataChangedEventListener interface and is invoked by the distributed registry watcher whenever a node under the database metadata tree is modified.

The method executes a multi-stage filtering pipeline:

1. Database name extraction: Uses NodePathSearcher.find() with DatabaseMetaDataNodePath.createDatabaseSearchCriteria() to extract the database name from the event key. If the key does not match a database metadata path pattern, the method returns immediately.
2. Cache invalidation: Calls OrderedServicesCache.clearCache() to invalidate any cached SPI service orderings, ensuring that the configuration change is reflected in subsequent service lookups.
3. Handler iteration and subscription check: Iterates through the registered handler list and calls the private isSubscribed method to determine if each handler should process the event. The handler list is constructed in the constructor and includes (in order): SchemaChangedHandler, TableChangedHandler, ViewChangedHandler, StorageUnitChangedHandler, StorageNodeChangedHandler, NamedRuleItemConfigurationChangedHandler, UniqueRuleItemConfigurationChangedHandler, RuleTypeConfigurationChangedHandler.
4. Active version validation: For ADDED and UPDATED events that match a handler, the method creates a new ActiveVersionChecker and calls checkSame(event) to verify that the version in the event's value matches the current active version in the repository. If they do not match, the event is stale and the method returns without processing.
5. Handler dispatch: If the event passes all filters, handler.handle(databaseName, event) is called and the method returns (first-match-wins).

The isSubscribed method applies different matching logic depending on the handler type:

• DatabaseLeafValueChangedHandler: For ADDED/UPDATED events, checks if the event key is the active version path for the handler's subscribed node path. For other event types, checks if the key matches the subscribed path pattern but is not the active version path or versions directory path.
• DatabaseNodeValueChangedHandler: Checks if the event key matches the handler's subscribed node path pattern.

Usage

This listener is registered during cluster mode initialization and processes all events from the database metadata watch path. It handles:

• Rule configuration item changes (sharding tables, algorithms, etc.)
• Schema creation and deletion events
• Table and view metadata changes
• Storage unit and storage node changes

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: mode/type/cluster/core/src/main/java/org/apache/shardingsphere/mode/manager/cluster/dispatch/listener/type/DatabaseMetaDataChangedListener.java
• Lines: 67-85 (onChange method), 87-101 (isSubscribed method)

Signature

@Override
public void onChange(final DataChangedEvent event)

Import

import org.apache.shardingsphere.mode.manager.cluster.dispatch.listener.type.DatabaseMetaDataChangedListener;

I/O Contract

Inputs

Name	Type	Required	Description
event	DataChangedEvent	Yes	The data change event from the distributed registry. Contains the registry path (key), the new value, and the change type (ADDED, UPDATED, DELETED, or IGNORED).

Outputs

Name	Type	Description
return	void	No return value. The method either dispatches the event to a handler or silently discards it based on the filtering criteria.

Usage Examples

// The listener is constructed during cluster initialization with the ContextManager
DatabaseMetaDataChangedListener listener = new DatabaseMetaDataChangedListener(contextManager);

// The registry watcher calls onChange when a database metadata node changes
// For example, when an active version pointer is updated:
DataChangedEvent event = new DataChangedEvent(
    "/metadata/my_db/rules/sharding/tables/t_order/active_version",
    "3",
    DataChangedEvent.Type.UPDATED
);
listener.onChange(event);

// Internal flow:
// 1. Extract "my_db" from the path
// 2. Clear ordered services cache
// 3. Find matching handler (NamedRuleItemConfigurationChangedHandler matches)
// 4. ActiveVersionChecker.checkSame(event) verifies version "3" is still current
// 5. handler.handle("my_db", event) is called to process the change

// Example of a stale event being filtered out:
// Suppose version 4 has already been written, but event for version 3 arrives late
DataChangedEvent staleEvent = new DataChangedEvent(
    "/metadata/my_db/rules/sharding/tables/t_order/active_version",
    "3",  // stale version
    DataChangedEvent.Type.UPDATED
);
listener.onChange(staleEvent);
// ActiveVersionChecker queries the repository and finds active_version = 4
// Since "3" != "4", the event is discarded (logged as warning)

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Event_Listener_Filtering