Fwd: Preliminary RFR JDK-8159053: Improve onPing/onClose behavior
Pavel Rappo
pavel.rappo at oracle.com
Fri Jun 17 18:37:16 UTC 2016
Sorry for the wrong method. There should've been onPing instead of onPong.
What's wrong with these two?
/**
* Receives a Ping message.
*
* <p> 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.
*
* <p> The message will consist of not more than {@code 125} bytes:
* {@code message.remaining() <= 125}.
*
* <p> The {@code onPing} 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.
*
* <p> The WebSocket implementation responds to the received Ping
* message using a strategy of its choice, but withing the boundaries of
* the WebSocket Protocol. It may call this method after handling the
* Ping message or before doing so. In other words no particular
* ordering is guaranteed. If an error occurs while implementation
* handles this Ping message, then {@code onError} will be invoked with
* this error.
*
* <p> For more information on handling Ping messages see RFC 6455 sections
* <a href="https://tools.ietf.org/html/rfc6455#section-5.5.2">5.5.2. Ping</a> and
* <a href="https://tools.ietf.org/html/rfc6455#section-5.5.3">5.5.2. Pong</a>.
*
* @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<?> onPing(WebSocket webSocket,
ByteBuffer message) {
webSocket.request(1);
return null;
}
> Begin forwarded message:
>
> From: Pavel Rappo <pavel.rappo at oracle.com>
> Subject: Preliminary RFR JDK-8159053: Improve onPing/onClose behavior
> Date: 17 June 2016 at 16:15:59 IST
> To: OpenJDK Network Dev list <net-dev at openjdk.java.net>
>
> 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.
More information about the net-dev
mailing list