Environment:Risingwavelabs Risingwave Java Connector Environment

Knowledge Sources	RisingWave Connector Node README
Domains	Infrastructure, CDC, Connectors
Last Updated	2026-02-09 08:00 GMT

Overview

Java 11+ environment with Maven, JNI native bindings, and Debezium 3.2.4 for running RisingWave's CDC source connectors and Java-based sink connectors.

Description

This environment provides the Java runtime and build toolchain for RisingWave's connector subsystem. The Java connector node handles CDC (Change Data Capture) via Debezium and sink writes to external systems (Cassandra, Elasticsearch, JDBC databases, Iceberg). It communicates with the Rust core via gRPC (standalone mode) or JNI (embedded mode). The JNI bridge requires a native library (risingwave_java_binding) compiled from Rust and loaded at runtime.

Usage

Use this environment for building or running the Java connector node, CDC source integration, or Java-based sink connectors. Required when running any CDC pipeline (MySQL, PostgreSQL, MongoDB, SQL Server) or when writing to sinks via the Java connector service.

System Requirements

Category	Requirement	Notes
OS	Linux (Ubuntu 20.04+), macOS	Windows not officially supported
Hardware	No GPU required	CPU-bound; JVM heap scales with CDC load
RAM	2GB+ for JVM	JVM heap defaults to 7% of system memory if JVM_HEAP_SIZE not set
Disk	5GB for Maven dependencies	.m2 cache can be shared across builds

Dependencies

System Packages

openjdk-17-jdk (build-time; compiles to Java 11 target)
maven (build tool)
python3 (for integration test scripts)

Java Libraries (Key Versions)

Protobuf: 3.25.8
gRPC: 1.75.0
Debezium: 3.2.4.Final
Jackson: 2.19.2
Hadoop: 3.4.1
AWS SDK: 2.32.19
Apache Iceberg (via JNI catalog wrapper)
Parquet: 1.15.1
Log4j: 2.25.3
SLF4J: 2.0.17

Build Configuration

Source/Target: Java 11 (maven.compiler.source=11, maven.compiler.target=11)
Code Formatting: Google Java Format 1.20.0 via Spotless
Checkstyle: 10.26.1

Credentials

The following environment variables control connector node behavior:

RW_CONNECTOR_NODE_PORT: gRPC listening port (default: 50051)
RW_CONNECTOR_NODE_PROMETHEUS_PORT: Prometheus metrics port (default: 50052)
JVM_HEAP_SIZE: Override JVM max heap size (otherwise 7% of system memory)

CDC source credentials are passed via SQL DDL properties, not environment variables.

Quick Install

# Install JDK 17 and Maven
sudo apt-get install -y openjdk-17-jdk maven

# Build Java connector node (from repo root)
cd java && mvn clean package -DskipTests=true

# Build without Rust JNI bindings (for Java-only changes)
cd java && mvn clean package -DskipTests=true -Dno-build-rust

Code Evidence

Java version configuration from java/pom.xml lines 59-60:

<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>

Environment variable reading from ConnectorService.java lines 31-49:

static final String PORT_ENV_NAME = "RW_CONNECTOR_NODE_PORT";
static final int DEFAULT_PORT = 50051;

if (System.getenv().containsKey(PORT_ENV_NAME)) {
    port = Integer.parseInt(System.getenv(PORT_ENV_NAME));
}

JNI library loading from Binding.java lines 23-27:

private static final boolean IS_EMBEDDED_CONNECTOR =
        Boolean.parseBoolean(System.getProperty("is_embedded_connector"));

static {
    if (!IS_EMBEDDED_CONNECTOR) {
        JarJniLoader.loadLib(Binding.class, "/risingwave/jni", "risingwave_java_binding");
    }
}

JVM heap allocation from DbzConnectorConfig.java lines 384-392:

/**
 * JVM heap size is obtained from Runtime.getRuntime().maxMemory(),
 * which reflects the -Xmx value set by Rust code during JVM initialization.
 * The Rust code sets -Xmx based on:
 * 1. JVM_HEAP_SIZE env var if set
 * 2. Otherwise: system_memory_available_bytes() * 0.07
 */

Common Errors

Error Message	Cause	Solution
`UnsatisfiedLinkError: risingwave_java_binding`	JNI native library not compiled	Build with `mvn package` (without `-Dno-build-rust`)
`java.lang.ClassNotFoundException: com.risingwave.connector.ConnectorService`	Classpath not set correctly	Use `java -classpath "./libs/*" com.risingwave.connector.ConnectorService`
`IllegalAccessError` in tests	Missing JVM module opens	Add `--add-opens` flags per pom.xml surefire configuration
`OutOfMemoryError: Java heap space`	JVM heap too small for CDC load	Set `JVM_HEAP_SIZE` env var or increase system memory

Compatibility Notes

Embedded vs Standalone Mode: When is_embedded_connector=true (system property), the JNI library is loaded by the Rust process directly. In standalone mode, the Java process loads the library from JAR resources.
JDK 17 Required for Build: Although the target is Java 11 bytecode, the build uses JDK 17 features and requires --add-opens flags for Surefire tests.
Debezium Patches: Several Debezium classes are patched in-tree (PostgresConnectorConfig, BinlogOffsetContext, etc.) to support RisingWave-specific CDC requirements.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment