jdk-sandbox: comparison jdk/src/java.httpclient/share/classes/java/net/http/WebSocket.java

equal deleted inserted replaced

-:e031aa31b25f
+:bf2b41533aed
 * String) received}. Or to close abruptly, {@link #abort()} is called. Once
 * closed it remains closed, cannot be reopened.
 *
 * <p> Messages of type {@code X} are sent through the {@code WebSocket.sendX}
 * methods and received through {@link WebSocket.Listener}{@code .onX} methods
-* asynchronously. Each of the methods begins the operation and returns a {@link
+* asynchronously. Each of the methods returns a {@link CompletionStage} which
-* CompletionStage} which completes when the operation has completed.
+* completes when the operation has completed.
 *
 * <p> Messages are received only if {@linkplain #request(long) requested}.
 *
 * <p> One outstanding send operation is permitted: if another send operation is
 * initiated before the previous one has completed, an {@link
 * HttpClient}.
 *
 * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
 * or method of this type will cause a {@link NullPointerException
 * NullPointerException} to be thrown.
+*
+* @implNote The default implementation's methods do not block before returning
+* a {@code CompletableFuture}.
 *
 * @since 9
 */
 public interface WebSocket {
 Builder connectTimeout(long timeout, TimeUnit unit);
 /**
 * Builds a {@code WebSocket}.
 *
-* <p> Returns immediately with a {@code CompletableFuture<WebSocket>}
+* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
-* which completes with the {@code WebSocket} when it is connected, or
+* normally with the {@code WebSocket} when it is connected or completes
-* completes exceptionally if an error occurs.
+* exceptionally if an error occurs.
 *
 * <p> {@code CompletableFuture} may complete exceptionally with the
 * following errors:
 * <ul>
 * <li> {@link IOException}
 *          have a {@link java.net.URLPermission} for the WebSocket URI
 * <li> {@link WebSocketHandshakeException}
 *          if the opening handshake fails
 * </ul>
 *
-* @return a {@code CompletableFuture} of {@code WebSocket}
+* @return a {@code CompletableFuture} with the {@code WebSocket}
 */
 CompletableFuture<WebSocket> buildAsync();
 }
 /**
 }
 /**
 * Sends a Text message with characters from the given {@code CharSequence}.
 *
-* <p> Returns immediately with a {@code CompletableFuture<Void>} which
+* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
-* completes normally when the message has been sent, or completes
+* normally when the message has been sent or completes exceptionally if an
-* exceptionally if an error occurs.
+* error occurs.
 *
 * <p> The {@code CharSequence} should not be modified until the returned
 * {@code CompletableFuture} completes (either normally or exceptionally).
 *
 * <p> The returned {@code CompletableFuture} can complete exceptionally
 * with:
 * <ul>
 * <li> {@link IOException}
-*          if an I/O error occurs during this operation; or the
+*          if an I/O error occurs during this operation
-*          {@code WebSocket} closes while this operation is in progress;
+* <li> {@link IllegalStateException}
-*          or the {@code message} is a malformed UTF-16 sequence
+*          if the {@code WebSocket} closes while this operation is in progress;
+*          or if a Close message has been sent already;
+*          or if there is an outstanding send operation;
+*          or if a previous Binary message was not sent with {@code isLast == true}
 * </ul>
 *
 * @implNote This implementation does not accept partial UTF-16
 * sequences. In case such a sequence is passed, a returned {@code
 * CompletableFuture} completes exceptionally.
-*
-* @param message
-*         the message
-* @param isLast
-*         {@code true} if this is the final part of the message
-*         {@code false} otherwise
-*
-* @return a CompletableFuture of Void
-*
-* @throws IllegalStateException
-*         if the WebSocket is closed
-* @throws IllegalStateException
-*         if a Close message has been already sent
-* @throws IllegalStateException
-*         if there is an outstanding send operation
-* @throws IllegalStateException
-*         if a previous Binary message was not sent
-*         with {@code isLast == true}
-*/
-CompletableFuture<Void> sendText(CharSequence message, boolean isLast);
-/**
-* Sends a whole Text message with characters from the given {@code
-* CharSequence}.
-*
-* <p> This is a convenience method. For the general case, use {@link
-* #sendText(CharSequence, boolean)}.
-*
-* <p> Returns immediately with a {@code CompletableFuture<Void>} which
-* completes normally when the message has been sent, or completes
-* exceptionally if an error occurs.
-*
-* <p> The {@code CharSequence} should not be modified until the returned
-* {@code CompletableFuture} completes (either normally or exceptionally).
-*
-* <p> The returned {@code CompletableFuture} can complete exceptionally
-* with:
-* <ul>
-* <li> {@link IOException}
-*          if an I/O error occurs during this operation;
-*          or the {@code WebSocket} closes while this operation is in progress;
-*          or the message is a malformed (or an incomplete) UTF-16 sequence
-* </ul>
-*
-* @param message
-*         the message
-*
-* @return a CompletableFuture of Void
-*
-* @throws IllegalStateException
-*         if the WebSocket is closed
-* @throws IllegalStateException
-*         if a Close message has been already sent
-* @throws IllegalStateException
-*         if there is an outstanding send operation
-* @throws IllegalStateException
-*         if a previous Binary message was not sent
-*         with {@code isLast == true}
-*/
-default CompletableFuture<Void> sendText(CharSequence message) {
-return sendText(message, true);
-}
-/**
-* Sends a whole Text message with characters from {@code
-* CharacterSequence}s provided by the given {@code Stream}.
-*
-* <p> This is a convenience method. For the general case use {@link
-* #sendText(CharSequence, boolean)}.
-*
-* <p> Returns immediately with a {@code CompletableFuture<Void>} which
-* completes normally when the message has been sent, or completes
-* exceptionally if an error occurs.
-*
-* <p> Streamed character sequences should not be modified until the
-* returned {@code CompletableFuture} completes (either normally or
-* exceptionally).
-*
-* <p> The returned {@code CompletableFuture} can complete exceptionally
-* with:
-* <ul>
-* <li> {@link IOException}
-*          if an I/O error occurs during this operation;
-*          or the {@code WebSocket} closes while this operation is in progress;
-*          or the message is a malformed (or an incomplete) UTF-16 sequence
-* </ul>
-*
-* @param message
-*         the message
-*
-* @return a CompletableFuture of Void
-*
-* @throws IllegalStateException
-*         if the WebSocket is closed
-* @throws IllegalStateException
-*         if a Close message has been already sent
-* @throws IllegalStateException
-*         if there is an outstanding send operation
-* @throws IllegalStateException
-*         if a previous Binary message was not sent
-*         with {@code isLast == true}
-*/
-CompletableFuture<Void> sendText(Stream<? extends CharSequence> message);
-/**
-* Sends a Binary message with bytes from the given {@code ByteBuffer}.
-*
-* <p> Returns immediately with a {@code CompletableFuture<Void>} which
-* completes normally when the message has been sent, or completes
-* exceptionally if an error occurs.
-*
-* <p> The returned {@code CompletableFuture} can complete exceptionally
-* with:
-* <ul>
-* <li> {@link IOException}
-*          if an I/O error occurs during this operation or the
-*          {@code WebSocket} closes while this operation is in progress
-* </ul>
 *
 * @param message
 *         the message
 * @param isLast
 *         {@code true} if this is the final part of the message,
 *         {@code false} otherwise
 *
-* @return a CompletableFuture of Void
+* @return a CompletableFuture with this WebSocket
 *
-* @throws IllegalStateException
+* @throws IllegalArgumentException
-*         if the WebSocket is closed
+*         if {@code message} is a malformed (or an incomplete) UTF-16 sequence
-* @throws IllegalStateException
+*/
-*         if a Close message has been already sent
+CompletableFuture<WebSocket> sendText(CharSequence message, boolean isLast);
-* @throws IllegalStateException
-*         if there is an outstanding send operation
+/**
-* @throws IllegalStateException
+* Sends a whole Text message with characters from the given {@code
-*         if a previous Text message was not sent
+* CharSequence}.
-*         with {@code isLast == true}
+*
-*/
+* <p> This is a convenience method. For the general case, use {@link
-CompletableFuture<Void> sendBinary(ByteBuffer message, boolean isLast);
+* #sendText(CharSequence, boolean)}.
+*
-/**
+* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
-* Sends a Binary message with bytes from the given {@code byte[]}.
+* normally when the message has been sent or completes exceptionally if an
-*
+* error occurs.
-* <p> Returns immediately with a {@code CompletableFuture<Void>} which
+*
-* completes normally when the message has been sent, or completes
+* <p> The {@code CharSequence} should not be modified until the returned
-* exceptionally if an error occurs.
+* {@code CompletableFuture} completes (either normally or exceptionally).
 *
 * <p> The returned {@code CompletableFuture} can complete exceptionally
 * with:
 * <ul>
 * <li> {@link IOException}
-*          if an I/O error occurs during this operation or the
+*          if an I/O error occurs during this operation
-*          {@code WebSocket} closes while this operation is in progress
+* <li> {@link IllegalStateException}
+*          if the {@code WebSocket} closes while this operation is in progress;
+*          or if a Close message has been sent already;
+*          or if there is an outstanding send operation;
+*          or if a previous Binary message was not sent with {@code isLast == true}
 * </ul>
 *
-* @implSpec This is equivalent to:
+* @param message
-* <pre>{@code
+*         the message
-*     sendBinary(ByteBuffer.wrap(message), isLast)
+*
-* }</pre>
+* @return a CompletableFuture with this WebSocket
+*
+* @throws IllegalArgumentException
+*         if {@code message} is a malformed (or an incomplete) UTF-16 sequence
+*/
+default CompletableFuture<WebSocket> sendText(CharSequence message) {
+return sendText(message, true);
+}
+/**
+* Sends a whole Text message with characters from {@code
+* CharacterSequence}s provided by the given {@code Stream}.
+*
+* <p> This is a convenience method. For the general case use {@link
+* #sendText(CharSequence, boolean)}.
+*
+* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
+* normally when the message has been sent or completes exceptionally if an
+* error occurs.
+*
+* <p> Streamed character sequences should not be modified until the
+* returned {@code CompletableFuture} completes (either normally or
+* exceptionally).
+*
+* <p> The returned {@code CompletableFuture} can complete exceptionally
+* with:
+* <ul>
+* <li> {@link IOException}
+*          if an I/O error occurs during this operation
+* <li> {@link IllegalStateException}
+*          if the {@code WebSocket} closes while this operation is in progress;
+*          or if a Close message has been sent already;
+*          or if there is an outstanding send operation;
+*          or if a previous Binary message was not sent with {@code isLast == true}
+* </ul>
+*
+* @param message
+*         the message
+*
+* @return a CompletableFuture with this WebSocket
+*
+* @throws IllegalArgumentException
+*         if {@code message} is a malformed (or an incomplete) UTF-16 sequence
+*/
+CompletableFuture<WebSocket> sendText(Stream<? extends CharSequence> message);
+/**
+* Sends a Binary message with bytes from the given {@code ByteBuffer}.
+*
+* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
+* normally when the message has been sent or completes exceptionally if an
+* error occurs.
+*
+* <p> The returned {@code CompletableFuture} can complete exceptionally
+* with:
+* <ul>
+* <li> {@link IOException}
+*          if an I/O error occurs during this operation
+* <li> {@link IllegalStateException}
+*          if the {@code WebSocket} closes while this operation is in progress;
+*          or if a Close message has been sent already;
+*          or if there is an outstanding send operation;
+*          or if a previous Text message was not sent with {@code isLast == true}
+* </ul>
 *
 * @param message
 *         the message
 * @param isLast
 *         {@code true} if this is the final part of the message,
 *         {@code false} otherwise
 *
-* @return a CompletableFuture of Void
+* @return a CompletableFuture with this WebSocket
-*
+*/
-* @throws IllegalStateException
+CompletableFuture<WebSocket> sendBinary(ByteBuffer message, boolean isLast);
-*         if the WebSocket is closed
-* @throws IllegalStateException
+/**
-*         if a Close message has been already sent
+* Sends a Binary message with bytes from the given {@code byte[]}.
-* @throws IllegalStateException
+*
-*         if there is an outstanding send operation
+* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
-* @throws IllegalStateException
+* normally when the message has been sent or completes exceptionally if an
-*         if a previous Text message was not sent
+* error occurs.
-*         with {@code isLast == true}
-*/
-default CompletableFuture<Void> sendBinary(byte[] message, boolean isLast) {
-Objects.requireNonNull(message, "message");
-return sendBinary(ByteBuffer.wrap(message), isLast);
-}
-/**
-* Sends a Ping message.
-*
-* <p> Returns immediately with a {@code CompletableFuture<Void>} which
-* completes normally when the message has been sent, or completes
-* exceptionally if an error occurs.
-*
-* <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 must consist of not more than {@code 125} bytes: {@code
-* message.remaining() <= 125}.
 *
 * <p> The returned {@code CompletableFuture} can complete exceptionally
 * with:
 * <ul>
 * <li> {@link IOException}
-*          if an I/O error occurs during this operation or the
+*          if an I/O error occurs during this operation
-*          {@code WebSocket} closes while this operation is in progress
+* <li> {@link IllegalStateException}
+*          if the {@code WebSocket} closes while this operation is in progress;
+*          or if a Close message has been sent already;
+*          or if there is an outstanding send operation;
+*          or if a previous Text message was not sent with {@code isLast == true}
 * </ul>
+*
+* @implSpec This is equivalent to:
+* <pre>{@code
+*     sendBinary(ByteBuffer.wrap(message), isLast)
+* }</pre>
 *
 * @param message
 *         the message
-*
+* @param isLast
-* @return a CompletableFuture of Void
+*         {@code true} if this is the final part of the message,
-*
+*         {@code false} otherwise
-* @throws IllegalStateException
+*
-*         if the WebSocket is closed
+* @return a CompletableFuture with this WebSocket
-* @throws IllegalStateException
+*/
-*         if a Close message has been already sent
+default CompletableFuture<WebSocket> sendBinary(byte[] message, boolean isLast) {
-* @throws IllegalStateException
+Objects.requireNonNull(message, "message");
-*         if there is an outstanding send operation
+return sendBinary(ByteBuffer.wrap(message), isLast);
-* @throws IllegalArgumentException
+}
-*         if {@code message.remaining() > 125}
-*/
+/**
-CompletableFuture<Void> sendPing(ByteBuffer message);
+* Sends a Ping message.
+*
-/**
+* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
-* Sends a Pong message.
+* normally when the message has been sent or completes exceptionally if an
-*
+* error occurs.
-* <p> Returns immediately with a {@code CompletableFuture<Void>} which
+*
-* completes normally when the message has been sent, or completes
+* <p> A Ping message may be sent or received by either client or server.
-* exceptionally if an error occurs.
+* It may serve either as a keepalive or as a means to verify that the
-*
+* remote endpoint is still responsive.
-* <p> 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 is
-* identical to the originating Ping.
 *
 * <p> The message must consist of not more than {@code 125} bytes: {@code
 * message.remaining() <= 125}.
 *
 * <p> The returned {@code CompletableFuture} can complete exceptionally
 * with:
 * <ul>
 * <li> {@link IOException}
-*          if an I/O error occurs during this operation or the
+*          if an I/O error occurs during this operation
-*          {@code WebSocket} closes while this operation is in progress
+* <li> {@link IllegalStateException}
+*          if the {@code WebSocket} closes while this operation is in progress;
+*          or if a Close message has been sent already;
+*          or if there is an outstanding send operation
 * </ul>
 *
 * @param message
 *         the message
 *
-* @return a CompletableFuture of Void
+* @return a CompletableFuture with this WebSocket
 *
-* @throws IllegalStateException
-*         if the WebSocket is closed
-* @throws IllegalStateException
-*         if a Close message has been already sent
-* @throws IllegalStateException
-*         if there is an outstanding send operation
 * @throws IllegalArgumentException
 *         if {@code message.remaining() > 125}
 */
-CompletableFuture<Void> sendPong(ByteBuffer message);
+CompletableFuture<WebSocket> sendPing(ByteBuffer message);
+/**
+* Sends a Pong message.
+*
+* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
+* normally when the message has been sent or completes exceptionally if an
+* error occurs.
+*
+* <p> 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 is
+* identical to the originating Ping.
+*
+* <p> The message must consist of not more than {@code 125} bytes: {@code
+* message.remaining() <= 125}.
+*
+* <p> The returned {@code CompletableFuture} can complete exceptionally
+* with:
+* <ul>
+* <li> {@link IOException}
+*          if an I/O error occurs during this operation
+* <li> {@link IllegalStateException}
+*          if the {@code WebSocket} closes while this operation is in progress;
+*          or if a Close message has been sent already;
+*          or if there is an outstanding send operation
+* </ul>
+*
+* @param message
+*         the message
+*
+* @return a CompletableFuture with this WebSocket
+*
+* @throws IllegalArgumentException
+*         if {@code message.remaining() > 125}
+*/
+CompletableFuture<WebSocket> sendPong(ByteBuffer message);
 /**
 * Sends a Close message with the given close code and the reason.
 *
-* <p> Returns immediately with a {@code CompletableFuture<Void>} which
+* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
-* completes normally when the message has been sent, or completes
+* normally when the message has been sent or completes exceptionally if an
-* exceptionally if an error occurs.
+* error occurs.
 *
 * <p> A Close message may consist of a close code and a reason for closing.
 * The reason must have a valid UTF-8 representation not longer than {@code
 * 123} bytes. The reason may be useful for debugging or passing information
 * relevant to the connection but is not necessarily human readable.
 *
 * <p> The returned {@code CompletableFuture} can complete exceptionally
 * with:
 * <ul>
 * <li> {@link IOException}
-*          if an I/O error occurs during this operation or the
+*          if an I/O error occurs during this operation
-*          {@code WebSocket} closes while this operation is in progress
+* <li> {@link IllegalStateException}
+*          if the {@code WebSocket} closes while this operation is in progress;
+*          or if a Close message has been sent already;
+*          or if there is an outstanding send operation
 * </ul>
 *
 * @param code
 *         the close code
 * @param reason
 *         the reason; can be empty
 *
-* @return a CompletableFuture of Void
+* @return a CompletableFuture with this WebSocket
 *
-* @throws IllegalStateException
-*         if the WebSocket is closed
-* @throws IllegalStateException
-*         if a Close message has been already sent
-* @throws IllegalStateException
-*         if there is an outstanding send operation
 * @throws IllegalArgumentException
-*         if the {@code reason} doesn't have a valid UTF-8
+*         if {@code reason} doesn't have an UTF-8 representation not longer
-*         representation not longer than {@code 123} bytes
+*         than {@code 123} bytes
 */
-CompletableFuture<Void> sendClose(CloseCode code, CharSequence reason);
+CompletableFuture<WebSocket> sendClose(CloseCode code, CharSequence reason);
 /**
 * Sends an empty Close message.
 *
-* <p> Returns immediately with a {@code CompletableFuture<Void>} which
+* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
-* completes normally when the message has been sent, or completes
+* normally when the message has been sent or completes exceptionally if an
-* exceptionally if an error occurs.
+* error occurs.
 *
 * <p> The returned {@code CompletableFuture} can complete exceptionally
 * with:
 * <ul>
 * <li> {@link IOException}
-*          if an I/O error occurs during this operation or the
+*          if an I/O error occurs during this operation
-*          {@code WebSocket} closes while this operation is in progress
+* <li> {@link IllegalStateException}
+*          if the {@code WebSocket} closes while this operation is in progress;
+*          or if a Close message has been sent already;
+*          or if there is an outstanding send operation
 * </ul>
 *
-* @return a CompletableFuture of Void
+* @return a CompletableFuture with this WebSocket
-*
+*/
-* @throws IllegalStateException
+CompletableFuture<WebSocket> sendClose();
-*         if the WebSocket is closed
-* @throws IllegalStateException
-*         if a Close message has been already sent
-* @throws IllegalStateException
-*         if there is an outstanding send operation
-*/
-CompletableFuture<Void> sendClose();
 /**
 * Requests {@code n} more messages to be received by the {@link Listener
 * Listener}.
 *

changeset 38864	bf2b41533aed
parent 38856	cc3a0d1e96e0
child 39133	b5641ce64cf7