Implementation:Apache Shardingsphere ClusterContextManagerBuilder Build

Knowledge Sources	Apache ShardingSphere
Domains	Cluster_Mode, Distributed_Coordination
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for orchestrating the full cluster-mode context manager initialization sequence provided by the ShardingSphere mode module.

Description

ClusterContextManagerBuilder is the SPI implementation of ContextManagerBuilder registered with type "Cluster". Its build() method is the central orchestration point for cluster-mode startup. It performs the following steps in sequence:

Extracts the ModeConfiguration from the parameter and casts its repository section to ClusterPersistRepositoryConfiguration.
Creates a ComputeNodeInstanceContext wrapping a new ComputeNodeInstance with the provided instance metadata and labels.
Loads the ClusterPersistRepository implementation via SPI (e.g., ZooKeeper or etcd), validates the configuration is non-null, and initializes the repository.
Initializes the compute node instance context with a ClusterWorkerIdGenerator backed by the repository.
Creates an ExclusiveOperatorEngine for cluster-level exclusive operations.
Builds MetaDataContexts using MetaDataContextsFactory, passing a new MetaDataPersistFacade and the instance context.
Assembles the ContextManager with the metadata contexts, instance context, exclusive operator engine, and repository.
Registers the compute node online, loads all existing cluster instances, and registers data changed event listeners.
Registers deliver event subscribers for cross-node event propagation.

Usage

This builder is loaded automatically by the SPI mechanism when the mode configuration type is "Cluster". It is not invoked directly by application code.

Code Reference

Source Location

Repository: Apache ShardingSphere
File: mode/type/cluster/core/src/main/java/org/apache/shardingsphere/mode/manager/cluster/ClusterContextManagerBuilder.java
Lines: 53-104

Signature

public final class ClusterContextManagerBuilder implements ContextManagerBuilder {

    @Override
    public ContextManager build(final ContextManagerBuilderParameter param, final EventBusContext eventBusContext) throws SQLException {
        ModeConfiguration modeConfig = param.getModeConfiguration();
        ClusterPersistRepositoryConfiguration config = (ClusterPersistRepositoryConfiguration) modeConfig.getRepository();
        ComputeNodeInstanceContext computeNodeInstanceContext = new ComputeNodeInstanceContext(
                new ComputeNodeInstance(param.getInstanceMetaData(), param.getLabels()), modeConfig, eventBusContext);
        ClusterPersistRepository repository = getClusterPersistRepository(config, computeNodeInstanceContext);
        computeNodeInstanceContext.init(new ClusterWorkerIdGenerator(repository, param.getInstanceMetaData().getId()));
        ExclusiveOperatorEngine exclusiveOperatorEngine = new ExclusiveOperatorEngine(new ClusterExclusiveOperatorContext(repository));
        MetaDataContexts metaDataContexts = new MetaDataContextsFactory(new MetaDataPersistFacade(repository), computeNodeInstanceContext).create(param);
        ContextManager result = new ContextManager(metaDataContexts, computeNodeInstanceContext, exclusiveOperatorEngine, repository);
        registerOnline(computeNodeInstanceContext, param, result);
        new DeliverEventSubscriberRegistry(result.getComputeNodeInstanceContext().getEventBusContext())
                .register(createDeliverEventSubscribers(repository));
        return result;
    }

    @Override
    public String getType() {
        return "Cluster";
    }
}

Import

import org.apache.shardingsphere.mode.manager.cluster.ClusterContextManagerBuilder;

I/O Contract

Inputs

Name	Type	Required	Description
param	ContextManagerBuilderParameter	Yes	Immutable parameter object containing all bootstrap configuration
eventBusContext	EventBusContext	Yes	Event bus context for cross-component event communication

Outputs

Name	Type	Description
return	ContextManager	Fully initialized context manager for cluster mode operation

Exceptions

Type	Condition
MissingRequiredClusterRepositoryConfigurationException	Thrown when the cluster repository configuration is null
SQLException	Thrown when metadata context creation encounters database errors

Usage Examples

// Typically invoked via SPI, not directly. The bootstrap code does:
ContextManagerBuilder builder = TypedSPILoader.getService(ContextManagerBuilder.class, "Cluster");
ContextManager contextManager = builder.build(param, eventBusContext);

// Internal orchestration performed by build():
// 1. Initializes ZooKeeper/etcd repository
// 2. Sets up worker ID generation
// 3. Loads or creates metadata contexts
// 4. Registers compute node online
// 5. Sets up event listeners for configuration changes

Related Pages

Implements Principle

Principle:Apache_Shardingsphere_SPI_Builder_Loading

Requires Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment