# Custom Timeouts (/sdks/java/how-to/connection/custom-timeouts)



## Overview [#overview]

Every client operation has an implicit deadline — how long to wait for the initial connection, how long before a dead socket is detected, how long reconnection retries wait between attempts, how long `close()` waits for in-flight work to drain. The defaults are reasonable for a healthy local network, but they're wrong for high-latency links, connections that pass through load balancers or NAT gateways, or servers that occasionally run slow under load. Tuning timeouts explicitly is how you trade fast-fail behavior against tolerance for transient slowness.

Each timeout targets a different phase of the client lifecycle. `connectionTimeoutSeconds` bounds the initial TCP/TLS handshake; `keepAlive(true)` with `pingIntervalInSeconds` / `pingTimeoutInSeconds` maps to gRPC HTTP/2 PING frames that detect a stale connection before you try to use it; `reconnectIntervalSeconds` sets the base delay for the SDK's exponential backoff reconnection loop; and `shutdownTimeoutSeconds` bounds how long `close()` waits for outstanding RPCs before it forces the channel shut. **Gotchas:** a `connectionTimeoutSeconds` shorter than your network's real handshake latency causes spurious startup failures, not faster detection of a genuinely down server; an aggressive `pingIntervalInSeconds` can flag a slow-but-healthy link as dead; and the reconnection loop's exponential backoff has no attempt cap by default, so it will keep retrying against a server that's down for good unless you bound it yourself.

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

import io.kubemq.sdk.client.KubeMQClient;
import io.kubemq.sdk.common.ServerInfo;
import io.kubemq.sdk.queues.QueuesClient;
import io.kubemq.sdk.pubsub.PubSubClient;
import io.kubemq.sdk.cq.CQClient;

/**
 * Custom Timeouts Example
 *
 * Demonstrates configuring custom timeouts for KubeMQ clients including
 * connection timeouts, keep-alive intervals, and reconnection intervals.
 */
public class CustomTimeoutsExample {

    private static final String ADDRESS = "localhost:50000";
    private static final String CLIENT_ID = "java-connection-custom-timeouts-client";

    public void connectionTimeoutExample() {
        System.out.println("=== Connection Timeout Configuration ===\n");

        // Create a client with custom connection timeout
        try (QueuesClient client = QueuesClient.builder()
                .address(ADDRESS)
                .clientId(CLIENT_ID + "-conn-timeout")
                .connectionTimeoutSeconds(10)
                .build()) {

            ServerInfo info = client.ping();
            System.out.println("Connected with 10s connection timeout.");
            System.out.println("Server: " + info.getHost() + "\n");

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

    public void keepAliveTimeoutsExample() {
        System.out.println("=== Keep-Alive Timeout Configuration ===\n");

        // Create a client with custom keep-alive intervals
        try (PubSubClient client = PubSubClient.builder()
                .address(ADDRESS)
                .clientId(CLIENT_ID + "-keepalive")
                .keepAlive(true)
                .pingIntervalInSeconds(15)
                .pingTimeoutInSeconds(5)
                .build()) {

            ServerInfo info = client.ping();
            System.out.println("Connected with custom keep-alive:");
            System.out.println("  Ping Interval: 15 seconds");
            System.out.println("  Ping Timeout: 5 seconds");
            System.out.println("  Server: " + info.getHost() + "\n");

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

    public void reconnectionTimeoutExample() {
        System.out.println("=== Reconnection Interval Configuration ===\n");

        // Create a client with custom reconnection interval
        try (CQClient client = CQClient.builder()
                .address(ADDRESS)
                .clientId(CLIENT_ID + "-reconnect")
                .reconnectIntervalSeconds(2)
                .build()) {

            ServerInfo info = client.ping();
            System.out.println("Connected with 2s base reconnect interval.");
            System.out.println("  Backoff: 2s, 4s, 8s, 16s, ... up to the configured max (default 30s)");
            System.out.println("  Server: " + info.getHost() + "\n");

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

    public void shutdownTimeoutExample() {
        System.out.println("=== Shutdown Timeout Configuration ===\n");

        // Create a client with custom shutdown timeout
        try (QueuesClient client = QueuesClient.builder()
                .address(ADDRESS)
                .clientId(CLIENT_ID + "-shutdown")
                .shutdownTimeoutSeconds(5)
                .build()) {

            ServerInfo info = client.ping();
            System.out.println("Connected with 5s shutdown timeout.");
            System.out.println("Server: " + info.getHost() + "\n");

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

    public static void main(String[] args) {
        CustomTimeoutsExample example = new CustomTimeoutsExample();
        example.connectionTimeoutExample();
        example.keepAliveTimeoutsExample();
        example.reconnectionTimeoutExample();
        example.shutdownTimeoutExample();
        System.out.println("Custom timeouts examples completed.");
    }
}

```

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

* `connectionTimeoutSeconds(10)` limits how long the SDK waits for the initial TCP/TLS handshake; requests that exceed this deadline throw a `KubeMQTimeoutException`.
* `keepAlive(true)` with `pingIntervalInSeconds` and `pingTimeoutInSeconds` maps to gRPC's HTTP/2 PING frames, which detect dead connections faster than TCP keepalives alone.
* `reconnectIntervalSeconds(2)` sets the base interval for the SDK's built-in exponential backoff reconnection loop; the interval doubles on each failed attempt up to a configurable maximum (default 30 s).
* `shutdownTimeoutSeconds(5)` controls how long `close()` waits for in-flight RPCs to complete before forcibly closing the channel.

## Related [#related]

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