Ping
Ping the KubeMQ server with the Java SDK to verify connectivity and read server health and version details.
Overview
A ping is a lightweight liveness check — you call it to confirm the broker is actually reachable before sending real traffic, without standing up a publisher, subscriber, or queue client just to find out. It's the tool of choice for startup readiness checks, container liveness/readiness probes, and connection-health dashboards that need a fast, cheap go/no-go signal.
client.ping() issues a minimal unary RPC to the server and returns a ServerInfo object (getHost(), getVersion(), getServerUpTimeSeconds()) confirming the broker answered. Building with validateOnBuild(true) folds that same check into construction, so build() throws immediately if the server is unreachable instead of failing silently on the first real send.
Gotchas: a failed ping() doesn't close the client — the SDK's reconnect logic keeps retrying in the background, so catch and check the exception yourself rather than assume the client tears itself down. A successful ping only confirms the broker process answered, not that a specific channel or queue exists or has capacity. And without validateOnBuild, the gRPC channel is created lazily, so the first call you make — ping or otherwise — is what actually triggers the connection.
Prerequisites
- KubeMQ server running on
localhost:50000 - Java SDK installed (
implementation 'io.kubemq.sdk:kubemq-sdk-Java:3.1.1'(Gradle) or Maven dependency from Getting Started)
Code
package io.kubemq.example.connection;
import io.kubemq.sdk.common.ServerInfo;
import io.kubemq.sdk.queues.QueuesClient;
/**
* Ping Example
*
* Demonstrates verifying connectivity to a KubeMQ server using ping.
*/
public class PingExample {
private static final String ADDRESS = "localhost:50000";
private static final String CLIENT_ID = "java-connection-ping-client";
public void pingServer() {
System.out.println("=== Ping KubeMQ Server ===\n");
// Create a client and verify connectivity with ping
try (QueuesClient client = QueuesClient.builder()
.address(ADDRESS)
.clientId(CLIENT_ID)
.build()) {
ServerInfo serverInfo = client.ping();
System.out.println("Ping successful!");
System.out.println(" Host: " + serverInfo.getHost());
System.out.println(" Version: " + serverInfo.getVersion());
System.out.println(" Server Start Time: " + serverInfo.getServerStartTime());
System.out.println(" Server Uptime (seconds): " + serverInfo.getServerUpTimeSeconds());
} catch (Exception e) {
System.err.println("Ping failed: " + e.getMessage());
}
}
public void pingWithValidateOnBuild() {
System.out.println("\n=== Ping via validateOnBuild ===\n");
// Create a client that validates connectivity on build
try (QueuesClient client = QueuesClient.builder()
.address(ADDRESS)
.clientId(CLIENT_ID + "-validate")
.validateOnBuild(true)
.build()) {
System.out.println("Client created and connectivity validated on build.");
} catch (Exception e) {
System.err.println("Connectivity validation failed: " + e.getMessage());
}
}
public static void main(String[] args) {
PingExample example = new PingExample();
example.pingServer();
example.pingWithValidateOnBuild();
}
}
How It Works
client.ping()sends a unaryPingRPC to the broker and returns aServerInfoobject containinggetHost(),getVersion(),getServerStartTime(), andgetServerUpTimeSeconds().validateOnBuild(true)causes the builder to callping()internally duringbuild()— the constructor throws if the server is unreachable, giving an early fail-fast check at startup.- Without
validateOnBuild, the gRPC channel is created lazily; the first message send or explicitping()establishes the connection. ping()is a lightweight health check and does not consume any queue or channel resources.
Related
Was this page helpful?