# Ping (/sdks/java/how-to/connection/ping)



## Overview [#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 [#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](/sdks/java))

## Code [#code]

```java title="PingExample.java"
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 [#how-it-works]

* `client.ping()` sends a unary `Ping` RPC to the broker and returns a `ServerInfo` object containing `getHost()`, `getVersion()`, `getServerStartTime()`, and `getServerUpTimeSeconds()`.
* `validateOnBuild(true)` causes the builder to call `ping()` internally during `build()` — 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 explicit `ping()` establishes the connection.
* `ping()` is a lightweight health check and does not consume any queue or channel resources.

## Related [#related]

* [Java SDK Reference](/sdks/java/reference)
* [Connect](/sdks/java/tutorials/connect)
* [Close](/sdks/java/how-to/connection/close)