Custom Timeouts
Configure custom connection and operation timeouts for the KubeMQ Java SDK client to tune reliability and latency.
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
- 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.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
connectionTimeoutSeconds(10)limits how long the SDK waits for the initial TCP/TLS handshake; requests that exceed this deadline throw aKubeMQTimeoutException.keepAlive(true)withpingIntervalInSecondsandpingTimeoutInSecondsmaps 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 longclose()waits for in-flight RPCs to complete before forcibly closing the channel.
Related
Was this page helpful?