--- a/src/java.net.http/share/classes/java/net/http/WebSocket.java Wed Jun 20 17:15:16 2018 +0200
+++ b/src/java.net.http/share/classes/java/net/http/WebSocket.java Wed Jun 20 09:05:57 2018 -0700
@@ -35,9 +35,9 @@
/**
* A WebSocket Client.
*
- * <p> {@code WebSocket} instances can be created via {@link WebSocket.Builder}.
+ * <p> {@code WebSocket} instances are created through {@link WebSocket.Builder}.
*
- * <p> WebSocket has an input and an output sides. These sides are independent
+ * <p> WebSocket has an input and an output side. These sides are independent
* from each other. A side can either be open or closed. Once closed, the side
* remains closed. WebSocket messages are sent through a {@code WebSocket} and
* received through a {@code WebSocket.Listener} associated with it. Messages
@@ -55,21 +55,22 @@
*
* <p> A receive method is any of the {@code onText}, {@code onBinary},
* {@code onPing}, {@code onPong} and {@code onClose} methods of
- * {@code Listener}. A receive method initiates a receive operation and returns
- * a {@code CompletionStage} which completes once the operation has completed.
+ * {@code Listener}. WebSocket initiates a receive operation by invoking a
+ * receive method on the listener. The listener then must return a
+ * {@code CompletionStage} which completes once the operation has completed.
*
- * <p> A WebSocket maintains an <a id="counter">internal counter</a>.
- * This counter's value is a number of times the WebSocket has yet to invoke a
- * receive method. While this counter is zero the WebSocket does not invoke
- * receive methods. The counter is incremented by {@code n} when {@code
- * request(n)} is called. The counter is decremented by one when the WebSocket
- * invokes a receive method. {@code onOpen} and {@code onError} are not receive
- * methods. WebSocket invokes {@code onOpen} prior to any other methods on the
- * listener. WebSocket invokes {@code onOpen} at most once. WebSocket may invoke
- * {@code onError} at any given time. If the WebSocket invokes {@code onError}
- * or {@code onClose}, then no further listener's methods will be invoked, no
- * matter the value of the counter. For a newly built WebSocket the counter is
- * zero. A WebSocket invokes methods on the listener in a thread-safe manner.
+ * <p> To control receiving of messages, a WebSocket maintains an
+ * <a id="counter">internal counter</a>. This counter's value is a number of
+ * times the WebSocket has yet to invoke a receive method. While this counter is
+ * zero the WebSocket does not invoke receive methods. The counter is
+ * incremented by {@code n} when {@code request(n)} is called. The counter is
+ * decremented by one when the WebSocket invokes a receive method.
+ * {@code onOpen} and {@code onError} are not receive methods. WebSocket invokes
+ * {@code onOpen} prior to any other methods on the listener. WebSocket invokes
+ * {@code onOpen} at most once. WebSocket may invoke {@code onError} at any
+ * given time. If the WebSocket invokes {@code onError} or {@code onClose}, then
+ * no further listener's methods will be invoked, no matter the value of the
+ * counter. For a newly built WebSocket the counter is zero.
*
* <p> Unless otherwise stated, {@code null} arguments will cause methods
* of {@code WebSocket} to throw {@code NullPointerException}, similarly,
@@ -105,13 +106,13 @@
/**
* A builder of {@linkplain WebSocket WebSocket Clients}.
*
- * <p> A builder can be created by invoking the
- * {@link HttpClient#newWebSocketBuilder HttpClient.newWebSocketBuilder}
- * method. The intermediate (setter-like) methods change the state of the
- * builder and return the same builder they have been invoked on. If an
- * intermediate method is not invoked, an appropriate default value (or
- * behavior) will be assumed. A {@code Builder} is not safe for use by
- * multiple threads without external synchronization.
+ * <p> Builders are created by invoking
+ * {@link HttpClient#newWebSocketBuilder HttpClient.newWebSocketBuilder}.
+ * The intermediate (setter-like) methods change the state of the builder
+ * and return the same builder they have been invoked on. If an intermediate
+ * method is not invoked, an appropriate default value (or behavior) will be
+ * assumed. A {@code Builder} is not safe for use by multiple threads
+ * without external synchronization.
*
* @since 11
*/
@@ -155,7 +156,7 @@
* Sets a request for the given subprotocols.
*
* <p> After the {@code WebSocket} has been built, the actual
- * subprotocol can be queried via
+ * subprotocol can be queried through
* {@link WebSocket#getSubprotocol WebSocket.getSubprotocol()}.
*
* <p> Subprotocols are specified in the order of preference. The most
@@ -218,11 +219,17 @@
* The receiving interface of {@code WebSocket}.
*
* <p> A {@code WebSocket} invokes methods of the associated listener
- * passing itself as an argument. When data has been received, the
- * {@code WebSocket} invokes a receive method. Methods {@code onText},
- * {@code onBinary}, {@code onPing} and {@code onPong} must return a
- * {@code CompletionStage} that completes once the message has been received
- * by the listener.
+ * passing itself as an argument. These methods are invoked in a thread-safe
+ * manner, such that the next invocation may start only after the previous
+ * one has finished.
+ *
+ * <p> When data has been received, the {@code WebSocket} invokes a receive
+ * method. Methods {@code onText}, {@code onBinary}, {@code onPing} and
+ * {@code onPong} must return a {@code CompletionStage} that completes once
+ * the message has been received by the listener. If a listener's method
+ * returns {@code null} rather than a {@code CompletionStage},
+ * {@code WebSocket} will behave as if the listener returned a
+ * {@code CompletionStage} that is already completed normally.
*
* <p> An {@code IOException} raised in {@code WebSocket} will result in an
* invocation of {@code onError} with that exception (if the input is not
@@ -231,11 +238,14 @@
* exceptionally, the WebSocket will invoke {@code onError} with this
* exception.
*
- * <p> If a listener's method returns {@code null} rather than a
- * {@code CompletionStage}, {@code WebSocket} will behave as if the listener
- * returned a {@code CompletionStage} that is already completed normally.
+ * @apiNote The strict sequential order of invocations from
+ * {@code WebSocket} to {@code Listener} means, in particular, that the
+ * {@code Listener}'s methods are treated as non-reentrant. This means that
+ * {@code Listener} implementations do not need to be concerned with
+ * possible recursion or the order in which they invoke
+ * {@code WebSocket.request} in relation to their processing logic.
*
- * @apiNote Careful attention may be required if a listener is associated
+ * <p> Careful attention may be required if a listener is associated
* with more than a single {@code WebSocket}. In this case invocations
* related to different instances of {@code WebSocket} may not be ordered
* and may even happen concurrently.