WebSocket.Builder (Java SE 26 & JDK 26)
Description: declaration: module: java.net.http, package: java.net.http, interface: WebSocket, interface: Builder
Keywords: java.net.http.WebSocket.Builder interface

# Interface WebSocket.Builder

Enclosing interface:
  `WebSocket`

public static interface WebSocket.Builder
A builder of WebSocket Clients.

Builders are created by invoking `HttpClient.newWebSocketBuilder`. The intermediate (setter-like) methods change the state of the builder and return the same builder they have been invoked on. If an intermediate method is not invoked, an appropriate default value (or behavior) will be assumed. A `Builder` is not safe for use by multiple threads without external synchronization.

Since:
  11

- ## Method Summary

  Modifier and Type
  Method
  Description
  `CompletableFuture<WebSocket>`
  `buildAsync(URI uri, WebSocket.Listener listener)`
  Builds a `WebSocket` connected to the given `URI` and associated with the given `Listener`.
  `WebSocket.Builder`
  `connectTimeout(Duration timeout)`
  Sets a timeout for establishing a WebSocket connection.
  `WebSocket.Builder`
  `header(String name, String value)`
  Adds the given name-value pair to the list of additional HTTP headers sent during the opening handshake.
  `WebSocket.Builder`
  `subprotocols(String mostPreferred, String... lesserPreferred)`
  Sets a request for the given subprotocols.

- ## Method Details

  - ### header

    WebSocket.Builder header(String name, String value)
    Adds the given name-value pair to the list of additional HTTP headers sent during the opening handshake.

    Headers defined in the WebSocket Protocol are illegal. If this method is not invoked, no additional HTTP headers will be sent.

    Parameters:
      `name` - the header name
      `value` - the header value
    Returns:
      this builder

  - ### connectTimeout

    WebSocket.Builder connectTimeout(Duration timeout)
    Sets a timeout for establishing a WebSocket connection.

    If the connection is not established within the specified duration then building of the `WebSocket` will fail with `HttpTimeoutException`. If this method is not invoked then the infinite timeout is assumed.

    Implementation Requirements:
      A connection timeout applies to the entire connection phase, from the moment a connection is requested until it is established. Implementations are recommended to ensure that the connection timeout covers any WebSocket and SSL/TLS handshakes.
    Implementation Note:
      The built-in JDK implementation of the connection timeout covers any WebSocket and SSL/TLS handshakes.
    Parameters:
      `timeout` - the timeout, non-negative, non-ZERO
    Returns:
      this builder

  - ### subprotocols

    WebSocket.Builder subprotocols(String mostPreferred, String... lesserPreferred)
    Sets a request for the given subprotocols.

    After the `WebSocket` has been built, the actual subprotocol can be queried through `WebSocket.getSubprotocol()`.

    Subprotocols are specified in the order of preference. The most preferred subprotocol is specified first. If there are any additional subprotocols they are enumerated from the most preferred to the least preferred.

    Subprotocols not conforming to the syntax of subprotocol identifiers are illegal. If this method is not invoked then no subprotocols will be requested.

    Parameters:
      `mostPreferred` - the most preferred subprotocol
      `lesserPreferred` - the lesser preferred subprotocols
    Returns:
      this builder

  - ### buildAsync

    CompletableFuture<WebSocket> buildAsync(URI uri, WebSocket.Listener listener)
    Builds a `WebSocket` connected to the given `URI` and associated with the given `Listener`.

    Returns a `CompletableFuture` which will either complete normally with the resulting `WebSocket` or complete exceptionally with one of 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 timeout
    - `InterruptedException` - if the operation is interrupted
    - `IllegalArgumentException` - if any of the arguments of this builder's methods are illegal
    Parameters:
      `uri` - the WebSocket URI
      `listener` - the listener
    Returns:
      a `CompletableFuture` with the `WebSocket`