--- a/jdk/src/java.httpclient/share/classes/java/net/http/WebSocket.java Tue Jun 21 16:52:16 2016 +0100
+++ b/jdk/src/java.httpclient/share/classes/java/net/http/WebSocket.java Tue Jun 21 18:51:18 2016 +0100
@@ -28,13 +28,11 @@
import java.net.ProtocolException;
import java.net.URI;
import java.nio.ByteBuffer;
+import java.time.Duration;
import java.util.Map;
-import java.util.Objects;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
-import java.util.concurrent.TimeUnit;
-import java.util.stream.Stream;
/**
* A WebSocket client conforming to RFC 6455.
@@ -47,8 +45,9 @@
* receive messages. When the {@code WebSocket} is no longer
* needed it must be closed: a Close message must both be {@linkplain
* #sendClose() sent} and {@linkplain Listener#onClose(WebSocket, Optional,
- * String) received}. Or to close abruptly, {@link #abort()} is called. Once
- * closed it remains closed, cannot be reopened.
+ * String) received}. Otherwise, invoke {@link #abort() abort} to close abruptly.
+ *
+ * <p> Once closed the {@code WebSocket} remains closed and 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
@@ -71,10 +70,6 @@
* arranged from the {@code buffer}'s {@link ByteBuffer#position() position} to
* the {@code buffer}'s {@link ByteBuffer#limit() limit}.
*
- * <p> All message exchange is run by the threads belonging to the {@linkplain
- * HttpClient#executorService() executor service} of {@code WebSocket}'s {@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.
@@ -217,22 +212,17 @@
* Sets a timeout for the opening handshake.
*
* <p> If the opening handshake is not finished within the specified
- * timeout then {@link #buildAsync()} completes exceptionally with a
- * {@code HttpTimeoutException}.
+ * amount of time then {@link #buildAsync()} completes exceptionally
+ * with a {@code HttpTimeoutException}.
*
- * <p> If the timeout is not specified then it's deemed infinite.
+ * <p> If this method is not invoked then the timeout is deemed infinite.
*
* @param timeout
- * the maximum time to wait
- * @param unit
- * the time unit of the timeout argument
+ * the timeout
*
* @return this builder
- *
- * @throws IllegalArgumentException
- * if the {@code timeout} is negative
*/
- Builder connectTimeout(long timeout, TimeUnit unit);
+ Builder connectTimeout(Duration timeout);
/**
* Builds a {@code WebSocket}.
@@ -506,7 +496,7 @@
* <p> Once a Close message is received, the server will not send any
* more messages.
*
- * <p> A Close message may consist of a close code and a reason for
+ * <p> A Close message may consist of a status code and a reason for
* closing. The reason will have a 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
@@ -545,12 +535,8 @@
* the time {@code onError} is invoked, no more messages can be sent on
* this {@code WebSocket}.
*
- * @apiNote Errors associated with send operations ({@link
- * WebSocket#sendText(CharSequence, boolean) sendText}, {@link
- * #sendBinary(ByteBuffer, boolean) sendBinary}, {@link
- * #sendPing(ByteBuffer) sendPing}, {@link #sendPong(ByteBuffer)
- * sendPong} and {@link #sendClose(CloseCode, CharSequence) sendClose})
- * are reported to the {@code CompletionStage} operations return.
+ * @apiNote Errors associated with {@code sendX} methods are reported to
+ * the {@code CompletableFuture} these methods return.
*
* @implSpec The default implementation does nothing.
*
@@ -563,8 +549,8 @@
}
/**
- * A marker used by {@link WebSocket.Listener} for partial message
- * receiving.
+ * A marker used by {@link WebSocket.Listener} in cases where a partial
+ * message may be received.
*
* @since 9
*/
@@ -586,19 +572,9 @@
LAST,
/**
- * A whole message. The message consists of a single part.
+ * A whole message consisting of a single part.
*/
- WHOLE;
-
- /**
- * Tells whether a part of a message received with this marker is the
- * last part.
- *
- * @return {@code true} if LAST or WHOLE, {@code false} otherwise
- */
- public boolean isLast() {
- return this == LAST || this == WHOLE;
- }
+ WHOLE
}
/**
@@ -630,7 +606,7 @@
* @param message
* the message
* @param isLast
- * {@code true} if this is the final part of the message,
+ * {@code true} if this is the last part of the message,
* {@code false} otherwise
*
* @return a CompletableFuture with this WebSocket
@@ -679,43 +655,6 @@
}
/**
- * 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
@@ -737,7 +676,7 @@
* @param message
* the message
* @param isLast
- * {@code true} if this is the final part of the message,
+ * {@code true} if this is the last part of the message,
* {@code false} otherwise
*
* @return a CompletableFuture with this WebSocket
@@ -745,43 +684,6 @@
CompletableFuture<WebSocket> sendBinary(ByteBuffer message, boolean isLast);
/**
- * Sends a Binary message with bytes from the given {@code byte[]}.
- *
- * <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>
- *
- * @implSpec This is equivalent to:
- * <pre>{@code
- * sendBinary(ByteBuffer.wrap(message), isLast)
- * }</pre>
- *
- * @param message
- * the message
- * @param isLast
- * {@code true} if this is the final part of the message,
- * {@code false} otherwise
- *
- * @return a CompletableFuture with this WebSocket
- */
- default CompletableFuture<WebSocket> sendBinary(byte[] message, boolean isLast) {
- Objects.requireNonNull(message, "message");
- return sendBinary(ByteBuffer.wrap(message), isLast);
- }
-
- /**
* Sends a Ping message.
*
* <p> Returns a {@code CompletableFuture<WebSocket>} which completes
@@ -858,10 +760,11 @@
* normally when the message has been sent or completes exceptionally if an
* 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> A Close message may consist of a status code and a reason for
+ * closing. The reason must have a 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:
@@ -910,24 +813,21 @@
CompletableFuture<WebSocket> sendClose();
/**
- * Requests {@code n} more messages to be received by the {@link Listener
+ * Allows {@code n} more messages to be received by the {@link Listener
* Listener}.
*
- * <p> The actual number might be fewer if either of the endpoints decide to
- * close the connection before that or an error occurs.
+ * <p> The actual number of received messages might be fewer if a Close
+ * message is received, the connection closes or an error occurs.
*
* <p> A {@code WebSocket} that has just been created, hasn't requested
* anything yet. Usually the initial request for messages is done in {@link
* Listener#onOpen(java.net.http.WebSocket) Listener.onOpen}.
*
- * If all requested messages have been received, and the server sends more,
- * then these messages are queued.
- *
* @implNote This implementation does not distinguish between partial and
* whole messages, because it's not known beforehand how a message will be
* received.
*
- * <p> If a server sends more messages than requested, the implementation
+ * <p> If a server sends more messages than requested, this implementation
* queues up these messages on the TCP connection and may eventually force
* the sender to stop sending through TCP flow control.
*
@@ -936,12 +836,8 @@
*
* @throws IllegalArgumentException
* if {@code n < 0}
- *
- * @return resulting unfulfilled demand with this request taken into account
*/
- // TODO return void as it's breaking encapsulation (leaking info when exactly something deemed delivered)
- // or demand behaves after LONG.MAX_VALUE
- long request(long n);
+ void request(long n);
/**
* Returns a {@linkplain Builder#subprotocols(String, String...) subprotocol}