/*

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

 *

 * @implSpec Methods of {@code WebSocket} are failure-atomic in respect to

 * {@code NullPointerException}, {@code IllegalArgumentException} and

 * {@code IllegalStateException}. That is, if a method throws said exception, or

 * a returned {@code CompletableFuture} completes exceptionally with said

 * exception, the {@code WebSocket} will behave as if the method has not been

 * invoked at all.

 *

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

         *

         * <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 its listener when it receives

     * messages or encounters events. The invoking {@code WebSocket} is passed

     * as an argument to {@code Listener}'s methods. A {@code WebSocket} invokes

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

     *

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

     *

     * @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> If a whole message has been received, this method will be invoked

         * with {@code MessagePart.WHOLE} marker. Otherwise, it will be invoked

         * with {@code FIRST}, possibly a number of times with {@code PART} and,

         * finally, with {@code LAST} markers. If this message is partial, it

         * may be an incomplete UTF-16 sequence. However, the concatenation of

         * all messages through the last will be a complete UTF-16 sequence.

         *

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

         * {@code WebSocket} as a signal it may reclaim 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

         * @param part

         *         the part

         *

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

                                          MessagePart part) {

            webSocket.request(1);

            return null;

        }

        /**

         * A Binary message has been received.

         *

         * <p> If a whole message has been received, this method will be invoked

         * with {@code MessagePart.WHOLE} marker. Otherwise, it will be invoked

         * with {@code FIRST}, possibly a number of times with {@code PART} and,

         * finally, with {@code LAST} markers.

         *

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

         * @param part

         *         the part

         *

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

                                            MessagePart part) {

            webSocket.request(1);

            return null;

        }

        /**

         * A Ping message has been 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 {@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> 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;

        }

        /**

         * A Close message has been received.

         *

         * <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> Return a {@code CompletionStage} that will be used by the

         * {@code WebSocket} as a signal that it may close the output. The

         * {@code WebSocket} will close the output at the earliest of completion

         * of the returned {@code CompletionStage} or invoking a

         * {@link WebSocket#sendClose(int, String) sendClose} method.

         *

         * <p> If an exception is thrown from this method or a

         * {@code CompletionStage} returned from it completes exceptionally,

         * the resulting behaviour is undefined.

         *

         * @apiNote Returning a {@code CompletionStage} that never completes,

         * effectively disables the automatic closure of the output.

         *

         * @implSpec The default implementation of this method returns

         * {@code null}, signaling that the output may be closed.

         *

         * @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 unrecoverable 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) { }

    }

    /**

     * A marker used by {@link WebSocket.Listener} for identifying partial

     * messages.

     *

     * @since 11

     */

    enum MessagePart {

        /**

         * The first part of a message.

         */

        FIRST,

        /**

         * A middle part of a message.

         */

        PART,

        /**

         * The last part of a message.

         */

        LAST,

        /**

         * A whole message consisting of a single part.

         */

        WHOLE

    }

    /**

     * Sends a Text message with characters from the given {@code CharSequence}.

     *

     * <p> To send a Text message invoke this method only after the previous

     * Text or Binary message has been sent. The character sequence must not be

     * modified until the {@code CompletableFuture} returned from this method