{@code WebSocket} instances can be created via {@link WebSocket.Builder}. + * + *
WebSocket has an input and an output sides. 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 + * can be sent until the WebSocket's output is closed, and received until the + * WebSocket's input is closed. + * + *
A send method is any of the {@code sendText}, {@code sendBinary}, + * {@code sendPing}, {@code sendPong} and {@code sendClose} methods of + * {@code WebSocket}. A send method initiates a send operation and returns a + * {@code CompletableFuture} which completes once the operation has completed. + * If the {@code CompletableFuture} completes normally the operation is + * considered succeeded. If the {@code CompletableFuture} completes + * exceptionally, the operation is considered failed. An operation that has been + * initiated but not yet completed is considered pending. + * + *
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. + * + *
A WebSocket maintains an internal counter. + * 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. + * + *
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}. The state of a WebSocket is not changed by the invocations + * that throw or return a {@code CompletableFuture} that completes with one of + * the {@code NullPointerException}, {@code IllegalArgumentException}, + * {@code IllegalStateException} exceptions. + * + *
{@code WebSocket} handles received Ping and Close messages automatically
+ * (as per the WebSocket Protocol) by replying with Pong and Close messages. If
+ * the listener receives Ping or Close messages, no mandatory actions from the
+ * listener are required.
+ *
+ * @apiNote The relationship between a WebSocket and the associated Listener is
+ * analogous to that of a Subscription and the associated Subscriber of type
+ * {@link java.util.concurrent.Flow}.
+ *
+ * @since 11
+ */
+public interface WebSocket {
+
+ /**
+ * The WebSocket Close message status code ({@value}),
+ * indicating normal closure, meaning that the purpose for which the
+ * connection was established has been fulfilled.
+ *
+ * @see #sendClose(int, String)
+ * @see Listener#onClose(WebSocket, int, String)
+ */
+ int NORMAL_CLOSURE = 1000;
+
+ /**
+ * A builder of {@linkplain WebSocket WebSocket Clients}.
+ *
+ *
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. + * + * @since 11 + */ + interface Builder { + + /** + * Adds the given name-value pair to the list of additional HTTP headers + * sent during the opening handshake. + * + *
Headers defined in the + * WebSocket + * Protocol are illegal. If this method is not invoked, no + * additional HTTP headers will be sent. + * + * @param name + * the header name + * @param value + * the header value + * + * @return this builder + */ + Builder header(String name, String value); + + /** + * Sets a timeout for establishing a WebSocket connection. + * + *
If the connection is not established within the specified + * duration then building of the {@code WebSocket} will fail with + * {@link HttpTimeoutException}. If this method is not invoked then the + * infinite timeout is assumed. + * + * @param timeout + * the timeout, non-{@linkplain Duration#isNegative() negative}, + * non-{@linkplain Duration#ZERO ZERO} + * + * @return this builder + */ + Builder connectTimeout(Duration timeout); + + /** + * Sets a request for the given subprotocols. + * + *
After the {@code WebSocket} has been built, the actual + * subprotocol can be queried via + * {@link WebSocket#getSubprotocol WebSocket.getSubprotocol()}. + * + *
Subprotocols are specified in the order of preference. The most + * preferred subprotocol is specified first. If there are any additional + * subprotocols they are enumerated from the most preferred to the least + * preferred. + * + *
Subprotocols not conforming to the syntax of subprotocol + * identifiers are illegal. If this method is not invoked then no + * subprotocols will be requested. + * + * @param mostPreferred + * the most preferred subprotocol + * @param lesserPreferred + * the lesser preferred subprotocols + * + * @return this builder + */ + Builder subprotocols(String mostPreferred, String... lesserPreferred); + + /** + * Builds a {@link WebSocket} connected to the given {@code URI} and + * associated with the given {@code Listener}. + * + *
Returns a {@code CompletableFuture} which will either complete + * normally with the resulting {@code WebSocket} or complete + * exceptionally with one of the following errors: + *
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. + * + *
An {@code IOException} raised in {@code WebSocket} will result in an + * invocation of {@code onError} with that exception (if the input is not + * closed). Unless otherwise stated if the listener's method throws an + * exception or a {@code CompletionStage} returned from a method completes + * exceptionally, the WebSocket will invoke {@code onError} with this + * exception. + * + *
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 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. + * + *
{@code CompletionStage}s returned from the receive methods have + * nothing to do with the + * counter of invocations. + * Namely, a {@code CompletionStage} does not have to be completed in order + * to receive more invocations of the listener's methods. + * Here is an example of a listener that requests invocations, one at a + * time, until a complete message has been accumulated, then processes + * the result, and completes the {@code CompletionStage}: + *
{@code WebSocket.Listener listener = new WebSocket.Listener() {
+ *
+ * List parts = new ArrayList<>();
+ * CompletableFuture accumulatedMessage = new CompletableFuture<>();
+ *
+ * public CompletionStage onText(WebSocket webSocket,
+ * CharSequence message,
+ * boolean last) {
+ * parts.add(message);
+ * webSocket.request(1);
+ * if (last) {
+ * processWholeText(parts);
+ * parts = new ArrayList<>();
+ * accumulatedMessage.complete(null);
+ * CompletionStage cf = accumulatedMessage;
+ * accumulatedMessage = new CompletableFuture<>();
+ * return cf;
+ * }
+ * return accumulatedMessage;
+ * }
+ * ...
+ * } }
+ *
+ * @since 11
+ */
+ interface Listener {
+
+ /**
+ * A {@code WebSocket} has been connected.
+ *
+ * This is the initial invocation and it is made once. It is + * typically used to make a request for more invocations. + * + * @implSpec The default implementation is equivalent to: + *
{@code webSocket.request(1); }
+ *
+ * @param webSocket
+ * the WebSocket that has been connected
+ */
+ default void onOpen(WebSocket webSocket) { webSocket.request(1); }
+
+ /**
+ * A textual data has been received.
+ *
+ * Return a {@code CompletionStage} which will be used by the + * {@code WebSocket} as an indication it may reclaim the + * {@code CharSequence}. Do not access the {@code CharSequence} after + * this {@code CompletionStage} has completed. + * + * @implSpec The default implementation is equivalent to: + *
{@code webSocket.request(1);
+ * return null; }
+ *
+ * @implNote The {@code data} is always a legal UTF-16 sequence.
+ *
+ * @param webSocket
+ * the WebSocket on which the data has been received
+ * @param data
+ * the data
+ * @param last
+ * whether this invocation completes the message
+ *
+ * @return a {@code CompletionStage} which completes when the
+ * {@code CharSequence} may be reclaimed; or {@code null} if it may be
+ * reclaimed immediately
+ */
+ default CompletionStage onText(WebSocket webSocket,
+ CharSequence data,
+ boolean last) {
+ webSocket.request(1);
+ return null;
+ }
+
+ /**
+ * A binary data has been received.
+ *
+ * This data is located in bytes from the buffer's position to its + * limit. + * + *
Return a {@code CompletionStage} which will be used by the + * {@code WebSocket} as an indication it may reclaim the + * {@code ByteBuffer}. Do not access the {@code ByteBuffer} after + * this {@code CompletionStage} has completed. + * + * @implSpec The default implementation is equivalent to: + *
{@code webSocket.request(1);
+ * return null; }
+ *
+ * @param webSocket
+ * the WebSocket on which the data has been received
+ * @param data
+ * the data
+ * @param last
+ * whether this invocation completes the message
+ *
+ * @return a {@code CompletionStage} which completes when the
+ * {@code ByteBuffer} may be reclaimed; or {@code null} if it may be
+ * reclaimed immediately
+ */
+ default CompletionStage onBinary(WebSocket webSocket,
+ ByteBuffer data,
+ boolean last) {
+ webSocket.request(1);
+ return null;
+ }
+
+ /**
+ * A Ping message has been received.
+ *
+ * As guaranteed by the WebSocket Protocol, the message consists of + * not more than {@code 125} bytes. These bytes are located from the + * buffer's position to its limit. + * + *
Given that the WebSocket implementation will automatically send a + * reciprocal pong when a ping is received, it is rarely required to + * send a pong message explicitly when a ping is received. + * + *
Return a {@code CompletionStage} which will be used by the + * {@code WebSocket} as a signal it may reclaim the + * {@code ByteBuffer}. Do not access the {@code ByteBuffer} after + * this {@code CompletionStage} has completed. + * + * @implSpec The default implementation is equivalent to: + *
{@code webSocket.request(1);
+ * return null; }
+ *
+ * @param webSocket
+ * the WebSocket on which the message has been received
+ * @param message
+ * the message
+ *
+ * @return a {@code CompletionStage} which completes when the
+ * {@code ByteBuffer} may be reclaimed; or {@code null} if it may be
+ * reclaimed immediately
+ */
+ default CompletionStage onPing(WebSocket webSocket,
+ ByteBuffer message) {
+ webSocket.request(1);
+ return null;
+ }
+
+ /**
+ * A Pong message has been received.
+ *
+ * As guaranteed by the WebSocket Protocol, the message consists of + * not more than {@code 125} bytes. These bytes are located from the + * buffer's position to its limit. + * + *
Return a {@code CompletionStage} which will be used by the + * {@code WebSocket} as a signal it may reclaim the + * {@code ByteBuffer}. Do not access the {@code ByteBuffer} after + * this {@code CompletionStage} has completed. + * + * @implSpec The default implementation is equivalent to: + *
{@code webSocket.request(1);
+ * return null; }
+ *
+ * @param webSocket
+ * the WebSocket on which the message has been received
+ * @param message
+ * the message
+ *
+ * @return a {@code CompletionStage} which completes when the
+ * {@code ByteBuffer} may be reclaimed; or {@code null} if it may be
+ * reclaimed immediately
+ */
+ default CompletionStage onPong(WebSocket webSocket,
+ ByteBuffer message) {
+ webSocket.request(1);
+ return null;
+ }
+
+ /**
+ * Receives a Close message indicating the WebSocket's input has been
+ * closed.
+ *
+ * This is the last invocation from the specified {@code WebSocket}. + * By the time this invocation begins the WebSocket's input will have + * been closed. + * + *
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 a UTF-8 representation not longer than {@code 123} bytes. + * + *
If the WebSocket's output is not already closed, the + * {@code CompletionStage} returned by this method will be used as an + * indication that the WebSocket's output may be closed. The WebSocket + * will close its output at the earliest of completion of the returned + * {@code CompletionStage} or invoking either of the {@code sendClose} + * or {@code abort} methods. + * + * @apiNote Returning a {@code CompletionStage} that never completes, + * effectively disables the reciprocating closure of the output. + * + *
To specify a custom closure code or reason code the + * {@code sendClose} method may be invoked from inside the + * {@code onClose} invocation: + *
{@code public CompletionStage onClose(WebSocket webSocket,
+ * int statusCode,
+ * String reason) {
+ * webSocket.sendClose(CUSTOM_STATUS_CODE, CUSTOM_REASON);
+ * return new CompletableFuture();
+ * } }
+ *
+ * @implSpec The default implementation of this method returns
+ * {@code null}, indicating that the output should be closed
+ * immediately.
+ *
+ * @param webSocket
+ * the WebSocket on which the message has been received
+ * @param statusCode
+ * the status code
+ * @param reason
+ * the reason
+ *
+ * @return a {@code CompletionStage} which completes when the
+ * {@code WebSocket} may be closed; or {@code null} if it may be
+ * closed immediately
+ */
+ default CompletionStage onClose(WebSocket webSocket,
+ int statusCode,
+ String reason) {
+ return null;
+ }
+
+ /**
+ * An error has occurred.
+ *
+ * This is the last invocation from the specified WebSocket. By the + * time this invocation begins both the WebSocket's input and output + * will have been closed. A WebSocket may invoke this method on the + * associated listener at any time after it has invoked {@code onOpen}, + * regardless of whether or not any invocations have been requested from + * the WebSocket. + * + *
If an exception is thrown from this method, resulting behavior is + * undefined. + * + * @param webSocket + * the WebSocket on which the error has occurred + * @param error + * the error + */ + default void onError(WebSocket webSocket, Throwable error) { } + } + + /** + * Sends textual data with characters from the given character sequence. + * + *
The character sequence must not be modified until the + * {@code CompletableFuture} returned from this method has completed. + * + *
A {@code CompletableFuture} returned from this method can + * complete exceptionally with: + *
The data is located in bytes from the buffer's position to its limit. + * Upon normal completion of a {@code CompletableFuture} returned from this + * method the buffer will have no remaining bytes. The buffer must not be + * accessed until after that. + * + *
The {@code CompletableFuture} returned from this method can + * complete exceptionally with: + *
The message consists of not more than {@code 125} bytes from the + * buffer's position to its limit. Upon normal completion of a + * {@code CompletableFuture} returned from this method the buffer will + * have no remaining bytes. The buffer must not be accessed until after that. + * + *
The {@code CompletableFuture} returned from this method can + * complete exceptionally with: + *
The message consists of not more than {@code 125} bytes from the + * buffer's position to its limit. Upon normal completion of a + * {@code CompletableFuture} returned from this method the buffer will have + * no remaining bytes. The buffer must not be accessed until after that. + * + *
Given that the WebSocket implementation will automatically send a + * reciprocal pong when a ping is received, it is rarely required to send a + * pong message explicitly. + * + *
The {@code CompletableFuture} returned from this method can + * complete exceptionally with: + *
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}, + * {@code 1013} and {@code 1015} are illegal. Behaviour in respect to other + * status codes is implementation-specific. A legal {@code reason} is a + * string that has a UTF-8 representation not longer than {@code 123} bytes. + * + *
A {@code CompletableFuture} returned from this method can + * complete exceptionally with: + *
Unless the {@code CompletableFuture} returned from this method + * completes with {@code IllegalArgumentException}, or the method throws + * {@code NullPointerException}, the output will be closed. + * + *
If not already closed, the input remains open until a Close message + * {@linkplain Listener#onClose(WebSocket, int, String) received}, 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: + *
{@code CompletableFuture webSocket = ...
+ * webSocket.thenCompose(ws -> ws.sendText("Hello, ", false))
+ * .thenCompose(ws -> ws.sendText("world!", true))
+ * .thenCompose(ws -> ws.sendClose(WebSocket.NORMAL_CLOSURE, ""))
+ * .join(); }
+ *
+ * The {@code sendClose} method does not close this WebSocket's input. It
+ * merely closes this WebSocket's output by sending a Close message. To
+ * enforce closing the input, invoke the {@code abort} method. Here is an
+ * example of an application that sends a Close message, and then starts a
+ * timer. Once no data has been received within the specified timeout, the
+ * timer goes off and the alarm aborts {@code WebSocket}:
+ * {@code MyAlarm alarm = new MyAlarm(webSocket::abort);
+ * WebSocket.Listener listener = new WebSocket.Listener() {
+ *
+ * public CompletionStage onText(WebSocket webSocket,
+ * CharSequence data,
+ * boolean last) {
+ * alarm.snooze();
+ * ...
+ * }
+ * ...
+ * };
+ * ...
+ * Runnable startTimer = () -> {
+ * MyTimer idleTimer = new MyTimer();
+ * idleTimer.add(alarm, 30, TimeUnit.SECONDS);
+ * };
+ * webSocket.sendClose(WebSocket.NORMAL_CLOSURE, "ok").thenRun(startTimer);
+ * }
+ *
+ * @param statusCode
+ * the status code
+ * @param reason
+ * the reason
+ *
+ * @return a {@code CompletableFuture} that completes, with this WebSocket,
+ * when the Close message has been sent
+ */
+ CompletableFutureThis WebSocket will invoke {@code onText}, {@code onBinary}, + * {@code onPing}, {@code onPong} or {@code onClose} methods on the + * associated listener (i.e. receive methods) up to {@code n} more times. + * + * @apiNote The parameter of this method is the number of invocations being + * requested from this WebSocket to the associated listener, not the number + * 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} methods respectively. However, whether + * or not Text and Binary messages are delivered in a single invocation of + * {@code onText} and {@code onBinary} methods depends on the boolean + * argument ({@code last}) of these methods. If {@code last} is + * {@code false}, then there is more to a message than has been delivered to + * the invocation. + * + *
Here is an example of a listener that requests invocations, one at a + * time, until a complete message has been accumulated, and then processes + * the result: + *
{@code WebSocket.Listener listener = new WebSocket.Listener() {
+ *
+ * StringBuilder text = new StringBuilder();
+ *
+ * public CompletionStage onText(WebSocket webSocket,
+ * CharSequence message,
+ * boolean last) {
+ * text.append(message);
+ * if (last) {
+ * processCompleteTextMessage(text);
+ * text = new StringBuilder();
+ * }
+ * webSocket.request(1);
+ * return null;
+ * }
+ * ...
+ * } }
+ *
+ * @param n
+ * the number of invocations
+ *
+ * @throws IllegalArgumentException
+ * if {@code n <= 0}
+ */
+ void request(long n);
+
+ /**
+ * Returns the subprotocol used by this WebSocket.
+ *
+ * @return the subprotocol, or an empty string if there's no subprotocol
+ */
+ String getSubprotocol();
+
+ /**
+ * Tells whether this WebSocket's output is closed.
+ *
+ * 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 WebSocket's input is closed. + * + *
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 WebSocket's input and output abruptly. + * + *
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. + */ + void abort(); +}