Preliminary RFR JDK-8159053: Improve onPing/onClose behavior

[Chris Hegarty]

I think this is good.

Just some ideas to simplify the wording.

    * <p> After a Close message has been received, the implementation will
    * close the connection automatically. However, the client may finish
    * sending the current sequence of partially sent message parts, if any.
    * To facilitate this, the WebSocket implementation will only
    * 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.

Otherwise, the simplifications are welcome.

-Chris.

> On 17 Jun 2016, at 16:15, Pavel Rappo <pavel.rappo at oracle.com> wrote:
> 
> 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 Close message.
>     *
>     * …..
>     *
>     * <p> After a Close message has been received, the implementation will
>     * close the connection automatically. However, the client may finish
>     * sending the current sequence of partially sent message parts, if any.
>     * To facilitate this, the WebSocket implementation will only
>     * 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.