/*

 * Copyright (c) 2015, 2017, 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 jdk.incubator.http;

import java.io.FileNotFoundException;

import java.io.InputStream;

import java.net.URI;

import java.net.URLPermission;

import java.nio.ByteBuffer;

import java.nio.charset.Charset;

import java.nio.charset.StandardCharsets;

import java.nio.file.Files;

import java.nio.file.Path;

import java.security.AccessController;

import java.security.PrivilegedAction;

import java.time.Duration;

import java.util.Iterator;

import java.util.Objects;

import java.util.Optional;

import java.util.concurrent.CompletableFuture;

import java.util.concurrent.Executor;

import java.util.concurrent.Flow;

import java.util.function.Supplier;

import jdk.incubator.http.HttpResponse.BodyHandler;

import jdk.incubator.http.internal.HttpRequestBuilderImpl;

import jdk.incubator.http.internal.RequestPublishers;

import static java.nio.charset.StandardCharsets.UTF_8;

/**

 * An HTTP request.

 * {@Incubating }

 *

 * <p> An {@code HttpRequest} instance is built through a {@code HttpRequest}

 * {@linkplain HttpRequest.Builder builder}. An {@code HttpRequest} builder

 * is obtained from one of the {@link HttpRequest#newBuilder(URI) newBuilder}

 * methods. A request's {@linkplain URI}, headers, and body can be set. Request

 * bodies are provided through a {@link BodyPublisher} object supplied to the

 * {@link Builder#DELETE(BodyPublisher) DELETE},

 * {@link Builder#POST(BodyPublisher) POST} or

 * {@link Builder#PUT(BodyPublisher) PUT} methods.

 * Once all required parameters have been set in the builder, {@link

 * Builder#build() build} will return the {@code HttpRequest}. Builders can be

 * copied and modified many times in order to build multiple related requests

 * that differ in some parameters.

 *

 * <p> <b>Example HTTP interactions:</b>

 * <pre>{@code    // GET

 *    HttpResponse<String> response = client.send(

 *          HttpRequest.newBuilder(new URI("http://www.foo.com/"))

 *                     .headers("Foo", "foovalue", "Bar", "barvalue")

 *                     .GET()

 *                     .build(),

 *          BodyHandler.asString()

 *    );

 *    int statusCode = response.statusCode();

 *    String body = response.body();

 *

 *    // POST

 *    HttpResponse<Path> response = client.send(

 *          HttpRequest.newBuilder(new URI("http://www.foo.com/"))

 *                     .headers("Foo", "foovalue", "Bar", "barvalue")

 *                     .POST(BodyPublisher.fromString("Hello world"))

 *                     .build(),

 *          BodyHandler.asFile(Paths.get("/path"))

 *    );

 *    int statusCode = response.statusCode();

 *    Path body = response.body(); // should be "/path" }</pre>

 *

 * <p> The request is sent and the response obtained by invoking one of the

 * following methods in {@link HttpClient}.

 * <ul><li>{@link HttpClient#send(HttpRequest, BodyHandler)} blocks

 * until the entire request has been sent and the response has been received.</li>

 * <li>{@link HttpClient#sendAsync(HttpRequest, BodyHandler)} sends the

 * request and receives the response asynchronously. Returns immediately with a

 * {@linkplain CompletableFuture CompletableFuture}&lt;{@linkplain HttpResponse}&gt;.</li>

 * </ul>

 *

 * <p> Once a {@link HttpResponse} is received, the headers, response code,

 * and body (typically) are available. Whether the response body bytes has been

 * read or not depends on the type {@code <T>} of the response body. See below.

 *

 * <p> <b>Request bodies</b>

 *

 * <p> Request bodies can be sent using one of the convenience request publisher

 * implementations, provided in {@link BodyPublisher}. Alternatively, a custom

 * Publisher implementation can be used.

 * <ul>

 * <li>{@link BodyPublisher#fromByteArray(byte[]) fromByteArray(byte[])} from byte array</li>

 * <li>{@link BodyPublisher#fromByteArrays(Iterable) fromByteArrays(Iterable)}

 *      from an Iterable of byte arrays</li>

 * <li>{@link BodyPublisher#fromFile(java.nio.file.Path) fromFile(Path)} from the file located

 *     at the given Path</li>

 * <li>{@link BodyPublisher#fromString(java.lang.String) fromString(String)} from a String </li>

 * <li>{@link BodyPublisher#fromInputStream(Supplier) fromInputStream}({@link Supplier}&lt;

 *      {@link InputStream}&gt;) from an InputStream obtained from a Supplier</li>

 * <li>{@link BodyPublisher#noBody() noBody()} no request body is sent</li>

 * </ul>

 *

 * <p> <b>Response bodies</b>

 *

 * <p> Responses bodies are handled at two levels. When sending the request,

 * a response {@linkplain BodyHandler body handler} is specified. This is a

 * function that will be called with the response status code and headers, once

 * they are received. This function must to return a {@link

 * HttpResponse.BodySubscriber}{@code <T>} which is used to read the response

 * body bytes, converting them into an instance of {@code T}. After this occurs,

 * the response becomes available in a {@link HttpResponse}, and the {@link

 * HttpResponse#body()} can be invoked to obtain the actual body. Some

 * implementations and examples of usage of both {@link

 * HttpResponse.BodySubscriber} and {@link HttpResponse.BodyHandler} are

 * provided in {@link HttpResponse}:

 *

 * <p> <b>Some of the pre-defined body handlers</b><br>

 * <ul>

 * <li>{@link BodyHandler#asByteArray() BodyHandler.asByteArray()}

 * stores the body in a byte array</li>

 * <li>{@link BodyHandler#asString() BodyHandler.asString()}

 * stores the body as a String </li>

 * <li>{@link BodyHandler#asFile(java.nio.file.Path)

 * BodyHandler.asFile(Path)} stores the body in a named file</li>

 * <li>{@link BodyHandler#replace(Object) BodyHandler.replace(Objectt)}

 * discards the response body and returns the given replacement value instead.</li>

 * </ul>

 *

 * <p> <b>Blocking/asynchronous behavior and thread usage</b>

 *

 * <p> There are two styles of request sending: <i>synchronous</i> and

 * <i>asynchronous</i>. {@link HttpClient#send(HttpRequest, HttpResponse.BodyHandler) }

 * blocks the calling thread until the request has been sent and the response received.

 *

 * <p> {@link HttpClient#sendAsync(HttpRequest, HttpResponse.BodyHandler)} is

 * asynchronous and returns immediately with a {@link CompletableFuture}<{@link

 * HttpResponse}> and when this object completes (possibly in a different

 * thread) the response has been received.

 *

 * <p> Instances of {@code CompletableFuture} can be combined in different ways

 * to declare the dependencies among several asynchronous tasks, while allowing

 * for the maximum level of parallelism to be utilized.

 *

 * <p> <a id="securitychecks"></a><b>Security checks</b></a>

 *

 * <p> If a security manager is present then security checks are performed by

 * the HTTP Client's sending methods. An appropriate {@link URLPermission} is

 * required to access the destination server, and proxy server if one has

 * been configured. The {@code URLPermission} form used to access proxies uses a

 * method parameter of {@code "CONNECT"} (for all kinds of proxying) and a URL

 * string  of the form {@code "socket://host:port"} where host and port specify

 * the proxy's address.

 *

 * <p> In this implementation, if an explicit {@linkplain

 * HttpClient.Builder#executor(Executor) executor} has not been set for an

 * {@code HttpClient}, and a security manager has been installed, then the

 * default executor will execute asynchronous and dependent tasks in a context

 * that is granted no permissions. Custom {@linkplain HttpRequest.BodyPublisher

 * request body publishers}, {@linkplain HttpResponse.BodyHandler response body

 * handlers}, {@linkplain HttpResponse.BodySubscriber response body subscribers},

 * and {@linkplain WebSocket.Listener WebSocket Listeners}, if executing

 * operations that require privileges, should do so  within an appropriate

 * {@linkplain AccessController#doPrivileged(PrivilegedAction) privileged context}.

 *

 * <p> <b>Examples</b>

 * <pre>{@code    HttpClient client = HttpClient.newHttpClient();

 *

 *    HttpRequest request = HttpRequest

 *            .newBuilder(URI.create("http://www.foo.com/"))

 *            .POST(BodyPublisher.fromString("Hello world"))

 *            .build();

 *

 *    HttpResponse<Path> response =

 *        client.send(request, BodyHandler.asFile(Paths.get("/path")));

 *

 *    Path body = response.body(); }</pre>

 *

 * <p><b>Asynchronous Example</b>

 *

 * <p> The above example will work asynchronously, if {@link HttpClient#sendAsync

 * (HttpRequest, HttpResponse.BodyHandler) sendAsync} is used instead of

 * {@link HttpClient#send(HttpRequest,HttpResponse.BodyHandler) send}

 * in which case the returned object is a {@link CompletableFuture}{@code <HttpResponse>}

 * instead of {@link HttpResponse}. The following example shows how multiple requests

 * can be sent asynchronously. It also shows how dependent asynchronous operations

 * (receiving response, and receiving response body) can be chained easily using

 * one of the many methods in {@code CompletableFuture}.

 * <pre>{@code     // fetch a list of target URIs asynchronously and store them in Files.

 *

 *    List<URI> targets = ...

 *

 *    List<CompletableFuture<File>> futures = targets

 *        .stream()

 *        .map(target -> client

 *                .sendAsync(

 *                    HttpRequest.newBuilder(target)

 *                               .GET()

 *                               .build(),

 *                    BodyHandler.asFile(Paths.get("base", target.getPath())))

 *                .thenApply(response -> response.body())

 *                .thenApply(path -> path.toFile()))

 *        .collect(Collectors.toList());

 *

 *    // all async operations waited for here

 *

 *    CompletableFuture.allOf(futures.toArray(new CompletableFuture<?>[0]))

 *        .join();

 *

 *    // all elements of futures have completed and can be examined.

 *    // Use File.exists() to check whether file was successfully downloaded }</pre>

 *

 */

