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

equal deleted inserted replaced

-:65a4ac71b2bf
+:95f6f846ee8e
 import java.util.concurrent.CompletionStage;
 /**
 * A WebSocket client.
 *
-* <p> To create a {@code WebSocket} use the {@link HttpClient#newWebSocketBuilder}
+* <p> To create a WebSocket use the {@link HttpClient#newWebSocketBuilder}
-* method. To close a {@code WebSocket} use one of the {@code sendClose} or
+* method. To close a WebSocket use one of the {@code sendClose} or
 * {@code abort} methods.
 *
 * <p> WebSocket messages are sent through a {@code WebSocket} and received
 * through the {@code WebSocket.Listener}. Messages can be sent until
 * the output is closed, and received until the input is closed.
 * completes normally if the message is sent or completes exceptionally if an
 * error occurs.
 *
 * A <i>receive method</i> is any of the {@code onText}, {@code onBinary},
 * {@code onPing}, {@code onPong} and {@code onClose} methods of
-* {@code Listener}. A {@code WebSocket} maintains an internal counter.
+* {@code Listener}. A WebSocket maintains an internal counter.
 * This counter indicates how many invocations of the associated listener's
 * receive methods have been requested, but not yet made. While this counter is
-* zero the {@code WebSocket} does not invoke any of the receive methods. The
+* zero the WebSocket does not invoke any of the receive methods. The
 * counter is incremented by {@code n} when {@code request(n)} is called. The
-* counter is decremented by one when the {@code WebSocket} invokes a receive
+* counter is decremented by one when the WebSocket invokes a receive method.
-* method. {@code onError} is not a receive method. The {@code WebSocket} may
+* {@code onOpen} and {@code onError} are not receive methods. WebSocket invokes
-* invoke {@code onError} at any given time. If the {@code WebSocket} invokes
+* {@code onOpen} prior to any other methods on the listener. WebSocket may
+* invoke {@code onError} at any given time. If the WebSocket invokes
 * {@code onError} or {@code onClose}, then no further listener methods will be
-* invoked, no matter the value of the counter. For a newly built
+* invoked, no matter the value of the counter. For a newly built WebSocket the
-* {@code WebSocket} the value of the counter is zero.
+* value of the counter is zero.
 *
 * <p> When sending or receiving a message in parts, a whole message is
 * transferred as a sequence of one or more invocations where the last
 * invocation is identified via an additional method argument.
 *
 * <p> Unless otherwise stated, {@code null} arguments will cause methods
 * of {@code WebSocket} to throw {@code NullPointerException}, similarly,
 * {@code WebSocket} will not pass {@code null} arguments to methods of
 * {@code Listener}.
 *
-* <p> The state of a {@code WebSocket} is not changed by the invocations that
+* <p> The state of a WebSocket is not changed by the invocations that throw or
-* throw or return a {@code CompletableFuture} that completes with one of the
+* return a {@code CompletableFuture} that completes with one of the
 * {@code NullPointerException}, {@code IllegalArgumentException},
 * {@code IllegalStateException} exceptions.
 *
-* <p> A {@code WebSocket} invokes methods of its listener in a thread-safe
+* <p> A WebSocket invokes methods on the associated listener in a thread-safe
 * manner.
 *
 * <p> {@code WebSocket} handles Ping and Close messages automatically (as per
 * RFC 6455) by replying with Pong and Close messages respectively. If the
 * listener receives Ping or Close messages, no mandatory actions from the
 webSocket.request(1);
 return null;
 }
 /**
-* Receives a Close message indicating the {@code WebSocket}'s input has
+* Receives a Close message indicating the WebSocket's input has been
-* been closed.
+* closed.
 *
 * <p> This is the last invocation from the {@code WebSocket}. By the
-* time this invocation begins the {@code WebSocket}'s input will have
+* time this invocation begins the WebSocket's input will have
 * been closed. Be prepared to receive this invocation at any time after
 * {@code onOpen} regardless of whether or not any messages have been
 * requested from the {@code WebSocket}.
 *
 * <p> A Close message consists of a status code and a reason for
 * closing. The status code is an integer from the range
 * {@code 1000 <= code <= 65535}. The {@code reason} is a string which
 * has an UTF-8 representation not longer than {@code 123} bytes.
 *
-* <p> If the {@code WebSocket}'s output is not already closed, the
+* <p> If the WebSocket's output is not already closed, the
 * {@code CompletionStage} returned by this method will be used as an
-* indication that the {@code WebSocket}'s output may be closed. The
+* indication that the WebSocket's output may be closed. The WebSocket
-* {@code WebSocket} will close its output at the earliest of completion
+* will close its output at the earliest of completion of the returned
-* of the returned {@code CompletionStage} or invoking either of the
+* {@code CompletionStage} or invoking either of the {@code sendClose}
-* {@code sendClose} or {@code abort} methods.
+* or {@code abort} methods.
 *
 * @apiNote Returning a {@code CompletionStage} that never completes,
 * effectively disables the reciprocating closure of the output.
 *
 * <p> To specify a custom closure code and/or reason code the sendClose
 * may be invoked from inside onClose call:
 * <pre>{@code
 *  public CompletionStage<?> onClose(WebSocket webSocket,
-*                             int statusCode,
+*                                    int statusCode,
-*                             String reason) {
+*                                    String reason) {
 *      webSocket.sendClose(CUSTOM_STATUS_CODE, CUSTOM_REASON);
 *      return new CompletableFuture<Void>();
 *  }
 * }</pre>
 *
 }
 /**
 * An error has occurred.
 *
-* <p> This is the last invocation from the {@code WebSocket}. By the
+* <p> This is the last invocation from the specified WebSocket. By the
-* time this invocation begins both {@code WebSocket}'s input and output
+* time this invocation begins both that WebSocket's input and output
-* will have been closed. Be prepared to receive this invocation at any
+* will have been closed. A WebSocket may invoke this method on the
-* time after {@code onOpen} regardless of whether or not any messages
+* associated listener at any time after it has invoked {@code onOpen},
-* have been requested from the {@code WebSocket}.
+* regardless of whether or not any invocations have been requested from
+* the WebSocket.
 *
 * <p> If an exception is thrown from this method, resulting behavior is
 * undefined.
 *
 * @param webSocket
 *         the message
 * @param last
 *         {@code true} if this is the last part of the message,
 *         {@code false} otherwise
 *
-* @return a {@code CompletableFuture} that completes, with this
+* @return a {@code CompletableFuture} that completes, with this WebSocket,
-* {@code WebSocket}, when the message has been sent
+* when the message has been sent
 */
 CompletableFuture<WebSocket> sendText(CharSequence message, boolean last);
 /**
 * Sends a Binary message with bytes from the given {@code ByteBuffer}.
 *         the message
 * @param last
 *         {@code true} if this is the last part of the message,
 *         {@code false} otherwise
 *
-* @return a {@code CompletableFuture} that completes, with this
+* @return a {@code CompletableFuture} that completes, with this WebSocket,
-* {@code WebSocket}, when the message has been sent
+* when the message has been sent
 */
 CompletableFuture<WebSocket> sendBinary(ByteBuffer message, boolean last);
 /**
 * Sends a Ping message with bytes from the given {@code ByteBuffer}.
 * </ul>
 *
 * @param message
 *         the message
 *
-* @return a {@code CompletableFuture} that completes, with this
+* @return a {@code CompletableFuture} that completes, with this WebSocket,
-* {@code WebSocket}, when the Ping message has been sent
+* when the Ping message has been sent
 */
 CompletableFuture<WebSocket> sendPing(ByteBuffer message);
 /**
 * Sends a Pong message with bytes from the given {@code ByteBuffer}.
 * </ul>
 *
 * @param message
 *         the message
 *
-* @return a {@code CompletableFuture} that completes, with this
+* @return a {@code CompletableFuture} that completes, with this WebSocket,
-* {@code WebSocket}, when the Pong message has been sent
+* when the Pong message has been sent
 */
 CompletableFuture<WebSocket> sendPong(ByteBuffer message);
 /**
-* Initiates an orderly closure of this {@code WebSocket}'s output by
+* Initiates an orderly closure of this WebSocket's output by
 * sending a Close message with the given status code and the reason.
 *
 * <p> The {@code statusCode} is an integer from the range
 * {@code 1000 <= code <= 4999}. Status codes {@code 1002}, {@code 1003},
 * {@code 1006}, {@code 1007}, {@code 1009}, {@code 1010}, {@code 1012},
 * <p> Unless the {@code CompletableFuture} returned from this method
 * completes with {@code IllegalArgumentException}, or the method throws
 * {@code NullPointerException}, the output will be closed.
 *
 * <p> If not already closed, the input remains open until it is
-* {@linkplain Listener#onClose(WebSocket, int, String) closed} by the server,
+* {@linkplain Listener#onClose(WebSocket, int, String) closed} by the
-* or {@code abort} is invoked, or an
+* server, or {@code abort} is invoked, or an
 * {@linkplain Listener#onError(WebSocket, Throwable) error} occurs.
 *
 * @apiNote Use the provided integer constant {@link #NORMAL_CLOSURE} as a
 * status code and an empty string as a reason in a typical case
 * <pre>{@code
 * @param statusCode
 *         the status code
 * @param reason
 *         the reason
 *
-* @return a {@code CompletableFuture} that completes, with this
+* @return a {@code CompletableFuture} that completes, with this WebSocket,
-* {@code WebSocket}, when the Close message has been sent
+* when the Close message has been sent
 */
 CompletableFuture<WebSocket> sendClose(int statusCode, String reason);
 /**
-* Increments the counter of invocations requested from this
+* Increments the counter of invocations requested from this WebSocket.
-* {@code WebSocket} to the associated listener by the given number.
 *
 * <p> This WebSocket will invoke {@code onText}, {@code onBinary},
 * {@code onPing}, {@code onPong} or {@code onClose} methods on the
 * associated listener up to {@code n} more times.
 *
 * @apiNote The parameter of this method is the number of invocations being
-* requested from this {@code WebSocket} to the associated {@code Listener},
+* requested from this WebSocket to the associated listener, not the number
-* not the number of messages. Sometimes a message may be delivered in a
+* of messages. Sometimes a message may be delivered to the listener in a
 * single invocation, but not always. For example, Ping, Pong and Close
 * messages are delivered in a single invocation of {@code onPing},
 * {@code onPong} and {@code onClose} respectively. However, whether or not
 * Text and Binary messages are delivered in a single invocation of
 * {@code onText} and {@code onBinary} depends on the boolean argument
 *         if {@code n <= 0}
 */
 void request(long n);
 /**
-* Returns the subprotocol for this {@code WebSocket}.
+* Returns the subprotocol used by this WebSocket.
 *
-* @return the subprotocol for this {@code WebSocket}, or an empty
+* @return the subprotocol, or an empty string if there's no subprotocol
-* {@code String} if there's no subprotocol
 */
 String getSubprotocol();
 /**
-* Tells whether this {@code WebSocket}'s output is closed.
+* Tells whether this WebSocket's output is closed.
 *
 * <p> If this method returns {@code true}, subsequent invocations will also
 * return {@code true}.
 *
 * @return {@code true} if closed, {@code false} otherwise
 */
 boolean isOutputClosed();
 /**
-* Tells whether this {@code WebSocket}'s input is closed.
+* Tells whether this WebSocket's input is closed.
 *
 * <p> If this method returns {@code true}, subsequent invocations will also
 * return {@code true}.
 *
 * @return {@code true} if closed, {@code false} otherwise
 */
 boolean isInputClosed();
 /**
-* Closes this {@code WebSocket}'s input and output abruptly.
+* Closes this WebSocket's input and output abruptly.
 *
 * <p> When this method returns both the input and the output will have been
 * closed. Any pending send operations will fail with {@code IOException}.
-* Subsequent invocations of {@code abort()} will have no effect.
+* Subsequent invocations of {@code abort} will have no effect.
 */
 void abort();
 }

branch	http-client-branch
changeset 56331	95f6f846ee8e
parent 56329	254f6c8277f9
child 56332	bf6a22cc06ba