/*

 * 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> To create a {@code WebSocket} use the {@link HttpClient#newWebSocketBuilder}

 * method. To close a {@code 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}'s {@code Listener}. Messages can be sent until

 * the output is closed, and received until the input is closed.

 * A {@code WebSocket} whose output and input are both closed may be considered

 * itself closed. To check these states use {@link #isOutputClosed()} and

 * {@link #isInputClosed()}.

 *

 * <p> Methods that send messages return {@code CompletableFuture} which

 * completes normally if the message is sent or completes exceptionally if an

 * error occurs.

 *

 * <p> To receive a message, first request it. If {@code n} messages are

 * requested, the listener will receive up to {@code n} more invocations of the

 * designated methods from the {@code WebSocket}. To request messages use

 * {@link #request(long)}. Request is an additive operation, that is

 * {@code request(n)} followed by {@code request(m)} is equivalent to

 * {@code request(n + m)}.

 *

 * <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

 * throw or 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

 * 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

 * listener are required.

 *

 * @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 for creating {@code WebSocket} instances.

     *

     * <p> To obtain a {@code WebSocket} configure a builder as required by

     * calling intermediate methods (the ones that return the builder itself),

     * then call {@code buildAsync()}. If an intermediate method is not called,

     * an appropriate default value (or behavior) will be assumed.

     *

     * <p> Unless otherwise stated, {@code null} arguments will cause methods of

     * {@code Builder} to throw {@code NullPointerException}.

     *

     * @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

         * <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 via

         * {@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 on the associated listener when

     * it receives messages or encounters events. A {@code WebSocket} invokes

     * methods on the listener in a thread-safe manner.

     *

     * <p> Messages received by the {@code Listener} conform to the WebSocket

     * Protocol, otherwise {@code onError} with a {@link IOException} is invoked.

     * Any {@code IOException} raised by {@code WebSocket} will result in an

     * invocation of {@code onError} with that exception. Unless otherwise

     * stated if a listener's method throws an exception or a

     * {@code CompletionStage} returned from a method completes exceptionally,

     * the {@code 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 Methods of {@code Listener} have a {@code WebSocket} parameter

     * which holds an invoking {@code WebSocket} at runtime. A careful attention

     * is 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.

     *

     * @since 11

     */

    interface Listener {

        /**

         * A {@code WebSocket} has been connected.

         *

         * <p> This is the first invocation and it is made at most once. This

         * method is typically used to make an initial request for messages.

         *

         * @implSpec The default implementation of this method behaves as if:

         *

         * <pre>{@code

         *     webSocket.request(1);

         * }</pre>

         *

         * @param webSocket

         *         the WebSocket that has been connected

         */

        default void onOpen(WebSocket webSocket) { webSocket.request(1); }

        /**

         * A Text message has been received.

         *

         * <p> Return a {@code CompletionStage} which will be used by the

         * {@code CharSequence}. Do not access the {@code CharSequence} after

         * this {@ode CompletionStage} has completed.

         *

         * @implSpec The default implementation of this method behaves as if:

         *

         * <pre>{@code

         *     webSocket.request(1);

         *     return null;

         * }</pre>

         *

         * @implNote This method is always invoked with character sequences

         * which are complete UTF-16 sequences.

         *

         * @param webSocket

         *         the WebSocket on which the message has been received

         * @param message

         *         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 message,

            webSocket.request(1);

            return null;

        }

        /**

         * A Binary message has been received.

         *

         * <p> This message consists of bytes from the buffer's position to

         * its limit.

         *

         * <p> Return a {@code CompletionStage} which will be used by the

         * {@code ByteBuffer}. Do not access the {@code ByteBuffer} after

         * this {@ode CompletionStage} has completed.

         *

         * @implSpec The default implementation of this method behaves as if:

         *

         * <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<?> onBinary(WebSocket webSocket,

                                            ByteBuffer message,

            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> 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 {@ode CompletionStage} has completed.

         *

         * @implSpec The default implementation of this method behaves as if:

         *

         * <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 {@ode CompletionStage} has completed.

         *

         * @implSpec The default implementation of this method behaves as if:

         *

         * <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 {@code WebSocket}'s input has

         * been closed.

         *

         * <p> This is the last invocation from the {@code WebSocket}. By the

         * time this invocation begins the {@code 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

         * {@code CompletionStage} returned by this method will be used as an

         * indication that the {@code WebSocket}'s output may be closed. The

         * {@code 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 and/or reason code the sendClose

         * may be invoked from inside onClose call:

         * <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 {@code WebSocket}. By the

         * time this invocation begins both {@code WebSocket}'s input and output

         * 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> 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 a Text message with characters from the given {@code CharSequence}.

     *

     * <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 the previous Text or Binary message has not been sent yet

     *          or if a previous Binary message has been sent with

     * <li> {@link IOException} -

     *          if an I/O error occurs, or if the output is closed

     * </ul>

     *

     * @implNote If a partial or malformed UTF-16 sequence is passed to this

     * method, a {@code CompletableFuture} returned will complete exceptionally

     * with {@code IOException}.

     *

     * @param message

     *         the message

     *         {@code true} if this is the last part of the message,

     *         {@code false} otherwise

     *

     * @return a {@code CompletableFuture} that completes, with this

     * {@code WebSocket}, when the message has been sent

     */