Preliminary RFR JDK-8159053: Improve onPing/onClose behavior

[Pavel Rappo]

Hi,

Could you please [*] review the following change for the upcoming JDK-8159053?
This change addresses:

1. Listener.onClose/onPing behaviour, making the implementation fully*
responsible of protocol compliance. So reactions on onClose/onPing cannot be
overridden/redefined in a Listener

2. Simpler representation of the Close message.

    /**
     * Receives a Pong message.
     *
     * <p> A Pong message may be unsolicited or may be received in response
     * to a previously sent Ping. In the latter case, the contents of the
     * Pong is identical to the originating Ping.
     *
     * <p> The message will consist of not more than {@code 125} bytes:
     * {@code message.remaining() <= 125}.
     *
     * <p> The {@code onPong} method is invoked zero or more times in
     * between {@code onOpen} and ({@code onClose} or {@code onError}).
     *
     * <p> If an exception is thrown from this method or the returned {@code
     * CompletionStage} completes exceptionally, then {@link
     * #onError(WebSocket, Throwable) onError} will be invoked with this
     * exception.
     *
     * @implSpec The default implementation behaves as if:
     *
     * <pre>{@code
     *     webSocket.request(1);
     *     return CompletableFuture.completedStage(null);
     * }</pre>
     *
     * @param webSocket
     *         the WebSocket
     * @param message
     *         the message
     *
     * @return a CompletionStage that completes when the message processing
     * is done; or {@code null} if already done
     */
    default CompletionStage<?> onPong(WebSocket webSocket,
                                      ByteBuffer message) {
        webSocket.request(1);
        return null;
    }

    /**
     * Receives a Close message.
     *
     * <p> Once a Close message is received, the server will not send any
     * more messages.
     *
     * <p> A Close message consists of a status code and a reason for
     * closing. The status code is an integer in the range {@code 1000 <=
     * code <= 65535}. The reason is a short string that has an UTF-8
     * representation not longer than {@code 123} bytes.
     *
     * <p> For more information on status codes and reasons see
     * <a href="https://tools.ietf.org/html/rfc6455#section-7.4">RFC 6455, 7.4. Status Codes</a>.
     *
     * <p> {@code onClose} is the last invocation on the {@code Listener}.
     * It is invoked at most once, but after {@code onOpen}. If an exception
     * is thrown from this method, it is ignored.
     *
     * <p> After a Close message has been received, the implementation will
     * close the connection automatically. However, the client is allowed to
     * finish sending the current sequence of partial message first. To
     * facilitate it, the WebSocket implementation expects this method to
     * return a {@code CompletionStage}. The implementation then will
     * attempt to close the connection at the earliest of, either the
     * completion of the returned {@code CompletionStage} or the last part
     * of the current message has been sent.
     *
     * @implSpec The default implementation behaves as if:
     *
     * <pre>{@code
     *     return CompletableFuture.completedStage(null);
     * }</pre>
     *
     * @param webSocket
     *         the WebSocket
     * @param statusCode
     *         the status code
     * @param reason
     *         the reason
     *
     * @return a CompletionStage that when completed will trigger closing of
     * the WebSocket
     */
    default CompletionStage<?> onClose(WebSocket webSocket,
                                       int statusCode,
                                       String reason) {
        return null;
    }

    /**
     * Sends a Close message with the given status code and the reason.
     *
     * <p> Returns a {@code CompletableFuture<WebSocket>} which completes
     * normally when the message has been sent or completes exceptionally if an
     * error occurs.
     *
     * <p> The {@code statusCode} is an integer in the range {@code 1000 <= code
     * <= 4999}, except for {@code 1004}, {@code 1005}, {@code 1006} and {@code
     * 1015}. The {@code reason} is a short string that must have an UTF-8
     * representation not longer than {@code 123} bytes.
     *
     * <p> For more information about status codes see
     * <a href="https://tools.ietf.org/html/rfc6455#section-7.4">RFC 6455, 7.4. Status Codes</a>.)
     *
     * <p> If a Close message has been already sent or the {@code WebSocket} is
     * closed, then invoking this method has no effect and returned {@code
     * CompletableFuture} completes normally.
     *
     * <p> The returned {@code CompletableFuture} can complete exceptionally
     * with:
     * <ul>
     * <li> {@link IOException}
     *          if an I/O error occurs during this operation
     * </ul>
     *
     * @param statusCode
     *         the status code
     * @param reason
     *         the reason
     *
     * @return a CompletableFuture with this WebSocket
     *
     * @throws IllegalArgumentException
     *         if the {@code statusCode} has an illegal value, or
     *         {@code reason} doesn't have an UTF-8 representation not longer
     *         than {@code 123} bytes
     *
     * @see #sendClose()
     */
    CompletableFuture<WebSocket> sendClose(int statusCode, String reason);

    /**
     * Sends an empty Close message.
     *
     * <p> Returns a {@code CompletableFuture<WebSocket>} which completes
     * normally when the message has been sent or completes exceptionally if an
     * error occurs.
     *
     * <p> If a Close message has been already sent or the {@code WebSocket} is
     * closed, then invoking this method has no effect and returned {@code
     * CompletableFuture} completes normally.
     *
     * <p> The returned {@code CompletableFuture} can complete exceptionally
     * with:
     * <ul>
     * <li> {@link IOException}
     *          if an I/O error occurs during this operation
     * </ul>
     *
     * @return a CompletableFuture with this WebSocket
     */
    CompletableFuture<WebSocket> sendClose();

Thanks,
-Pavel

--------------------------------------------------------------------------------
[1] Please excuse me for not publishing this in a form of a webrev. The reason
is that currently there are too many outstanding changes in the queue that would
simply obscure the review.