/*

 * Copyright (c) 2015, 2016, 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.io.InputStream;

import java.io.UncheckedIOException;

import java.net.URI;

import java.net.ProxySelector;

import java.nio.ByteBuffer;

import java.nio.channels.FileChannel;

import java.nio.charset.*;

import java.nio.file.Path;

import java.util.Iterator;

import java.util.concurrent.CompletableFuture;

import java.util.concurrent.TimeUnit;

import java.util.function.LongConsumer;

/**

 * Represents one HTTP request which can be sent to a server. {@code

 * HttpRequest}s are built from {@code HttpRequest} {@link HttpRequest.Builder

 * builder}s. {@code HttpRequest} builders are obtained from a {@link HttpClient}

 * by calling {@link HttpClient#request(java.net.URI) HttpClient.request}, or

 * by calling {@link #create(java.net.URI) HttpRequest.create} which returns a

 * builder on the <a href="HttpClient.html#defaultclient">default</a> client.

 * A request's {@link java.net.URI}, headers and body can be set. Request bodies

 * are provided through a {@link BodyProcessor} object. Once all required

 * parameters have been set in the builder, one of the builder methods should be

 * called, which sets the request method and returns a {@code HttpRequest}.

 * These methods are {@link Builder#GET() GET}, {@link HttpRequest.Builder#POST()

 * POST} and {@link HttpRequest.Builder#PUT() PUT} which return a GET, POST or

 * PUT request respectively. Alternatively, {@link

 * HttpRequest.Builder#method(String) method} can be called to set an arbitrary

 * method type (and return a {@code HttpRequest}). Builders can also be copied

 * and modified multiple times in order to build multiple related requests that

 * differ in some parameters.

 *

 * <p> Two simple, example HTTP interactions are shown below:

 * <pre>

 * {@code

 *      // GET

 *      HttpResponse response = HttpRequest

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

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

 *          .GET()

 *          .response();

 *

 *      int statusCode = response.statusCode();

 *      String responseBody = response.body(asString());

 *

 *      // POST

 *      response = HttpRequest

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

 *          .body(fromString("param1=foo,param2=bar"))

 *          .POST()

 *          .response();}

 * </pre>

 *

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

 * following methods.

 * <ul><li>{@link #response() response} blocks until the entire request has been

 * sent and the response status code and headers have been received.</li>

 * <li>{@link #responseAsync() responseAsync} sends the request and receives the

 * response asynchronously. Returns immediately with a

 * {@link java.util.concurrent.CompletableFuture CompletableFuture}<{@link

 * HttpResponse}&gt;.</li>

 * <li>{@link #multiResponseAsync(HttpResponse.MultiProcessor) multiResponseAsync}

 * sends the request asynchronously, expecting multiple responses. This

 * capability is of most relevance to HTTP/2 server push, but can be used for

 * single responses (HTTP/1.1 or HTTP/2) also.</li>

 * </ul>

 *

 * <p> Once a request has been sent, it is an error to try and send it again.

 *

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

 * available. The body can then be received by calling one of the body methods

 * on {@code HttpResponse}.

 *

 * <p> See below for discussion of synchronous versus asynchronous usage.

 *

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

 *

 * <p> Request bodies are sent using one of the request processor implementations

 * below provided in {@code HttpRequest}, or else a custom implementation can be

 * used.

 * <ul>

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

 * <li>{@link #fromByteArrays(java.util.Iterator) fromByteArrays(Iterator)}

 *      from an iterator of byte arrays</li>

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

 *     at the given Path</li>

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

 * <li>{@link #fromInputStream(java.io.InputStream) fromInputStream(InputStream)}

 *      request body from InputStream</li>

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

 * </ul>

 *

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

 *

 * <p> Responses bodies are handled by the {@link HttpResponse.BodyProcessor}

 * {@code <T>} supplied to the {@link HttpResponse#body(HttpResponse.BodyProcessor)

 * HttpResponse.body} and {@link HttpResponse#bodyAsync(HttpResponse.BodyProcessor)

 * HttpResponse.bodyAsync} methods. Some implementations of {@code

 * HttpResponse.BodyProcessor} are provided in {@link HttpResponse}:

 * <ul>

 * <li>{@link HttpResponse#asByteArray() } stores the body in a byte array</li>

 * <li>{@link HttpResponse#asString()} stores the body as a String </li>

 * <li>{@link HttpResponse#asFile(java.nio.file.Path) } stores the body in a

 * named file</li>

 * <li>{@link HttpResponse#ignoreBody() } ignores any received response body</li>

 * </ul>

 *

 * <p> The output of a response processor is the response body, and its

 * parameterized type {@code T} determines the type of the body object returned

 * from {@code HttpResponse.body} and {@code HttpResponse.bodyAsync}. Therefore,

 * as an example, the second response processor in the list above has the type

 * {@code HttpResponse.BodyProcessor<String>} which means the type returned by

 * {@code HttpResponse.body()} is a String. Response processors can be defined

 * to return potentially any type as body.

 *

 * <p> <b>Multi responses</b>

 *

 * <p> With HTTP/2 it is possible for a server to return a main response and zero

 * or more additional responses (known as server pushes) to a client-initiated

 * request. These are handled using a special response processor called {@link

 * HttpResponse.MultiProcessor}.

 *

 * <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 #response() response} blocks the calling thread

 * until the request has been sent and the response received.

 *

 * <p> {@link #responseAsync() responseAsync} is asynchronous and returns

 * immediately with a {@link java.util.concurrent.CompletableFuture}<{@link

 * HttpResponse}> and when this object completes (in a background thread) the

 * response has been received.

 *

 * <p> {@link #multiResponseAsync(HttpResponse.MultiProcessor) multiResponseAsync}

 * is the variant for multi responses and is also asynchronous.

 *

 * <p> CompletableFutures 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> <b>Security checks</b>

 *

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

 * the {@link #response() } and {@link #responseAsync() } methods. A {@link

 * java.net.URLPermission} or {@link java.net.SocketPermission} is required to

 * access any destination origin server and proxy server utilised. URLPermissions

 * should be preferred in policy files over SocketPermissions given the more

 * limited scope of URLPermission. Permission is always implicitly granted to a

 * system's default proxies. The URLPermission form used to access proxies uses

 * a method parameter of "CONNECT" (for all kinds of proxying) and a url string

 * of the form "socket://host:port" where host and port specify the proxy's

 * address.

 *

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

 * <pre>

 *     import static java.net.http.HttpRequest.*;

 *     import static java.net.http.HttpResponse.*;

 *

 *     //Simple blocking

 *

 *     HttpResponse r1 = HttpRequest.create(new URI("http://www.foo.com/"))

 *                                  .GET()

 *                                 .response();

 *     int responseCode = r1.statusCode());

 *     String body = r1.body(asString());

 *

 *     HttpResponse r2 = HttpRequest.create(new URI("http://www.foo.com/"))

 *                                  .GET()

 *                                  .response();

 *

 *     System.out.println("Response was " + r1.statusCode());

 *     Path body1 = r2.body(asFile(Paths.get("/tmp/response.txt")));

 *     // Content stored in /tmp/response.txt

 *

 *     HttpResponse r3 = HttpRequest.create(new URI("http://www.foo.com/"))

 *                                  .body(fromString("param1=1, param2=2"))

 *                                  .POST()

 *                                  .response();

 *

 *     Void body2 = r3.body(ignoreBody()); // body is Void in this case

 * </pre>

 *

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

 *

 * <p> All of the above examples will work asynchronously, if {@link

 * #responseAsync()} is used instead of {@link #response()} in which case the

 * returned object is a {@code CompletableFuture<HttpResponse>} instead of

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

 *              return HttpRequest

 *                  .create(target)

 *                  .GET()

 *                  .responseAsync()

 *                  .thenCompose(response -> {

 *                      Path dest = Paths.get("base", target.getPath());

 *                      if (response.statusCode() == 200) {

 *                          return response.bodyAsync(asFile(dest));

 *                      } else {

 *                          return CompletableFuture.completedFuture(dest);

 *                      }

 *                  })

 *                  // convert Path -> File

 *                  .thenApply((Path dest) -> {

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

 *

 * @since 9

 */

