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

## Interface WebSocket

-     public interface WebSocket

  A WebSocket client conforming to RFC 6455.
  Incubating Feature. Will be removed in a future release.

  A `WebSocket` provides full-duplex communication over a TCP connection.

  To create a `WebSocket` use a builder. Once a `WebSocket` is built, it's ready to send and receive messages. When the `WebSocket` is no longer needed it must be closed: a Close message must both be sent and received. The `WebSocket` may be also closed abruptly.

  Once closed the `WebSocket` remains closed and cannot be reopened.

  Messages of type `X` (where `X` is one of: Text, Binary, Ping, Pong or Close) are sent and received asynchronously through the `WebSocket.send{X}` and `WebSocket.Listener``.on{X}` methods respectively. Each method returns a `CompletionStage` which completes when the operation has completed.

  Note that messages (of any type) are received only if requested.

  One outstanding send operation is permitted. No further send operation can be initiated before the previous one has completed. When sending, a message must not be modified until the returned `CompletableFuture` completes (either normally or exceptionally).

  Text and Binary messages can be sent and received as a whole or in parts. A whole message is transferred as a sequence of one or more invocations of a corresponding method where the last invocation is identified via an additional method argument.

  If the message is contained in a `ByteBuffer`, bytes are considered arranged from the `buffer`'s `position` to the `buffer`'s `limit`.

  Unless otherwise stated, `null` parameter values will cause methods and constructors to throw `NullPointerException`.

  Implementation Note:
    This implementation's methods do not block before returning a `CompletableFuture`.
  Since:
    9

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static interface` | `WebSocket.Builder` | A builder for creating `WebSocket` instances.
    `static interface` | `WebSocket.Listener` | A listener for events and messages on a `WebSocket`.
    `static class` | `WebSocket.MessagePart` | A marker used by `WebSocket.Listener` in cases where a partial message may be received.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `NORMAL_CLOSURE` | The WebSocket Close message status code (`1000`), indicating normal closure, meaning that the purpose for which the connection was established has been fulfilled.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `abort​()` | Closes the `WebSocket` abruptly.
    `String` | `getSubprotocol​()` | Returns a subprotocol which has been chosen for this `WebSocket`.
    `boolean` | `isClosed​()` | Tells whether the `WebSocket` is closed.
    `void` | `request​(long n)` | Allows `n` more messages to be received by the `Listener`.
    `CompletableFuture<WebSocket>` | `sendBinary​(ByteBuffer message, boolean isLast)` | Sends a Binary message with bytes from the given `ByteBuffer`.
    `CompletableFuture<WebSocket>` | `sendClose​(int statusCode, String reason)` | Sends a Close message with the given status code and the reason.
    `CompletableFuture<WebSocket>` | `sendPing​(ByteBuffer message)` | Sends a Ping message with bytes from the given ByteBuffer.
    `CompletableFuture<WebSocket>` | `sendPong​(ByteBuffer message)` | Sends a Pong message with bytes from the given ByteBuffer.
    `CompletableFuture<WebSocket>` | `sendText​(CharSequence message, boolean isLast)` | Sends a Text message with characters from the given `CharSequence`.

- - ### Field Detail

    - #### NORMAL_CLOSURE

          static final int NORMAL_CLOSURE

      The WebSocket Close message status code (`1000`), indicating normal closure, meaning that the purpose for which the connection was established has been fulfilled.
      See Also:
        `sendClose(int, String)`, `WebSocket.Listener.onClose(WebSocket, int, String)`, Constant Field Values

  - ### Method Detail

    - #### sendText

          CompletableFuture<WebSocket> sendText​(CharSequence message,
                                                boolean isLast)

      Sends a Text message with characters from the given `CharSequence`.

      Returns a `CompletableFuture<WebSocket>` which completes normally when the message has been sent or completes exceptionally if an error occurs.

      The `CharSequence` must not be modified until the returned `CompletableFuture` completes (either normally or exceptionally).

      The returned `CompletableFuture` can complete exceptionally with:

      - `IllegalArgumentException` - if `message` is a malformed UTF-16 sequence
      - `IllegalStateException` - if the `WebSocket` is closed; or if a Close message has been sent; or if there is an outstanding send operation; or if a previous Binary message was sent with `isLast == false`
      - `IOException` - if an I/O error occurs during this operation; or if the `WebSocket` has been closed due to an error;
      Implementation Note:
        This implementation does not accept partial UTF-16 sequences. In case such a sequence is passed, a returned `CompletableFuture` completes exceptionally with `IOException`.
      Parameters:
        `message` - the message
        `isLast` - `true` if this is the last part of the message, `false` otherwise
      Returns:
        a `CompletableFuture` with this `WebSocket`

    - #### sendBinary

          CompletableFuture<WebSocket> sendBinary​(ByteBuffer message,
                                                  boolean isLast)

      Sends a Binary message with bytes from the given `ByteBuffer`.

      Returns a `CompletableFuture<WebSocket>` which completes normally when the message has been sent or completes exceptionally if an error occurs.

      The returned `CompletableFuture` can complete exceptionally with:

      - `IllegalStateException` - if the `WebSocket` is closed; or if a Close message has been sent; or if there is an outstanding send operation; or if a previous Text message was sent with `isLast == false`
      - `IOException` - if an I/O error occurs during this operation; or if the `WebSocket` has been closed due to an error
      Parameters:
        `message` - the message
        `isLast` - `true` if this is the last part of the message, `false` otherwise
      Returns:
        a `CompletableFuture` with this `WebSocket`

    - #### sendPing

          CompletableFuture<WebSocket> sendPing​(ByteBuffer message)

      Sends a Ping message with bytes from the given ByteBuffer.

      Returns a `CompletableFuture<WebSocket>` which completes normally when the message has been sent or completes exceptionally if an error occurs.

      A Ping message may be sent or received by either client or server. It may serve either as a keepalive or as a means to verify that the remote endpoint is still responsive.

      The message must consist of not more than `125` bytes: `message.remaining() <= 125`.

      The returned `CompletableFuture` can complete exceptionally with:

      - `IllegalArgumentException` - if `message.remaining() > 125`
      - `IllegalStateException` - if the `WebSocket` is closed; or if a Close message has been sent; or if there is an outstanding send operation
      - `IOException` - if an I/O error occurs during this operation; or if the `WebSocket` has been closed due to an error
      Parameters:
        `message` - the message
      Returns:
        a `CompletableFuture` with this `WebSocket`

    - #### sendPong

          CompletableFuture<WebSocket> sendPong​(ByteBuffer message)

      Sends a Pong message with bytes from the given ByteBuffer.

      Returns a `CompletableFuture<WebSocket>` which completes normally when the message has been sent or completes exceptionally if an error occurs.

      A Pong message may be unsolicited or may be sent in response to a previously received Ping. In latter case the contents of the Pong must be identical to the originating Ping.

      The message must consist of not more than `125` bytes: `message.remaining() <= 125`.

      The returned `CompletableFuture` can complete exceptionally with:

      - `IllegalArgumentException` - if `message.remaining() > 125`
      - `IllegalStateException` - if the `WebSocket` is closed; or if a Close message has been sent; or if there is an outstanding send operation
      - `IOException` - if an I/O error occurs during this operation; or if the `WebSocket` has been closed due to an error
      Parameters:
        `message` - the message
      Returns:
        a `CompletableFuture` with this `WebSocket`

    - #### sendClose

          CompletableFuture<WebSocket> sendClose​(int statusCode,
                                                 String reason)

      Sends a Close message with the given status code and the reason.

      When this method has been invoked, no further messages can be sent.

      The `statusCode` is an integer in the range `1000 <= code <= 4999`. However, not all status codes may be legal in some implementations. Regardless of an implementation, `1000` is always legal and `1002`, `1003`, `1005`, `1006`, `1007`, `1009`, `1010`, `1012`, `1013` and `1015` are always illegal codes.

      The `reason` is a short string that must have an UTF-8 representation not longer than `123` bytes. For more details on Close message, status codes and reason see RFC 6455 sections 5.5.1. Close and 7.4. Status Codes.

      The method returns a `CompletableFuture<WebSocket>` which completes normally when the message has been sent or completes exceptionally if an error occurs.

      The returned `CompletableFuture` can complete exceptionally with:

      - `IllegalArgumentException` - if the `statusCode` has an illegal value; or if `reason` doesn't have an UTF-8 representation of length `<= 123`
      - `IOException` - if an I/O error occurs during this operation; or the `WebSocket` has been closed due to an error

      If this method has already been invoked or the `WebSocket` is closed, then subsequent invocations of this method have no effect and the returned `CompletableFuture` completes normally.

      If a Close message has been received before, then this invocation completes the closing handshake and by the time the returned `CompletableFuture` completes, the `WebSocket` will have been closed.

      Parameters:
        `statusCode` - the status code
        `reason` - the reason
      Returns:
        a `CompletableFuture` with this `WebSocket`

    - #### request

          void request​(long n)

      Allows `n` more messages to be received by the `Listener`.

      The actual number of received messages might be fewer if a Close message is received, the `WebSocket` closes or an error occurs.

      A `WebSocket` that has just been built, hasn't requested anything yet. Usually the initial request for messages is made in `Listener.onOpen`.

      If the `WebSocket` is closed then invoking this method has no effect.

      Implementation Note:
        This implementation does not distinguish between partial and whole messages, because it's not known beforehand how a message will be received.

        If a server sends more messages than requested, this implementation queues up these messages on the TCP connection and may eventually force the sender to stop sending through TCP flow control.

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

    - #### getSubprotocol

          String getSubprotocol​()

      Returns a subprotocol which has been chosen for this `WebSocket`.
      Returns:
        a subprotocol, or an empty `String` if there is none

    - #### isClosed

          boolean isClosed​()

      Tells whether the `WebSocket` is closed.

      When a `WebSocket` is closed no further messages can be sent or received.

      Returns:
        `true` if the `WebSocket` is closed, `false` otherwise

    - #### abort

          void abort​()
              throws IOException

      Closes the `WebSocket` abruptly.

      This method may be invoked at any time. This method closes the underlying TCP connection and puts the `WebSocket` into a closed state.

      As the result `Listener.onClose` will be invoked unless either `onClose` or `onError` has been invoked before. In which case no additional invocation will happen.

      If the `WebSocket` is already closed then invoking this method has no effect.

      Throws:
        `IOException` - if an I/O error occurs