public abstract class HttpRequest {

    /**

     * Creates an HttpRequest.

     */

    protected HttpRequest() {}

    /**

     * A builder of {@linkplain HttpRequest HTTP Requests}.

     * {@Incubating}

     *

     * <p> Instances of {@code HttpRequest.Builder} are created by calling {@link

     * HttpRequest#newBuilder(URI)} or {@link HttpRequest#newBuilder()}.

     *

     * <p> Each of the setter methods in this class modifies the state of the

     * builder and returns <i>this</i> (ie. the same instance). The methods are

     * not synchronized and should not be called from multiple threads without

     * external synchronization.

     *

     * <p> Note, that not all request headers may be set by user code. Some are

     * restricted for security reasons and others such as the headers relating

     * to authentication, redirection and cookie management are managed by

     * specific APIs rather than through directly user set headers.

     *

     * <p> The {@linkplain #build() build} method returns a new {@code

     * HttpRequest} each time it is invoked.

     *

     */

    public abstract static class Builder {

        /**

         * Creates a Builder.

         */

        protected Builder() {}

        /**

         * Sets this {@code HttpRequest}'s request {@code URI}.

         *

         * @param uri the request URI

         * @return this request builder

         * @throws IllegalArgumentException if the {@code URI} scheme is not

         *         supported

         */

