Module jdk.incubator.httpclient
Package jdk.incubator.http

Interface WebSocket

  • public interface WebSocket
    A WebSocket client.
    Incubating Feature. Will be removed in a future release.

    To create a WebSocket use the HttpClient.newWebSocketBuilder() method. To close a WebSocket use one of the sendClose or abort methods.

    WebSocket messages are sent through a WebSocket and received through the WebSocket's Listener. Messages can be sent until the output is closed, and received until the input is closed. A WebSocket whose output and input are both closed may be considered itself closed. To check these states use isOutputClosed() and isInputClosed().

    Methods that send messages return CompletableFuture which completes normally if the message is sent or completes exceptionally if an error occurs.

    To receive a message, first request it. If n messages are requested, the listener will receive up to n more invocations of the designated methods from the WebSocket. To request messages use request(long). Request is an additive operation, that is request(n) followed by request(m) is equivalent to request(n + m).

    When sending or receiving a message in parts, a whole message is transferred as a sequence of one or more invocations where the last invocation is identified via an additional method argument.

    Unless otherwise stated, null arguments will cause methods of WebSocket to throw NullPointerException, similarly, WebSocket will not pass null arguments to methods of Listener.

    Implementation Requirements:
    Methods of WebSocket are failure-atomic in respect to NullPointerException, IllegalArgumentException and IllegalStateException. That is, if a method throws said exception, or a returned CompletableFuture completes exceptionally with said exception, the WebSocket will behave as if the method has not been invoked at all.

    A WebSocket invokes methods of its listener in a thread-safe manner.

    WebSocket handles Ping and Close messages automatically (as per RFC 6455) by replying with Pong and Close messages respectively. If the listener receives Ping or Close messages, no mandatory actions from the listener are required.

    Since:
    9

    • Method Detail

      • sendText

        CompletableFuture<WebSocket> sendText​(CharSequence message,
                                      boolean isLast)
        Sends a Text message with characters from the given CharSequence.

        To send a Text message invoke this method only after the previous Text or Binary message has been sent. The character sequence must not be modified until the CompletableFuture returned from this method has completed.

        A CompletableFuture returned from this method can complete exceptionally with:

        Implementation Note:
        If a partial UTF-16 sequence is passed to this method, a CompletableFuture returned will complete exceptionally with IOException.
        Parameters:
        message - the message
        isLast - true if this is the last part of the message, false otherwise
        Returns:
        a CompletableFuture that completes, with this WebSocket, when the message has been sent

      • sendBinary

        CompletableFuture<WebSocket> sendBinary​(ByteBuffer message,
                                        boolean isLast)
        Sends a Binary message with bytes from the given ByteBuffer.

        To send a Binary message invoke this method only after the previous Text or Binary message has been sent. The message consists of bytes from the buffer's position to its limit. Upon normal completion of a CompletableFuture returned from this method the buffer will have no remaining bytes. The buffer must not be accessed until after that.

        The CompletableFuture returned from this method can complete exceptionally with:

        • IllegalStateException - if sendClose has been invoked or if the previous message has not been sent yet or if a previous Text message was sent with isLast == false
        • IOException - if an I/O error occurs
        Parameters:
        message - the message
        isLast - true if this is the last part of the message, false otherwise
        Returns:
        a CompletableFuture that completes, with this WebSocket, when the message has been sent

      • sendPing

        CompletableFuture<WebSocket> sendPing​(ByteBuffer message)
        Sends a Ping message with bytes from the given ByteBuffer.

        The message consists of not more than 125 bytes from the buffer's position to its limit. Upon normal completion of a CompletableFuture returned from this method the buffer will have no remaining bytes. The buffer must not be accessed until after that.

        The CompletableFuture returned from this method can complete exceptionally with:

        Parameters:
        message - the message
        Returns:
        a CompletableFuture that completes, with this WebSocket, when the Ping message has been sent

      • sendPong

        CompletableFuture<WebSocket> sendPong​(ByteBuffer message)
        Sends a Pong message with bytes from the given ByteBuffer.

        The message consists of not more than 125 bytes from the buffer's position to its limit. Upon normal completion of a CompletableFuture returned from this method the buffer will have no remaining bytes. The buffer must not be accessed until after that.

        The CompletableFuture returned from this method can complete exceptionally with:

        Parameters:
        message - the message
        Returns:
        a CompletableFuture that completes, with this WebSocket, when the Pong message has been sent

      • sendClose

        CompletableFuture<WebSocket> sendClose​(int statusCode,
                                       String reason)
        Sends a Close message with the given status code and the reason, initiating an orderly closure.

        When this method returns the output will have been closed.

        The statusCode is an integer from the range 1000 <= code <= 4999. Status codes 1002, 1003, 1006, 1007, 1009, 1010, 1012, 1013 and 1015 are illegal. Behaviour in respect to other status codes is implementation-specific. The reason is a string that has an UTF-8 representation not longer than 123 bytes.

        Use the provided integer constant NORMAL_CLOSURE as a status code and an empty string as a reason in a typical case.

        A CompletableFuture returned from this method can complete exceptionally with:

        Implementation Requirements:
        An endpoint sending a Close message might not receive a complementing Close message in a timely manner for a variety of reasons. The WebSocket implementation is responsible for providing a closure mechanism that guarantees that once sendClose method has been invoked the WebSocket will close regardless of whether or not a Close frame has been received and without further intervention from the user of this API. Method sendClose is designed to be, possibly, the last call from the user of this API.
        Parameters:
        statusCode - the status code
        reason - the reason
        Returns:
        a CompletableFuture that completes, with this WebSocket, when the Close message has been sent

      • request

        void request​(long n)
        Requests n more messages from this WebSocket.

        This WebSocket will invoke its listener's onText, onBinary, onPing, onPong or onClose methods up to n more times.

        This method may be invoked at any time.

        Parameters:
        n - the number of messages requested
        Throws:
        IllegalArgumentException - if n <= 0

      • getSubprotocol

        String getSubprotocol()
        Returns the subprotocol for this WebSocket.

        This method may be invoked at any time.

        Returns:
        the subprotocol for this WebSocket, or an empty String if there's no subprotocol

      • isOutputClosed

        boolean isOutputClosed()
        Tells whether or not this WebSocket is permanently closed for sending messages.

        If this method returns true, subsequent invocations will also return true. This method may be invoked at any time.

        Returns:
        true if closed, false otherwise

      • isInputClosed

        boolean isInputClosed()
        Tells whether or not this WebSocket is permanently closed for receiving messages.

        If this method returns true, subsequent invocations will also return true. This method may be invoked at any time.

        Returns:
        true if closed, false otherwise

      • abort

        void abort()
        Closes this WebSocket abruptly.

        When this method returns both the input and output will have been closed. This method may be invoked at any time. Subsequent invocations have no effect.

        API Note:
        Depending on its implementation, the state (for example, whether or not a message is being transferred at the moment) and possible errors while releasing associated resources, this WebSocket may invoke its listener's onError.