Principle:Apache Shardingsphere Data Change Event Emission
| Knowledge Sources | |
|---|---|
| Domains | Configuration_Management, Distributed_Systems |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Data change event emission is the mechanism by which modifications to distributed registry nodes are transformed into structured event objects that drive configuration propagation across the cluster.
Description
In an event-driven distributed configuration system, the bridge between persistent state changes and reactive processing is the data change event. When a node in the distributed registry (ZooKeeper, etcd, or similar) is created, updated, or deleted, the registry infrastructure emits a notification. This raw notification is captured and wrapped in a structured DataChangedEvent object that carries three essential pieces of information:
- Key (path): The full registry path of the node that changed. This path encodes the hierarchical structure of the configuration -- for example, it identifies the database name, rule type, and specific rule item. Downstream listeners use this path to determine which handler should process the event.
- Value (content): The new content of the node after the change. For ADDED and UPDATED events, this is the new version number or configuration data. For DELETED events, this represents the last known value before deletion.
- Type (change kind): An enumerated value indicating the nature of the change: ADDED for newly created nodes, UPDATED for modified nodes, DELETED for removed nodes, or IGNORED for events that should be silently discarded.
The event model is deliberately minimal and immutable. It carries no business logic, no computed fields, and no references to domain objects. This design ensures that:
- Decoupling: The event producer (registry watcher) has no knowledge of event consumers (listeners and handlers).
- Serializability: Events can be logged, replayed, or forwarded without loss of information.
- Idempotency enablement: Consumers can use the key and value to determine whether they have already processed an equivalent event, supporting at-least-once delivery semantics.
Usage
Data change events are emitted automatically by the distributed registry infrastructure whenever a watched node is modified. They are consumed by:
- DatabaseMetaDataChangedListener for database-scoped configuration changes.
- GlobalMetaDataChangedListener for cluster-wide global rule and property changes.
- Other specialized listeners for compute node state, storage node state, and cluster state management.
Theoretical Basis
The data change event model implements the Observer pattern at the distributed system level:
MODEL DataChangedEvent:
key : String // registry node path that changed
value : String // new content of the node
type : Enum // ADDED | UPDATED | DELETED | IGNORED
INVARIANTS:
- key is never null or empty
- type is never null
- value may be null for DELETED events in some registry implementations
- the event is immutable after construction
EVENT FLOW:
Registry Node Modified
-> Registry Watcher detects change
-> Construct DataChangedEvent(key, value, type)
-> Dispatch to all registered DataChangedEventListener instances
-> Each listener filters and processes relevant events
The IGNORED type serves as a sentinel value for events that the registry infrastructure recognizes as non-actionable (e.g., connection loss notifications or session events). By including this type in the enum rather than filtering at the watcher level, the system maintains a complete audit trail of all registry activity while allowing listeners to efficiently skip irrelevant events.
The choice to use a flat event structure (key + value + type) rather than a hierarchically typed event system (e.g., RuleChangedEvent, SchemaChangedEvent) is intentional. It keeps the event infrastructure generic and pushes domain-specific interpretation to the listener and handler layers, following the principle of separation of concerns.