        public abstract Builder uri(URI uri);

        /**

         * Requests the server to acknowledge the request before sending the

         * body. This is disabled by default. If enabled, the server is

         * requested to send an error response or a {@code 100 Continue}

         * response before the client sends the request body. This means the

         * request publisher for the request will not be invoked until this

         * interim response is received.

         *

         * @param enable {@code true} if Expect continue to be sent

         * @return this request builder

         */

        public abstract Builder expectContinue(boolean enable);

        /**

         * Sets the preferred {@link HttpClient.Version} for this request.

         *

         * <p> The corresponding {@link HttpResponse} should be checked for the

         * version that was actually used. If the version is not set in a

         * request, then the version requested will be that of the sending

         * {@link HttpClient}.

         *

         * @param version the HTTP protocol version requested

         * @return this request builder

         */

        public abstract Builder version(HttpClient.Version version);

        /**

         * Adds the given name value pair to the set of headers for this request.

         * The given value is added to the list of values for that name.

         *

         * @implNote An implementation may choose to restrict some header names

         *           or values, as the HTTP Client may determine their value itself.

         *           For example, "Content-Length", which will be determined by

         *           the request Publisher. In such a case, an implementation of

         *           {@code HttpRequest.Builder} may choose to throw an

         *           {@code IllegalArgumentException} if such a header is passed

         *           to the builder.

         *

         * @param name the header name

         * @param value the header value

         * @return this request builder

         * @throws IllegalArgumentException if the header name or value is not

         *         valid, see <a href="https://tools.ietf.org/html/rfc7230#section-3.2">

         *         RFC 7230 section-3.2</a>, or the header name or value is restricted

         *         by the implementation.

         */

        public abstract Builder header(String name, String value);

        /**

         * Adds the given name value pairs to the set of headers for this

         * request. The supplied {@code String} instances must alternate as

         * header names and header values.

         * To add several values to the same name then the same name must

         * be supplied with each new value.

         *

         * @param headers the list of name value pairs

         * @return this request builder

         * @throws IllegalArgumentException if there are an odd number of

         *         parameters, or if a header name or value is not valid, see

         *         <a href="https://tools.ietf.org/html/rfc7230#section-3.2">

         *         RFC 7230 section-3.2</a>, or a header name or value is

         *         {@linkplain #header(String, String) restricted} by the

         *         implementation.

         */

        public abstract Builder headers(String... headers);

