jdk/src/java.net.http/share/classes/java/net/http/WebSocket.java

/*
 * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.net.http;

import java.io.IOException;
import java.net.URI;
import java.nio.ByteBuffer;
import java.time.Duration;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;

/**
 * A WebSocket Client.
 *
 * <p> {@code WebSocket} instances are created through {@link WebSocket.Builder}.
 *
 * <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
 * can be sent until the WebSocket's output is closed, and received until the
 * WebSocket's input is closed.
 *
 * <p> 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.
 *
 * <p> A receive method is any of the {@code onText}, {@code onBinary},
 * {@code onPing}, {@code onPong} and {@code onClose} methods of
 * {@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> 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,
 * {@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.
 *
 * <p> {@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 (<code>{@value}</code>),
     * 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}.
     *
     * <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
     */
    interface Builder {

        /**
         * Adds the given name-value pair to the list of additional HTTP headers
         * sent during the opening handshake.
         *
         * <p> Headers defined in the
         * <a href="https://tools.ietf.org/html/rfc6455#section-11.3">WebSocket
         * Protocol</a> 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.
         *
         * <p> 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.
         *
         * <p> After the {@code WebSocket} has been built, the actual
         * subprotocol can be queried through
         * {@link WebSocket#getSubprotocol WebSocket.getSubprotocol()}.
         *
         * <p> 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.
         *
         * <p> 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}.
         *
         * <p> Returns a {@code CompletableFuture} which will either complete
         * normally with the resulting {@code WebSocket} or complete
         * exceptionally with one of the following errors:
         * <ul>
         * <li> {@link IOException} -
         *          if an I/O error occurs
         * <li> {@link WebSocketHandshakeException} -
         *          if the opening handshake fails
         * <li> {@link HttpTimeoutException} -
         *          if the opening handshake does not complete within
         *          the timeout
         * <li> {@link InterruptedException} -
         *          if the operation is interrupted
         * <li> {@link SecurityException} -
         *          if a security manager has been installed and it denies
         *          {@link java.net.URLPermission access} to {@code uri}.
         *          <a href="HttpRequest.html#securitychecks">Security checks</a>
         *          contains more information relating to the security context
         *          in which the the listener is invoked.
         * <li> {@link IllegalArgumentException} -
         *          if any of the arguments of this builder's methods are
         *          illegal
         * </ul>
         *
         * @param uri
         *         the WebSocket URI
         * @param listener
         *         the listener
         *
         * @return a {@code CompletableFuture} with the {@code WebSocket}
         */
        CompletableFuture<WebSocket> buildAsync(URI uri, Listener listener);
    }

    /**
     * The receiving interface of {@code WebSocket}.
     *
     * <p> A {@code WebSocket} invokes methods of the associated 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
     * 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.
     *
     * @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.
     *
     * <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.
     *
     * <p> {@code CompletionStage}s returned from the receive methods have
     * nothing to do with the
     * <a href="WebSocket.html#counter">counter of invocations</a>.
     * 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}:
     * <pre>{@code     WebSocket.Listener listener = new WebSocket.Listener() {
     *
     *        List<CharSequence> 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;
     *        }
     *    ...
     *    } } </pre>
     *
     * @since 11
     */
    interface Listener {

        /**
         * A {@code WebSocket} has been connected.
         *
         * <p> 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:
         * <pre>{@code     webSocket.request(1); }</pre>
         *
         * @param webSocket
         *         the WebSocket that has been connected
         */
        default void onOpen(WebSocket webSocket) { webSocket.request(1); }

        /**
         * A textual data has been received.
         *
         * <p> 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:
         * <pre>{@code     webSocket.request(1);
         *    return null; }</pre>
         *
         * @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.
         *
         * <p> This data is located in bytes from the buffer's position to its
         * limit.
         *
         * <p> 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:
         * <pre>{@code     webSocket.request(1);
         *    return null; }</pre>
         *
         * @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.
         *
         * <p> 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.
         *
         * <p> 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.
         *
         * <p> 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:
         * <pre>{@code     webSocket.request(1);
         *    return null; }</pre>
         *
         * @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.
         *
         * <p> 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.
         *
         * <p> 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:
         * <pre>{@code     webSocket.request(1);
         *    return null; }</pre>
         *
         * @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.
         *
         * <p> This is the last invocation from the specified {@code WebSocket}.
         * By the time this invocation begins the WebSocket's input will have
         * been closed.
         *
         * <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 a UTF-8 representation not longer than {@code 123} bytes.
         *
         * <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 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.
         *
         * <p> To specify a custom closure code or reason code the
         * {@code sendClose} method may be invoked from inside the
         * {@code onClose} invocation:
         * <pre>{@code     public CompletionStage<?> onClose(WebSocket webSocket,
         *                                      int statusCode,
         *                                      String reason) {
         *        webSocket.sendClose(CUSTOM_STATUS_CODE, CUSTOM_REASON);
         *        return new CompletableFuture<Void>();
         *    } } </pre>
         *
         * @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.
         *
         * <p> 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.
         *
         * <p> 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.
     *
     * <p> The character sequence must not be modified until the
     * {@code CompletableFuture} returned from this method has completed.
     *
     * <p> A {@code CompletableFuture} returned from this method can
     * complete exceptionally with:
     * <ul>
     * <li> {@link IllegalStateException} -
     *          if there is a pending text or binary send operation
     *          or if the previous binary data does not complete the message
     * <li> {@link IOException} -
     *          if an I/O error occurs, or if the output is closed
     * </ul>
     *
     * @implNote If {@code data} is a malformed UTF-16 sequence, the operation
     * will fail with {@code IOException}.
     *
     * @param data
     *         the data
     * @param last
     *         {@code true} if this invocation completes the message,
     *         {@code false} otherwise
     *
     * @return a {@code CompletableFuture} that completes, with this WebSocket,
     * when the data has been sent
     */
    CompletableFuture<WebSocket> sendText(CharSequence data, boolean last);

    /**
     * Sends binary data with bytes from the given buffer.
     *
     * <p> 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.
     *
     * <p> The {@code CompletableFuture} returned from this method can
     * complete exceptionally with:
     * <ul>
     * <li> {@link IllegalStateException} -
     *          if there is a pending text or binary send operation
     *          or if the previous textual data does not complete the message
     * <li> {@link IOException} -
     *          if an I/O error occurs, or if the output is closed
     * </ul>
     *
     * @param data
     *         the data
     * @param last
     *         {@code true} if this invocation completes the message,
     *         {@code false} otherwise
     *
     * @return a {@code CompletableFuture} that completes, with this WebSocket,
     * when the data has been sent
     */
    CompletableFuture<WebSocket> sendBinary(ByteBuffer data, boolean last);

    /**
     * Sends a Ping message with bytes from the given buffer.
     *
     * <p> 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.
     *
     * <p> The {@code CompletableFuture} returned from this method can
     * complete exceptionally with:
     * <ul>
     * <li> {@link IllegalStateException} -
     *          if there is a pending ping or pong send operation
     * <li> {@link IllegalArgumentException} -
     *          if the message is too long
     * <li> {@link IOException} -
     *          if an I/O error occurs, or if the output is closed
     * </ul>
     *
     * @param message
     *         the message
     *
     * @return a {@code CompletableFuture} that completes, with this WebSocket,
     * when the Ping message has been sent
     */
    CompletableFuture<WebSocket> sendPing(ByteBuffer message);

    /**
     * Sends a Pong message with bytes from the given buffer.
     *
     * <p> 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.
     *
     * <p> 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.
     *
     * <p> The {@code CompletableFuture} returned from this method can
     * complete exceptionally with:
     * <ul>
     * <li> {@link IllegalStateException} -
     *          if there is a pending ping or pong send operation
     * <li> {@link IllegalArgumentException} -
     *          if the message is too long
     * <li> {@link IOException} -
     *          if an I/O error occurs, or if the output is closed
     * </ul>
     *
     * @param message
     *         the message
     *
     * @return a {@code CompletableFuture} that completes, with this WebSocket,
     * when the Pong message has been sent
     */
    CompletableFuture<WebSocket> sendPong(ByteBuffer message);

    /**
     * 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},
     * {@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.
     *
     * <p> A {@code CompletableFuture} returned from this method can
     * complete exceptionally with:
     * <ul>
     * <li> {@link IllegalArgumentException} -
     *           if {@code statusCode} is illegal, or
     *           if {@code reason} is illegal
     * <li> {@link IOException} -
     *           if an I/O error occurs, or if the output is closed
     * </ul>
     *
     * <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 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:
     * <pre>{@code     CompletableFuture<WebSocket> webSocket = ...
     *    webSocket.thenCompose(ws -> ws.sendText("Hello, ", false))
     *             .thenCompose(ws -> ws.sendText("world!", true))
     *             .thenCompose(ws -> ws.sendClose(WebSocket.NORMAL_CLOSURE, ""))
     *             .join(); }</pre>
     *
     * 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}:
     * <pre>{@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);
     * } </pre>
     *
     * @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
     */
    CompletableFuture<WebSocket> sendClose(int statusCode, String reason);

    /**
     * Increments the counter of invocations of receive methods.
     *
     * <p> This 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.
     *
     * <p> 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:
     * <pre>{@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;
     *        }
     *    ...
     *    } } </pre>
     *
     * @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.
     *
     * <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 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 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.
     */
    void abort();
}