Implementation:Apache Shardingsphere ClusterWorkerIdGenerator Generate

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

Overview

Concrete tool for generating unique worker IDs and registering compute nodes online in the cluster, provided by the ShardingSphere cluster mode module.

Description

This page documents two collaborating classes that implement compute node registration:

ClusterWorkerIdGenerator is a final class implementing the WorkerIdGenerator interface. Its generate(Properties) method produces a unique worker ID (0-1023) for the current compute node instance by:

1. Attempting to load a previously assigned worker ID for the current instance ID from the repository.
2. If no existing ID is found, entering a retry loop that scans all assigned worker IDs, computes the set of available IDs, selects the smallest available candidate, and attempts to atomically reserve it via ReservationPersistService.
3. Once successfully reserved, persisting the worker ID and returning it.
4. Logging a warning if the user has explicitly configured a worker-id property, since cluster mode manages worker IDs automatically.

ClusterComputeNodePersistService is a final class annotated with @RequiredArgsConstructor that provides the registerOnline(ComputeNodeInstance) method. This method:

1. Persists the compute node data (database name, attributes, version) as an ephemeral node at the online node path.
2. Updates the node's instance state as ephemeral data.
3. Persists the node's labels as ephemeral data.

The ephemeral persistence ensures automatic removal of the node's registration when the session with the coordination service expires.

Usage

ClusterWorkerIdGenerator is constructed in ClusterContextManagerBuilder.build() and passed to ComputeNodeInstanceContext.init(). It is invoked lazily when the worker ID is first needed.

ClusterComputeNodePersistService.registerOnline() is called in ClusterContextManagerBuilder.registerOnline() after the context manager is assembled.

Code Reference

Source Location -- ClusterWorkerIdGenerator

• Repository: Apache ShardingSphere
• File: mode/type/cluster/core/src/main/java/org/apache/shardingsphere/mode/manager/cluster/workerid/ClusterWorkerIdGenerator.java
• Lines: 40-89

Source Location -- ClusterComputeNodePersistService

• Repository: Apache ShardingSphere
• File: mode/type/cluster/core/src/main/java/org/apache/shardingsphere/mode/manager/cluster/persist/service/ClusterComputeNodePersistService.java
• Lines: 53-179

Signature -- ClusterWorkerIdGenerator

@Slf4j
public final class ClusterWorkerIdGenerator implements WorkerIdGenerator {

    private final String instanceId;

    private final ClusterComputeNodePersistService computeNodePersistService;

    private final ReservationPersistService reservationPersistService;

    private final AtomicBoolean isWarned = new AtomicBoolean(false);

    public ClusterWorkerIdGenerator(final ClusterPersistRepository repository, final String instanceId) {
        this.instanceId = instanceId;
        computeNodePersistService = new ClusterComputeNodePersistService(repository);
        reservationPersistService = new ReservationPersistService(repository);
    }

    @Override
    public int generate(final Properties props) {
        int result = computeNodePersistService.loadWorkerId(instanceId).orElseGet(this::generateNewWorkerId);
        logWarning(result, props);
        return result;
    }
}

Signature -- ClusterComputeNodePersistService.registerOnline

@RequiredArgsConstructor
@Slf4j
public final class ClusterComputeNodePersistService implements ComputeNodePersistService {

    private final ClusterPersistRepository repository;

    public void registerOnline(final ComputeNodeInstance computeNodeInstance) {
        persistOnline(computeNodeInstance);
        updateState(computeNodeInstance.getMetaData().getId(), computeNodeInstance.getState().getCurrentState());
        persistLabels(computeNodeInstance.getMetaData().getId(), computeNodeInstance.getLabels());
    }
}

Import

import org.apache.shardingsphere.mode.manager.cluster.workerid.ClusterWorkerIdGenerator;
import org.apache.shardingsphere.mode.manager.cluster.persist.service.ClusterComputeNodePersistService;

I/O Contract

Inputs -- ClusterWorkerIdGenerator.generate

Name	Type	Required	Description
props	Properties	Yes	System properties; checked for a user-configured worker-id key (which triggers a warning)

Outputs -- ClusterWorkerIdGenerator.generate

Name	Type	Description
return	int	Unique worker ID in the range 0-1023 assigned to this compute node instance

Inputs -- ClusterComputeNodePersistService.registerOnline

Name	Type	Required	Description
computeNodeInstance	ComputeNodeInstance	Yes	The compute node instance to register, containing metadata, state, and labels

Outputs -- ClusterComputeNodePersistService.registerOnline

Name	Type	Description
(void)	void	Side effect: persists ephemeral online, state, and label data in the repository

Exceptions

Type	Condition
WorkerIdAssignedException	Thrown when all 1024 worker IDs (0-1023) are already assigned to other instances
NullPointerException	Thrown (via Preconditions.checkNotNull) if no available worker ID candidate can be selected

Worker ID Allocation Algorithm

Step	Description
1	Check if this instance already has a persisted worker ID
2	If yes, return the existing worker ID
3	If no, load all assigned worker IDs from the repository
4	Compute available IDs as the set difference: {0..1023} - assignedIds
5	Select the smallest available ID as a candidate
6	Attempt atomic reservation of the candidate via ReservationPersistService
7	If reservation fails (another node claimed it), retry from step 3
8	Once reserved, persist the worker ID for this instance and return it

Usage Examples

// Worker ID generator construction and initialization (in ClusterContextManagerBuilder.build())
ClusterWorkerIdGenerator workerIdGenerator = new ClusterWorkerIdGenerator(repository, param.getInstanceMetaData().getId());
computeNodeInstanceContext.init(workerIdGenerator);

// Worker ID generation is invoked lazily when needed
int workerId = workerIdGenerator.generate(props);

// Online registration (in ClusterContextManagerBuilder.registerOnline())
ClusterPersistServiceFacade clusterPersistServiceFacade =
    (ClusterPersistServiceFacade) contextManager.getPersistServiceFacade().getModeFacade();
clusterPersistServiceFacade.getComputeNodeService().registerOnline(computeNodeInstanceContext.getInstance());

// Loading all cluster instances after registration
contextManager.getComputeNodeInstanceContext().getClusterInstanceRegistry().getAllClusterInstances()
    .addAll(clusterPersistServiceFacade.getComputeNodeService().loadAllInstances());

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Compute_Node_Registration

Requires Environment

• Environment:Apache_Shardingsphere_Java_Runtime_Environment
• Environment:Apache_Shardingsphere_ZooKeeper_Cluster_Coordination
• Environment:Apache_Shardingsphere_Etcd_Cluster_Coordination

Uses Heuristic

• Heuristic:Apache_Shardingsphere_Worker_ID_Reservation_Strategy