Implementation:Risingwavelabs Risingwave MetaClient

Metadata

Property	Value
File	java/common-utils/src/main/java/com/risingwave/java/utils/MetaClient.java
Language	Java
Module	common-utils
Package	com.risingwave.java.utils
Classes	MetaClient, HeartbeatTask (inner class)
Lines	157
Interfaces Implemented	AutoCloseable

Overview

MetaClient is a gRPC client that enables Java connector nodes to communicate with the RisingWave meta service. It handles worker node registration, periodic heartbeat maintenance, Hummock version pinning/unpinning, and table schema retrieval via the DDL service. Upon construction, it registers itself as a WORKER_TYPE_RISE_CTL worker node and obtains a worker ID used for subsequent RPC calls.

The class also contains an inner HeartbeatTask class that implements Runnable to send periodic heartbeat requests to the meta service, keeping the worker node registration alive.

Code Reference

Source Location

java/common-utils/src/main/java/com/risingwave/java/utils/MetaClient.java

Signature

public class MetaClient implements AutoCloseable {
    public MetaClient(String metaAddr, ScheduledExecutorService scheduler)
    public HummockVersion pinVersion()
    public void unpinVersion(HummockVersion version)
    public Table getTable(String databaseName, String tableName)
    public ScheduledFuture<?> startHeartbeatLoop(Duration interval)
    public void close()
}

Imports

import com.risingwave.proto.*;
import com.risingwave.proto.Catalog.Table;
import com.risingwave.proto.ClusterServiceGrpc.ClusterServiceBlockingStub;
import com.risingwave.proto.Common.HostAddress;
import com.risingwave.proto.Common.WorkerNode.Property;
import com.risingwave.proto.Common.WorkerType;
import com.risingwave.proto.DdlServiceGrpc.DdlServiceBlockingStub;
import com.risingwave.proto.DdlServiceOuterClass.GetTableRequest;
import com.risingwave.proto.DdlServiceOuterClass.GetTableResponse;
import com.risingwave.proto.HeartbeatServiceGrpc.HeartbeatServiceBlockingStub;
import com.risingwave.proto.Hummock.HummockVersion;
import com.risingwave.proto.Hummock.PinVersionRequest;
import com.risingwave.proto.Hummock.PinVersionResponse;
import com.risingwave.proto.Hummock.UnpinVersionBeforeRequest;
import com.risingwave.proto.HummockManagerServiceGrpc.HummockManagerServiceBlockingStub;
import com.risingwave.proto.Meta.AddWorkerNodeRequest;
import com.risingwave.proto.Meta.AddWorkerNodeResponse;
import com.risingwave.proto.Meta.HeartbeatRequest;
import io.grpc.Grpc;
import io.grpc.InsecureChannelCredentials;
import io.grpc.ManagedChannel;
import java.time.Duration;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.ScheduledFuture;
import java.util.concurrent.TimeUnit;
import java.util.logging.Logger;

I/O Contract

Constructor

Parameter	Type	Description
metaAddr	String	The address of the RisingWave meta service (e.g., "host:port")
scheduler	ScheduledExecutorService	Executor service for scheduling background heartbeat tasks

Side Effects: The constructor opens a gRPC channel to the meta service using insecure credentials and immediately sends an AddWorkerNode RPC to register the client as a WORKER_TYPE_RISE_CTL worker. The returned worker ID is stored internally.

pinVersion

Direction	Type	Description
Input	None	Uses the internal workerId as context ID
Output	HummockVersion	The pinned Hummock storage version

unpinVersion

Direction	Type	Description
Input	HummockVersion	The version to unpin (unpins all versions before this version's ID)
Output	None	Sends an UnpinVersionBefore RPC

Note: The current implementation uses UnpinVersionBefore, which may accidentally unpin versions used by other threads if multiple versions are in use concurrently. A reference counting mechanism is planned.

getTable

Direction	Type	Description
Input	String databaseName, String tableName	The database and table names to look up
Output	Catalog.Table or null	Returns the table metadata if found, null otherwise

startHeartbeatLoop

Direction	Type	Description
Input	Duration interval	The interval between heartbeats
Output	ScheduledFuture<?>	A handle to the scheduled heartbeat task (can be cancelled)

The heartbeat task uses a timeout of 3x the interval duration.

Usage Examples

// Create a MetaClient connected to the meta service
ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
MetaClient metaClient = new MetaClient("localhost:5690", scheduler);

// Start the heartbeat loop to maintain registration
ScheduledFuture<?> heartbeat = metaClient.startHeartbeatLoop(Duration.ofSeconds(5));

// Pin a Hummock version for consistent reads
HummockVersion version = metaClient.pinVersion();

// Retrieve table metadata
Catalog.Table table = metaClient.getTable("my_database", "my_table");

// Unpin the version when done
metaClient.unpinVersion(version);

// Stop heartbeat and close
heartbeat.cancel(false);
metaClient.close();

Related Pages

• VnodeHelper - Another utility in the common-utils module for vnode partition management
• ConnectorService Main - The main entry point for the connector service that may use MetaClient
• TableSchema - Represents table schema metadata that can be obtained via MetaClient's getTable method