Principle:Apache Shardingsphere Configuration Parameter Construction

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

Overview

Assembling all bootstrap configuration parameters into an immutable parameter object provides a single, well-defined entry point for mode initialization in a distributed database system.

Description

Configuration Parameter Construction is the principle of bundling every piece of bootstrap configuration -- mode settings, database configurations, global data sources, global rule configurations, system properties, instance labels, and instance metadata -- into one cohesive, immutable value object before any initialization logic executes. In Apache ShardingSphere, this object is ContextManagerBuilderParameter.

By collecting all required configuration into a single parameter object, the system achieves several goals:

• Single Responsibility: The parameter object is responsible solely for holding configuration data. It carries no behavior beyond exposing its fields and providing a safe default for the mode configuration.
• Immutability: All fields are declared final and populated through a single constructor invocation via @RequiredArgsConstructor. Once constructed, the parameter object cannot be modified, preventing accidental mutation during the multi-step initialization sequence.
• Safe Defaults: When no explicit ModeConfiguration is supplied (i.e., it is null), the object transparently falls back to a "Standalone" mode configuration. This ensures that downstream consumers never encounter a null mode configuration.
• Decoupling: Callers (JDBC driver, Proxy bootstrap, integration tests) assemble the parameter object independently of the builder that consumes it. This decouples configuration assembly from initialization logic.

The parameter object encapsulates the following data:

Field	Type	Purpose
modeConfig	ModeConfiguration	Defines the operating mode (Standalone, Cluster) and its repository settings
databaseConfigs	Map<String, DatabaseConfiguration>	Per-database configurations including data sources and rules
globalDataSources	Map<String, DataSource>	Globally shared data sources
globalRuleConfigs	Collection<RuleConfiguration>	Global rule configurations such as authority and transaction rules
props	Properties	System-level properties (e.g., SQL show, executor size)
labels	Collection<String>	Instance labels for compute node identification
instanceMetaData	InstanceMetaData	Metadata describing the current compute node instance

Usage

Use this principle whenever initiating the ShardingSphere context manager from any entry point. Both JDBC and Proxy modes construct a ContextManagerBuilderParameter as the first step of their bootstrap sequences. The parameter object is then passed to the appropriate ContextManagerBuilder implementation (loaded via SPI) to drive the full initialization workflow.

Theoretical Basis

The Configuration Parameter Construction principle follows a well-established pattern in software design:

1. Parameter Object Pattern

Instead of passing numerous individual arguments through a chain of method calls, all configuration is gathered into a single object. This avoids long parameter lists, reduces the chance of argument transposition errors, and provides a named, documented structure for the configuration contract.

2. Immutable Value Object

The parameter object is constructed once and never modified. This is especially important in a concurrent distributed system where multiple threads may access configuration during initialization. Immutability eliminates synchronization concerns for read access.

3. Null-Safe Default Strategy

The getModeConfiguration() method implements a null-coalescing pattern:

FUNCTION getModeConfiguration():
    IF modeConfig IS NULL:
        RETURN new ModeConfiguration("Standalone", null)
    ELSE:
        RETURN modeConfig

This guarantees that any consumer of the parameter object always receives a valid mode configuration, removing the need for null checks throughout the initialization pipeline.

4. Separation of Assembly and Consumption

The assembly of configuration (performed by the caller) is separated from its consumption (performed by the builder). This enables different entry points to construct the parameter differently while the builder logic remains uniform:

PROCEDURE bootstrap(entryPointConfig):
    param = assembleParameterObject(entryPointConfig)
    builder = loadBuilderViaSPI(param.getModeConfiguration().getType())
    contextManager = builder.build(param)

Related Pages

Implemented By

• Implementation:Apache_Shardingsphere_ContextManagerBuilderParameter_Constructor