Interface WebSocket.Builder

  • All Known Implementing Classes:
    BuilderImpl
    Enclosing interface:
    WebSocket


    public static interface WebSocket.Builder
    A builder for creating WebSocket instances.

    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 Detail

      • header

        WebSocket.Builder header(java.lang.String name,
                                 java.lang.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(java.lang.String mostPreferred,
                                       java.lang.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(java.time.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

        java.util.concurrent.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