org.apache.hc.client5.http.websocket.client

Class CloseableWebSocketClient

java.lang.Object

org.apache.hc.client5.http.websocket.client.CloseableWebSocketClient

All Implemented Interfaces:

Closeable, AutoCloseable, WebSocketClient, ModalCloseable

Direct Known Subclasses:

DefaultWebSocketClient

@Contract(threading=STATELESS)
public abstract class CloseableWebSocketClient
extends Object
implements WebSocketClient, ModalCloseable

Public WebSocket client API mirroring CloseableHttpAsyncClient's shape.

Subclasses provide the actual connect implementation in doConnect(URI, WebSocketListener, WebSocketClientConfig, HttpContext). Overloads of connect(...) funnel into that single method.

This type is a ModalCloseable; use ModalCloseable.close(CloseMode) to select graceful or immediate shutdown. A graceful close allows in-flight I/O to finish, while immediate close aborts active operations.

Since:

5.7

Constructor Summary

Constructors

Constructor and Description
CloseableWebSocketClient()

Method Summary

Modifier and Type	Method and Description
abstract void	awaitShutdown(TimeValue waitTime) Best-effort await of shutdown.
CompletableFuture<WebSocket>	connect(URI uri, WebSocketListener listener) Convenience overload that uses the client's default configuration and a fresh HttpCoreContext.
CompletableFuture<WebSocket>	connect(URI uri, WebSocketListener listener, WebSocketClientConfig cfg) Convenience overload that uses a fresh HttpCoreContext.
CompletableFuture<WebSocket>	connect(URI uri, WebSocketListener listener, WebSocketClientConfig cfg, HttpContext context) Initiates an asynchronous WebSocket connection to the given target URI.
protected abstract CompletableFuture<WebSocket>	doConnect(URI uri, WebSocketListener listener, WebSocketClientConfig cfg, HttpContext context) Core connect hook for subclasses.
abstract IOReactorStatus	getStatus() Current I/O reactor status.
abstract void	initiateShutdown() Initiate shutdown (non-blocking).
abstract void	start() Start underlying I/O.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.hc.core5.io.ModalCloseable

close

Methods inherited from interface java.io.Closeable

close

Constructor Detail

CloseableWebSocketClient

public CloseableWebSocketClient()

Method Detail

start

public abstract void start()

Start underlying I/O. Safe to call once; subsequent calls are no-ops.

getStatus

public abstract IOReactorStatus getStatus()

Current I/O reactor status.

awaitShutdown

public abstract void awaitShutdown(TimeValue waitTime)
                            throws InterruptedException

Best-effort await of shutdown.

Throws:

InterruptedException

initiateShutdown

public abstract void initiateShutdown()

Initiate shutdown (non-blocking).

doConnect

protected abstract CompletableFuture<WebSocket> doConnect(URI uri,
                                                          WebSocketListener listener,
                                                          WebSocketClientConfig cfg,
                                                          HttpContext context)

Core connect hook for subclasses.

Parameters:

uri - target WebSocket URI (ws:// or wss://)

listener - application callbacks

cfg - optional per-connection config (may be null for defaults)

context - optional HTTP context (may be null)

connect

public final CompletableFuture<WebSocket> connect(URI uri,
                                                  WebSocketListener listener)

Convenience overload that uses the client's default configuration and a fresh HttpCoreContext.

Parameters:

uri - target WebSocket URI (ws or wss)

listener - callback for WebSocket events

Returns:

future that completes with a connected WebSocket

connect

public final CompletableFuture<WebSocket> connect(URI uri,
                                                  WebSocketListener listener,
                                                  WebSocketClientConfig cfg)

Convenience overload that uses a fresh HttpCoreContext.

Parameters:

uri - target WebSocket URI (ws or wss)

listener - callback for WebSocket events

cfg - per-connection configuration, or null for defaults

Returns:

future that completes with a connected WebSocket

connect

public final CompletableFuture<WebSocket> connect(URI uri,
                                                  WebSocketListener listener,
                                                  WebSocketClientConfig cfg,
                                                  HttpContext context)

Initiates an asynchronous WebSocket connection to the given target URI.

The URI must use the ws or wss scheme. This method performs an HTTP/1.1 upgrade to the WebSocket protocol and, on success, creates a WebSocket associated with the supplied WebSocketListener.

The operation is fully asynchronous. The returned CompletableFuture completes when the opening WebSocket handshake has either succeeded or failed.

Specified by:

connect in interface WebSocketClient

Parameters:

uri - target WebSocket URI, must not be null.

listener - callback that receives WebSocket events, must not be null.

cfg - optional per-connection configuration; if null, the client’s default configuration is used.

context - optional HTTP context for the underlying upgrade request; may be null.

Returns:

a future that completes with a connected WebSocket on success, or completes exceptionally if the connection attempt or protocol handshake fails.