Implementation:Apache Shardingsphere TableCoordinatorChangedHandler Handle

Knowledge Sources	Apache ShardingSphere
Domains	Metadata_Management, DDL_Processing
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for synchronizing metadata changes across cluster nodes through event-driven handlers that update in-memory metadata when governance repository changes are detected, provided by the ShardingSphere cluster mode module. This page documents TableCoordinatorChangedHandler, TableChangedHandler, and ViewChangedHandler.

Description

ShardingSphere's cluster mode uses three complementary handlers to synchronize metadata across nodes:

TableCoordinatorChangedHandler is a global event handler that processes coordinated table CREATE and DROP events from the coordinator path. When a node persists a table change, it writes a coordinator entry containing the serialized table metadata. This handler:

1. Subscribes to the TableCoordinatorNodePath for ADDED events only.
2. Parses the event key to extract a qualified table name (database.schema.table) and a coordinator type (CREATE or DROP).
3. For CREATE events, deserializes the YamlShardingSphereTable from the event value using YamlTableSwapper and calls alterTable() on the database metadata manager.
4. For DROP events, calls dropTable() on the database metadata manager.
5. Triggers an asynchronous statistics refresh after each operation.

TableChangedHandler is a per-database event handler that watches table metadata node paths. It:

1. Subscribes to TableMetaDataNodePath for each database.
2. Reacts to ADDED, UPDATED, and DELETED events.
3. For ADDED/UPDATED, loads the table metadata from the persist service and calls alterTable().
4. For DELETED, calls dropTable().

ViewChangedHandler follows the same pattern as TableChangedHandler but for view metadata, using ViewMetaDataNodePath and calling alterView() / dropView().

All three handlers trigger StatisticsRefreshEngine.asyncRefresh() after processing to keep cluster statistics up to date.

Usage

These handlers are registered automatically in cluster mode and should not be invoked directly. They are triggered by the event dispatch system when the governance repository (ZooKeeper, etcd) delivers change events.

Code Reference

Source Location (TableCoordinatorChangedHandler)

• Repository: Apache ShardingSphere
• File: mode/type/cluster/core/src/main/java/org/apache/shardingsphere/mode/manager/cluster/dispatch/handler/global/state/coordinator/TableCoordinatorChangedHandler.java
• Lines: 46-103

Source Location (TableChangedHandler)

• File: mode/type/cluster/core/src/main/java/org/apache/shardingsphere/mode/manager/cluster/dispatch/handler/database/metadata/TableChangedHandler.java
• Lines: 34-77

Source Location (ViewChangedHandler)

• File: mode/type/cluster/core/src/main/java/org/apache/shardingsphere/mode/manager/cluster/dispatch/handler/database/metadata/ViewChangedHandler.java
• Lines: 34-77

Signature (TableCoordinatorChangedHandler)

public final class TableCoordinatorChangedHandler implements GlobalDataChangedEventHandler {

    @Override
    public NodePath getSubscribedNodePath()

    @Override
    public Collection<Type> getSubscribedTypes()

    @Override
    public void handle(final ContextManager contextManager, final DataChangedEvent event)
}

Signature (TableChangedHandler)

public final class TableChangedHandler implements DatabaseLeafValueChangedHandler {

    public TableChangedHandler(final ContextManager contextManager)

    @Override
    public NodePath getSubscribedNodePath(final String databaseName)

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

Signature (ViewChangedHandler)

public final class ViewChangedHandler implements DatabaseLeafValueChangedHandler {

    public ViewChangedHandler(final ContextManager contextManager)

    @Override
    public NodePath getSubscribedNodePath(final String databaseName)

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

Import

import org.apache.shardingsphere.mode.manager.cluster.dispatch.handler.global.state.coordinator.TableCoordinatorChangedHandler;
import org.apache.shardingsphere.mode.manager.cluster.dispatch.handler.database.metadata.TableChangedHandler;
import org.apache.shardingsphere.mode.manager.cluster.dispatch.handler.database.metadata.ViewChangedHandler;

I/O Contract

Inputs (TableCoordinatorChangedHandler.handle)

Name	Type	Required	Description
contextManager	ContextManager	Yes	The context manager providing access to metadata manager and persist services
event	DataChangedEvent	Yes	The governance repository change event containing the key path and serialized table value

Inputs (TableChangedHandler.handle)

Name	Type	Required	Description
databaseName	String	Yes	The name of the database whose table metadata changed
event	DataChangedEvent	Yes	The repository change event with type (ADDED, UPDATED, DELETED) and key path

Inputs (ViewChangedHandler.handle)

Name	Type	Required	Description
databaseName	String	Yes	The name of the database whose view metadata changed
event	DataChangedEvent	Yes	The repository change event with type (ADDED, UPDATED, DELETED) and key path

Outputs

Name	Type	Description
return	void	No return value; in-memory metadata is updated as a side effect and statistics are refreshed asynchronously

Usage Examples

// These handlers are registered automatically by the cluster dispatch system.
// The following illustrates the internal flow when a table change event arrives:

// 1. TableCoordinatorChangedHandler processes global coordinator events
//    Event key: /states/coordinator/tables/my_db.public.orders/CREATE
//    Event value: YAML-serialized table metadata
TableCoordinatorChangedHandler coordinatorHandler = new TableCoordinatorChangedHandler();
coordinatorHandler.handle(contextManager, dataChangedEvent);
// Internally:
//   - Parses qualified name "my_db.public.orders" and type "CREATE"
//   - Deserializes YAML to ShardingSphereTable
//   - Calls contextManager.getMetaDataContextManager()
//         .getDatabaseMetaDataManager().alterTable("my_db", "public", table)
//   - Calls new StatisticsRefreshEngine(contextManager).asyncRefresh()

// 2. TableChangedHandler processes per-database table events
//    Event key: /metadata/my_db/schemas/public/tables/orders
//    Event type: ADDED
TableChangedHandler tableHandler = new TableChangedHandler(contextManager);
tableHandler.handle("my_db", dataChangedEvent);
// Internally:
//   - Extracts schemaName="public", tableName="orders" from event key
//   - Loads table from persist service
//   - Calls alterTable() or dropTable() based on event type
//   - Triggers async statistics refresh

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Cluster_Metadata_Synchronization