/**
* 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 {@linkplain WebSocket#request(long) requests one more
* message}.
* @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 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.
*
* @implNote
* <p>Replies with a Pong message and requests one more message when the Pong has been sent.
* @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) {
return webSocket.sendPong(message).thenRun(() -> webSocket.request(1));
}
/**
* Receives a Text message.
*
* <p>The {@code onText} method is invoked zero or more times between {@code onOpen} and ({@code
* onClose} or {@code onError}).
*
* <p>This message may be a partial UTF-16 sequence. However, the concatenation of all messages
* through the last will be a whole UTF-16 sequence.
*
* <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 the exception.
*
* @implSpec The default implementation {@linkplain WebSocket#request(long) requests one more
* message}.
* @implNote This implementation passes only complete UTF-16 sequences to the {@code onText}
* method.
* @param webSocket the WebSocket
* @param message the message
* @param part the part
* @return a CompletionStage that completes when the message processing is done; or {@code null}
* if already done
*/
default CompletionStage<?> onText(WebSocket webSocket, CharSequence message, MessagePart part) {
webSocket.request(1);
return null;
}
/**
* Receives a Binary message.
*
* <p>The {@code onBinary} method is invoked zero or more times 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 {@linkplain WebSocket#request(long) requests one more
* message}.
* @param webSocket the WebSocket
* @param message the message
* @param part the part
* @return a CompletionStage that completes when the message processing is done; or {@code null}
* if already done
*/
default CompletionStage<?> onBinary(WebSocket webSocket, ByteBuffer message, MessagePart part) {
webSocket.request(1);
return null;
}
/**
* Notifies the {@code Listener} that it is connected to the provided {@code WebSocket}.
*
* <p>The {@code onOpen} method does not correspond to any message from the WebSocket Protocol.
* It is a synthetic event. It is the first {@code Listener}'s method to be invoked. No other
* {@code Listener}'s methods are invoked before this one. The method is usually used to make an
* initial {@linkplain WebSocket#request(long) request} for messages.
*
* <p>If an exception is thrown from this method then {@link #onError(WebSocket, Throwable)
* onError} will be invoked with the exception.
*
* @implSpec The default implementation {@linkplain WebSocket#request(long) requests one
* message}.
* @param webSocket the WebSocket
*/
default void onOpen(WebSocket webSocket) {
webSocket.request(1);
}
