Module java.httpclient

Package java.net.http

Interface WebSocket.Builder

Enclosing interface:

WebSocket

public static interface WebSocket.Builder

A builder for creating WebSocket instances.

To build a WebSocket, instantiate 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), if no exception is thrown.

Instances of Builder may not be safe for use by multiple threads.

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

Throws:

IllegalArgumentException - if the name is a WebSocket defined header name

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. When the WebSocket is connected, the subprotocol in use is available from WebSocket.getSubprotocol(). Subprotocols may be specified in the order of preference.

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

Parameters:

mostPreferred - the most preferred subprotocol

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

Returns:

this builder

Throws:

IllegalArgumentException - if any of the WebSocket Protocol rules relevant to subprotocols are violated

connectTimeout

WebSocket.Builder connectTimeout(Duration timeout)

Sets a timeout for the opening handshake.

If the opening handshake is not finished within the specified amount of time then buildAsync() completes exceptionally with a HttpTimeoutException.

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

Parameters:

timeout - the timeout

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
• 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
• WebSocketHandshakeException if the opening handshake fails

Returns:

a CompletableFuture with the WebSocket