Principle:Apache Shardingsphere Event Listener Registration
| Knowledge Sources | |
|---|---|
| Domains | Cluster_Mode, Distributed_Coordination |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Registering event listeners on distributed coordination repositories enables compute nodes to react to configuration and metadata changes propagated through the cluster in real time.
Description
Event Listener Registration is the principle of establishing watch/notification subscriptions on the distributed coordination repository so that each compute node in the cluster is notified when configuration, metadata, rules, or state data changes. This is the mechanism that enables dynamic reconfiguration without restarting ShardingSphere instances.
In Apache ShardingSphere, the DataChangedEventListenerRegistry is responsible for setting up two categories of listeners:
- Database-level listeners: One listener per database, watching the database metadata node path. These react to changes in schema structure, table definitions, data source configurations, and per-database rule changes.
- Global-level listeners: One listener per GlobalDataChangedEventHandler SPI implementation. These watch global paths such as compute node status, global rule configurations, system properties, and state changes.
The listener registration occurs during the final phase of cluster-mode initialization, after the compute node has been registered online and the metadata contexts are fully constructed. This ordering is important: the node must have a complete view of the current state before it begins reacting to incremental changes.
Each listener is backed by the repository's watch() mechanism:
- In ZooKeeper, this uses CuratorCache with CuratorCacheListener to receive create, update, and delete events for a node path and all its descendants.
- In etcd, this uses the etcd Watch API with prefix-based watching to receive PUT and DELETE events for keys under a given prefix.
When a data change event is detected, the listener dispatches it to the appropriate handler within the ContextManager, which applies the change to the in-memory metadata context.
Usage
Use this principle as the last step in the cluster-mode initialization sequence. After the context manager is fully constructed and the compute node is registered online, call DataChangedEventListenerRegistry.register() to begin listening for changes. The set of database names to watch is determined by the mode:
- Proxy mode: Database names are loaded from the persistence layer (register center).
- JDBC mode: Database names come from the local configuration parameter.
Theoretical Basis
The Event Listener Registration principle implements the Observer pattern at a distributed system level:
1. Observer Pattern with Distributed State
Each compute node acts as an observer of the distributed coordination repository. When another node (or an administrator via DistSQL) modifies a configuration path, all watching nodes receive a notification:
FUNCTION register():
FOR EACH databaseName IN databaseNames:
path = generateDatabaseMetaDataPath(databaseName)
repository.watch(path, new DatabaseMetaDataChangedListener(contextManager))
FOR EACH handler IN loadGlobalEventHandlers():
path = generatePath(handler.getSubscribedNodePath())
repository.watch(path, new GlobalMetaDataChangedListener(contextManager, handler))
2. Separation of Detection and Handling
The registry is responsible only for setting up the watches. The actual change processing is delegated to specialized listener and handler classes:
- DatabaseMetaDataChangedListener -- processes events related to a specific database's metadata, dispatching to appropriate event handlers based on the affected node path.
- GlobalMetaDataChangedListener -- processes events on global paths and delegates to the specific GlobalDataChangedEventHandler that subscribed to that path.
3. SPI-Driven Handler Discovery
Global event handlers are discovered via SPI using ShardingSphereServiceLoader.getServiceInstances(GlobalDataChangedEventHandler.class). This means new global change handlers can be added without modifying the registry code, following the Open/Closed principle.
4. Event Type Classification
Each data change event carries a type indicating the nature of the change:
- ADDED -- a new node was created
- UPDATED -- an existing node's data was modified
- DELETED -- a node was removed
- IGNORED -- the event should be silently discarded
Handlers use this type to determine the appropriate response (e.g., add a new rule, update a configuration, remove a database).
5. Consistency Guarantee
By registering listeners only after the node has loaded the full current state from the repository, the system avoids the problem of processing incremental changes against an incomplete baseline. The initialization order ensures:
1. Load complete metadata from repository (MetaDataContextsFactory.create)
2. Register compute node online (registerOnline)
3. Register event listeners (DataChangedEventListenerRegistry.register)