# Connect (/sdks/java/tutorials/connect)



## Overview [#overview]

Every KubeMQ application starts the same way: open a connection to the broker and prove it actually works before building anything on top of it. This tutorial is that first lesson — create a client, give it a stable identity, and confirm connectivity with a health check, so the pattern is muscle memory before you move on to real messaging.

`QueuesClient.builder()` is constructed with an `address` and a `clientId` — the ID tags this connection in broker logs, subscriptions, and management views, so pick something stable rather than a random string. `client.ping()` verifies the round trip cheaply: it returns live server info (host, version, uptime) instead of just "no exception," proving the client is talking to a real broker rather than silently misconfigured. All client classes implement `AutoCloseable`, so `try-with-resources` releases the gRPC channel even on exception.

**Gotchas:** building the client doesn't always mean the broker is reachable — the channel can be established lazily, so `ping()` is the only reliable proof; reusing the same client ID across running instances causes routing confusion on the broker; and skipping `try-with-resources` in quick scripts is a common source of leaked channels under load.

## 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="ConnectExample.java"
package io.kubemq.example.connection;

import io.kubemq.sdk.queues.QueuesClient;
import io.kubemq.sdk.common.ServerInfo;

public class ConnectExample {

    public static void main(String[] args) {
        // TODO: Replace with your KubeMQ server address
        String address = "localhost:50000";

        try (QueuesClient client = QueuesClient.builder()
                .address(address)
                .clientId("java-connection-connect-client")
                .build()) {

            ServerInfo info = client.ping();
            System.out.printf("Connected successfully: host=%s version=%s uptime=%ds%n",
                    info.getHost(), info.getVersion(), info.getServerUpTimeSeconds());

        } catch (Exception e) {
            System.err.println("Connection failed: " + e.getMessage());
        }
    }
}

// Expected output:
// Connected successfully: host=<host> version=<version> uptime=<uptime>s

```

## How It Works [#how-it-works]

* `QueuesClient.builder()` constructs the client without opening a connection; the gRPC channel is established lazily on first use or explicitly via `ping()`.
* `client.ping()` issues a gRPC health-check RPC and returns `ServerInfo` containing the host, SDK version, and server uptime.
* All three client classes (`PubSubClient`, `QueuesClient`, `CQClient`) implement `AutoCloseable`, so `try-with-resources` ensures the underlying gRPC channel is released even if an exception occurs.
* Replace `localhost:50000` with the actual broker address and set a stable `clientId` string — it is used for subscription routing and server-side logging.

## Related [#related]

* [Java SDK Reference](/sdks/java/reference)
* [Close](/sdks/java/how-to/connection/close)
* [Ping](/sdks/java/how-to/connection/ping)