public abstract class HttpRequest {

    HttpRequest() {}

    /**

     * A builder of {@link HttpRequest}s. {@code HttpRequest.Builder}s are

     * created by calling {@link HttpRequest#create(URI)} or {@link

     * HttpClient#request(URI)}.

     *

     * <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> The build methods return a new {@code HttpRequest} each time they are

     * called.

     *

     * @since 9

     */

    public abstract static class Builder {

        Builder() {}

        /**

         * Sets this HttpRequest's request URI.

         *

         * @param uri the request URI

         * @return this request builder

         */

        public abstract Builder uri(URI uri);

        /**

         * Specifies whether this request will automatically follow redirects

         * issued by the server. The default value for this setting is the value

         * of {@link HttpClient#followRedirects() }

         *

         * @param policy the redirection policy

         * @return this request builder

         */

        public abstract Builder followRedirects(HttpClient.Redirect policy);

        /**

         * Request server to acknowledge request before sending request

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

         * to send an error response or a 100-Continue response before the client

         * sends the request body. This means the request processor 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);

        /**

         * Overrides the {@link HttpClient#version()  } setting for this

         * request.

         *

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

         *

         * @param name the header name

         * @param value the header value

         * @return this request builder

         */

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

        /**

         * Overrides the ProxySelector set on the request's client for this

         * request.

         *

         * @param proxy the ProxySelector to use

         * @return this request builder

         */