        /**

         * Sets a timeout for this request. If the response is not received

         * within the specified timeout then a {@link HttpTimeoutException} is

         * thrown from {@link HttpClient#send(jdk.incubator.http.HttpRequest,

         * jdk.incubator.http.HttpResponse.BodyHandler) HttpClient::send} or

         * {@link HttpClient#sendAsync(jdk.incubator.http.HttpRequest,

         * jdk.incubator.http.HttpResponse.BodyHandler) HttpClient::sendAsync}

         * completes exceptionally with a {@code HttpTimeoutException}. The effect

         * of not setting a timeout is the same as setting an infinite Duration, ie.

         * block forever.

         *

         * @param duration the timeout duration

         * @return this request builder

         * @throws IllegalArgumentException if the duration is non-positive

         */

        public abstract Builder timeout(Duration duration);

        /**

         * Sets the given name value pair to the set of headers for this

         * request. This overwrites any previously set values for name.

         *

         * @param name the header name

         * @param value the header value

         * @return this request builder

         * @throws IllegalArgumentException if the header name or value is not valid,

         *         see <a href="https://tools.ietf.org/html/rfc7230#section-3.2">

         *         RFC 7230 section-3.2</a>, or the header name or value is

         *         {@linkplain #header(String, String) restricted} by the

         *         implementation.

         */

        public abstract Builder setHeader(String name, String value);

        /**

         * Sets the request method of this builder to GET.

         * This is the default.

         *

         * @return a {@code HttpRequest}

         */

        public abstract Builder GET();

        /**

         * Sets the request method of this builder to POST and sets its

         * request body publisher to the given value.

         *

         * @param bodyPublisher the body publisher

         *

         * @return a {@code HttpRequest}

         */

        public abstract Builder POST(BodyPublisher bodyPublisher);

        /**

         * Sets the request method of this builder to PUT and sets its

         * request body publisher to the given value.

         *

         * @param bodyPublisher the body publisher

         *

         * @return a {@code HttpRequest}

         */

        public abstract Builder PUT(BodyPublisher bodyPublisher);

        /**

         * Sets the request method of this builder to DELETE and sets its

         * request body publisher to the given value.

         *

         * @param bodyPublisher the body publisher

         *

         * @return a {@code HttpRequest}

         */

        public abstract Builder DELETE(BodyPublisher bodyPublisher);

        /**

         * Sets the request method and request body of this builder to the

         * given values.

         *

         * @apiNote The {@linkplain BodyPublisher#noBody() noBody} request

         * body publisher can be used where no request body is required or

         * appropriate. Whether a method is restricted, or not, is

         * implementation specific. For example, some implementations may choose

         * to restrict the {@code CONNECT} method.

         *

         * @param method the method to use

         * @param bodyPublisher the body publisher

         * @return a {@code HttpRequest}

         * @throws IllegalArgumentException if the method is restricted

         */

        public abstract Builder method(String method, BodyPublisher bodyPublisher);

        /**

         * Builds and returns a {@link HttpRequest}.

         *

         * @return the request

         * @throws IllegalStateException if a URI has not been set

         */

        public abstract HttpRequest build();

        /**

         * Returns an exact duplicate copy of this {@code Builder} based on

         * current state. The new builder can then be modified independently of

         * this builder.

         *

         * @return an exact copy of this Builder

         */

        public abstract Builder copy();

    }

    /**

     * Creates a {@code HttpRequest} builder.

     *

     * @param uri the request URI

     * @return a new request builder

     * @throws IllegalArgumentException if the URI scheme is not supported.

     */

    public static HttpRequest.Builder newBuilder(URI uri) {

        return new HttpRequestBuilderImpl(uri);

    }

    /**

     * Creates a {@code HttpRequest} builder.

     *

     * @return a new request builder

     */

    public static HttpRequest.Builder newBuilder() {

        return new HttpRequestBuilderImpl();

    }

    /**

     * Returns an {@code Optional} containing the {@link BodyPublisher} set on

     * this request. If no {@code BodyPublisher} was set in the requests's

     * builder, then the {@code Optional} is empty.

     *

     * @return an {@code Optional} containing this request's {@code BodyPublisher}

     */

    public abstract Optional<BodyPublisher> bodyPublisher();

    /**

     * Returns the request method for this request. If not set explicitly,

     * the default method for any request is "GET".

     *

     * @return this request's method

     */

    public abstract String method();

    /**

     * Returns an {@code Optional} containing this request's timeout duration.

     * If the timeout duration was not set in the request's builder, then the

     * {@code Optional} is empty.

     *

     * @return an {@code Optional} containing this request's timeout duration

     */

    public abstract Optional<Duration> timeout();

    /**

     * Returns this request's {@link HttpRequest.Builder#expectContinue(boolean)

     * expect continue } setting.

     *

     * @return this request's expect continue setting

     */