Module jdk.incubator.httpclient

Package jdk.incubator.http

Interface WebSocket.Builder

Enclosing interface:

WebSocket

public static interface WebSocket.Builder

A builder for creating WebSocket instances.
Incubating Feature. Will be removed in a future release.

To build a WebSocket, create a builder, configure it as required by calling intermediate methods (the ones that return the builder itself), then finally call buildAsync() to get a CompletableFuture with resulting WebSocket.

If an intermediate method has not been called, an appropriate default value (or behavior) will be used. Unless otherwise noted, a repeated call to an intermediate method overwrites the previous value (or overrides the previous behaviour).

Instances of Builder are not safe for use by multiple threads without external synchronization.

Since:

9

Method Summary

Modifier and Type	Method	Description
CompletableFuture<WebSocket>	buildAsync()	Builds a WebSocket.
WebSocket.Builder	connectTimeout(Duration timeout)	Sets a timeout for the opening handshake.
WebSocket.Builder	header(String name, String value)	Adds the given name-value pair to the list of additional headers for the opening handshake.
WebSocket.Builder	subprotocols(String mostPreferred, String... lesserPreferred)	Includes a request for the given subprotocols during the opening handshake.

Method Detail

header

WebSocket.Builder header(String name,
                         String value)

Adds the given name-value pair to the list of additional headers for the opening handshake.

Headers defined in WebSocket Protocol are not allowed to be added.

Parameters:

name - the header name

value - the header value

Returns:

this builder

subprotocols

WebSocket.Builder subprotocols(String mostPreferred,
                               String... lesserPreferred)

Includes a request for the given subprotocols during the opening handshake.

Among the requested subprotocols at most one will be chosen by the server. This subprotocol will be available from WebSocket.getSubprotocol(). Subprotocols are specified in the order of preference.

Each of the given subprotocols must conform to the relevant rules defined in the WebSocket Protocol.

If this method is not invoked then no subprotocols are requested.

Parameters:

mostPreferred - the most preferred subprotocol

lesserPreferred - the lesser preferred subprotocols, with the least preferred at the end

Returns:

this builder

connectTimeout

WebSocket.Builder connectTimeout(Duration timeout)

Sets a timeout for the opening handshake.

If the opening handshake does not complete within the specified duration then the CompletableFuture returned from buildAsync() completes exceptionally with a HttpTimeoutException.

If this method is not invoked then the timeout is deemed infinite.

Parameters:

timeout - the timeout, non-negative, non-ZERO

Returns:

this builder

buildAsync

CompletableFuture<WebSocket> buildAsync()

Builds a WebSocket.

Returns a CompletableFuture<WebSocket> which completes normally with the WebSocket when it is connected or completes exceptionally if an error occurs.

CompletableFuture may complete exceptionally with the following errors:

• IOException - if an I/O error occurs
• WebSocketHandshakeException - if the opening handshake fails
• HttpTimeoutException - if the opening handshake does not complete within the specified duration
• InterruptedException - if the operation was interrupted
• SecurityException - if a security manager is set, and the caller does not have a URLPermission for the WebSocket URI
• IllegalArgumentException - if any of the additional headers are illegal; or if any of the WebSocket Protocol rules relevant to subprotocols are violated; or if the connect timeout is invalid;

Returns:

a CompletableFuture with the WebSocket