        public abstract Builder proxy(ProxySelector proxy);

        /**

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

         * request. The supplied Strings must alternate as names and values.

         *

         * @param headers the list of String name value pairs

         * @return this request builder

         * @throws IllegalArgumentException if there is an odd number of

         *                                  parameters

         */

        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 #response() } or {@link #responseAsync() }

         * completes exceptionally with a {@code HttpTimeoutException}.

         *

         * @param unit the timeout units

         * @param timeval the number of units to wait for

         * @return this request builder

         */

        public abstract Builder timeout(TimeUnit unit, long timeval);

        /**

         * 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

         */

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

        /**

         * Sets a request body for this builder. See {@link HttpRequest}

         * for example {@code BodyProcessor} implementations.

         * If no body is specified, then no body is sent with the request.

         *

         * @param reqproc the request body processor

         * @return this request builder

         */

        public abstract Builder body(BodyProcessor reqproc);

        /**

         * Builds and returns a GET {@link HttpRequest} from this builder.

         *

         * @return a {@code HttpRequest}

         */

        public abstract HttpRequest GET();

        /**

         * Builds and returns a POST {@link HttpRequest} from this builder.

         *

         * @return a {@code HttpRequest}

         */

        public abstract HttpRequest POST();

        /**

         * Builds and returns a PUT {@link HttpRequest} from this builder.

         *

         * @return a {@code HttpRequest}

         */

        public abstract HttpRequest PUT();

        /**

         * Builds and returns a {@link HttpRequest} from this builder using

         * the given method String. The method string is case-sensitive, and

         * may be rejected if an upper-case string is not used.

         *

         * @param method the method to use

         * @return a {@code HttpRequest}

         * @throws IllegalArgumentException if an unrecognised method is used

         */

        public abstract HttpRequest method(String method);

        /**

         * Returns an exact duplicate copy of this 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 HttpRequest builder from the <i>default</i> HttpClient.

     *

     * @param uri the request URI

     * @return a new request builder

     */

    public static HttpRequest.Builder create(URI uri) {

        return HttpClient.getDefault().request(uri);

    }

    /**

     * Returns the follow-redirects setting for this request.

     *

     * @return follow redirects setting

     */

    public abstract HttpClient.Redirect followRedirects();

    /**

     * Returns the response to this request, by sending it and blocking if

     * necessary to get the response. The {@link HttpResponse} contains the

     * response status and headers.

     *

     * @return a HttpResponse for this request

     * @throws IOException if an I/O error occurs

     * @throws InterruptedException if the operation was interrupted

     * @throws SecurityException if the caller does not have the required

     *                           permission

     * @throws IllegalStateException if called more than once or if

     *                               responseAsync() called previously

     */

    public abstract HttpResponse response()

        throws IOException, InterruptedException;

    /**

     * Sends the request and returns the response asynchronously. This method

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

     * HttpResponse}>

     *

     * @return a {@code CompletableFuture<HttpResponse>}

     * @throws IllegalStateException if called more than once or if response()

     *                               called previously.

     */

    public abstract CompletableFuture<HttpResponse> responseAsync();

    /**

     * Sends the request asynchronously expecting multiple responses.

     *

     * <p> This method must be given a {@link HttpResponse.MultiProcessor} to

     * handle the multiple responses.

     *

     * <p> If a security manager is set, the caller must possess a {@link

     * java.net.URLPermission} for the request's URI, method and any user set

     * headers. The security manager is also checked for each incoming

     * additional server generated request/response. Any request that fails the

     * security check, is canceled and ignored.

     *

     * <p> This method can be used for both HTTP/1.1 and HTTP/2, but in cases

     * where multiple responses are not supported, the MultiProcessor

     * only receives the main response.

     *

     * <p> The aggregate {@code CompletableFuture} returned from this method

     * returns a {@code <U>} defined by the {@link HttpResponse.MultiProcessor}

     * implementation supplied. This will typically be a Collection of

     * HttpResponses or of some response body type.

     *

     * @param <U> the aggregate response type

     * @param rspproc the MultiProcessor for the request

     * @return a {@code CompletableFuture<U>}

     * @throws IllegalStateException if the request has already been sent.

     */

    public abstract <U> CompletableFuture<U>

    multiResponseAsync(HttpResponse.MultiProcessor<U> rspproc);

    /**

     * 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 this request's {@link HttpRequest.Builder#expectContinue(boolean)

     * expect continue } setting.

     *

     * @return this request's expect continue setting

     */

    public abstract boolean expectContinue();

    /**

     * Returns this request's request URI.

     *

     * @return this request's URI

     */

    public abstract URI uri();

    /**

     * Returns this request's {@link HttpClient}.

     *

     * @return this request's HttpClient

     */

    public abstract HttpClient client();

    /**

     * Returns the HTTP protocol version that this request will use or used.