/*

 * 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.net.Authenticator;

import java.net.CookieManager;

import java.net.InetSocketAddress;

import java.net.NetPermission;

import java.net.ProxySelector;

import java.net.URI;

import java.util.Optional;

import java.util.concurrent.ExecutorService;

import java.util.concurrent.Executors;

import javax.net.ssl.SSLContext;

import javax.net.ssl.SSLParameters;

/**

 * A container for configuration information common to multiple {@link

 * HttpRequest}s. All requests are associated with, and created from a {@code

 * HttpClient}.

 *

 * <p> {@code HttpClient}s are immutable and created from a builder returned

 * from {@link HttpClient#create()}. Request builders that are associated with

 * an application created client, are created by calling {@link #request(URI) }.

 * It is also possible to create a request builder directly which is associated

 * with the <i>default</i> {@code HttpClient} by calling {@link

 * HttpRequest#create(URI)}.

 *

 * <p> The HTTP API functions asynchronously (using {@link

 * java.util.concurrent.CompletableFuture}) and also in a simple synchronous

 * mode, where all work may be done on the calling thread. In asynchronous mode,

 * work is done on the threads supplied by the client's {@link

 * java.util.concurrent.ExecutorService}.

 *

 * <p> <a name="defaultclient"></a> The <i>default</i> {@code HttpClient} is

 * used whenever a request is created without specifying a client explicitly

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

 * There is only one static instance of this {@code HttpClient}. A reference to

 * the default client can be obtained by calling {@link #getDefault() }. If a

 * security manager is set, then a permission is required for this.

 *

 * <p> See {@link HttpRequest} for examples of usage of this API.

 *

 * @since 9

 */

public abstract class HttpClient {

    HttpClient() {}

    private static HttpClient defaultClient;

    /**

     * Creates a new {@code HttpClient} builder.

     *

     * @return a {@code HttpClient.Builder}

     */

    public static Builder  create() {

        return new HttpClientBuilderImpl();

    }

    //public abstract void debugPrint();

    /**

     * Returns the default {@code HttpClient} that is used when a {@link

     * HttpRequest} is created without specifying a client. If a security

     * manager is set, then its {@code checkPermission} method is called with a

     * {@link java.net.NetPermission} specifying the name "getDefaultHttpClient".

     * If the caller does not possess this permission a {@code SecurityException}

     * is thrown.

     *

     * @implNote Code running under a security manager can avoid the security

     * manager check by creating a {@code HttpClient} explicitly.

     *

     * @return the default {@code HttpClient}

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

     *                           permission

     */

    public synchronized static HttpClient getDefault() {

        Utils.checkNetPermission("getDefaultHttpClient");

        if (defaultClient == null) {

            Builder b = create();

            defaultClient = b.executorService(Executors.newCachedThreadPool())

                             .build();

        }

        return defaultClient;

    }

    /**

     * Creates a {@code HttpRequest} builder associated with this client.

     *

     * @return a new builder

     */

    public abstract HttpRequest.Builder request();

    /**

     * Creates a {@code HttpRequest} builder associated with this client and

     * using the given request URI.

     *

     * @param uri the request URI

     * @return a new builder

     */

    public abstract HttpRequest.Builder request(URI uri);

    /**

     * A builder of immutable {@link HttpClient}s. {@code HttpClient.Builder}s

     * are created by calling {@link HttpClient#create()}.

     *

     * <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> {@link #build() } returns a new {@code HttpClient} each time it is

     * called.

     *

     * @since 9

     */

    public abstract static class Builder {

        Builder() {}

        /**

         * Sets a cookie manager.

         *

         * @param manager the CookieManager

         * @return this builder

         * @throws NullPointerException if {@code manager} is null

         */

        public abstract Builder cookieManager(CookieManager manager);

        /**

         * Sets an SSLContext. If a security manager is set, then the caller

         * must have the {@link java.net.NetPermission NetPermission}

         * ("setSSLContext")

         *

         * <p> The effect of not calling this method, is that a default {@link

         * javax.net.ssl.SSLContext} is used, which is normally adequate for

         * client applications that do not need to specify protocols, or require

         * client authentication.

         *

         * @param sslContext the SSLContext

         * @return this builder

         * @throws NullPointerException if {@code sslContext} is null

         * @throws SecurityException if a security manager is set and the

         *                           caller does not have any required permission

         */

        public abstract Builder sslContext(SSLContext sslContext);

        /**

         * Sets an SSLParameters. If this method is not called, then a default

         * set of parameters are used. The contents of the given object are

         * copied. Some parameters which are used internally by the HTTP protocol

         * implementation (such as application protocol list) should not be set

         * by callers, as they are ignored.

         *

         * @param sslParameters the SSLParameters

         * @return this builder

         * @throws NullPointerException if {@code sslParameters} is null

         */

        public abstract Builder sslParameters(SSLParameters sslParameters);

        /**

         * Sets the ExecutorService to be used for sending and receiving

         * asynchronous requests. If this method is not called, a default

         * executor service is set, which is the one returned from {@link

         * java.util.concurrent.Executors#newCachedThreadPool()

         * Executors.newCachedThreadPool}.

         *

         * @param s the ExecutorService

         * @return this builder

         * @throws NullPointerException if {@code s} is null

         */

        public abstract Builder executorService(ExecutorService s);

        /**

         * Specifies whether requests will automatically follow redirects issued

         * by the server. This setting can be overridden on each request. The

         * default value for this setting is {@link Redirect#NEVER NEVER}

         *

         * @param policy the redirection policy

         * @return this builder

         * @throws NullPointerException if {@code policy} is null

         */

        public abstract Builder followRedirects(Redirect policy);

        /**

         * Requests a specific HTTP protocol version where possible. If not set,

         * the version defaults to {@link HttpClient.Version#HTTP_1_1}. If

         * {@link HttpClient.Version#HTTP_2} is set, then each request will

         * attempt to upgrade to HTTP/2.  If the upgrade succeeds, then the

         * response to this request will use HTTP/2 and all subsequent requests

         * and responses to the same

         * <a href="https://tools.ietf.org/html/rfc6454#section-4">origin server</a>

         * will use HTTP/2. If the upgrade fails, then the response will be

         * handled using HTTP/1.1

         *

         * <p>This setting can be over-ridden per request.

         *

         * @param version the requested HTTP protocol version

         * @return this builder

         * @throws NullPointerException if {@code version} is null

         */

        public abstract Builder version(HttpClient.Version version);

        /**

         * Sets the default priority for any HTTP/2 requests sent from this

         * client. The value provided must be between {@code 1} and {@code 255}.

         *

         * @param priority the priority weighting

         * @return this builder

         * @throws IllegalArgumentException if the given priority is out of range

         */

        public abstract Builder priority(int priority);

        /**

         * Enables pipelining mode for HTTP/1.1 requests sent through this

         * client. When pipelining is enabled requests to the same destination

         * are sent over existing TCP connections that may already have requests

         * outstanding. This reduces the number of connections, but may have

         * a performance impact since responses must be delivered in the same

         * order that they were sent. By default, pipelining is disabled.

         *

         * @param enable {@code true} enables pipelining

         * @return this builder

         * @throws UnsupportedOperationException if pipelining mode is not

         *                                       supported by this implementation

         */

        public abstract Builder pipelining(boolean enable);

        /**

         * Sets a {@link java.net.ProxySelector} for this client. If no selector

         * is set, then no proxies are used. If a {@code null} parameter is

         * given then the system wide default proxy selector is used.

         *

         * @implNote {@link java.net.ProxySelector#of(InetSocketAddress)}

         * provides a ProxySelector which uses one proxy for all requests.

         *

         * @param selector the ProxySelector

         * @return this builder

         */

        public abstract Builder proxy(ProxySelector selector);

        /**

         * Sets an authenticator to use for HTTP authentication.

         *

         * @param a the Authenticator

         * @return this builder

         */

        public abstract Builder authenticator(Authenticator a);

        /**

         * Returns a {@link HttpClient} built from the current state of this

         * builder.

         *

         * @return this builder

         */

        public abstract HttpClient build();

    }

    /**

     * Returns an {@code Optional} which contains this client's {@link

     * CookieManager}. If no CookieManager was set in this client's builder,

     * then the {@code Optional} is empty.

     *

     * @return an {@code Optional} containing this client's CookieManager

     */

    public abstract Optional<CookieManager> cookieManager();

    /**

     * Returns the follow-redirects setting for this client. The default value

     * for this setting is {@link HttpClient.Redirect#NEVER}

     *

     * @return this client's follow redirects setting

     */

    public abstract Redirect followRedirects();

    /**

     * Returns an {@code Optional} containing the ProxySelector for this client.

     * If no proxy is set then the {@code Optional} is empty.

     *

     * @return an {@code Optional} containing this client's proxy selector

     */

    public abstract Optional<ProxySelector> proxy();

    /**

     * Returns the SSLContext, if one was set on this client. If a security

     * manager is set then then caller must then the caller must have the

     * {@link java.net.NetPermission NetPermission}("getSSLContext") permission.

     * If no SSLContext was set, then the default context is returned.

     *

     * @return this client's SSLContext

     */

    public abstract SSLContext sslContext();

    /**

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

     * this client. If no {@code SSLParameters} were set in the client's builder,

     * then the {@code Optional} is empty.

     *

     * @return an {@code Optional} containing this client's SSLParameters

     */

    public abstract Optional<SSLParameters> sslParameters();

    /**

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

     * this client. If no {@code Authenticator} was set in the client's builder,

     * then the {@code Optional} is empty.

     *

     * @return an {@code Optional} containing this client's Authenticator

     */

    public abstract Optional<Authenticator> authenticator();

    /**

     * Returns the HTTP protocol version requested for this client. The default

     * value is {@link HttpClient.Version#HTTP_1_1}

     *

     * @return the HTTP protocol version requested

     */

    public abstract HttpClient.Version version();

    /**

     * Returns whether this client supports HTTP/1.1 pipelining.

     *

     * @return whether pipelining allowed

     */

    public abstract boolean pipelining();

    /**

     * Returns the {@code ExecutorService} set on this client. If an {@code

     * ExecutorService} was not set on the client's builder, then a default

     * object is returned. The default ExecutorService is created independently

     * for each client.

     *

     * @return this client's ExecutorService

     */

    public abstract ExecutorService executorService();

    /**

     * The HTTP protocol version.

     *

     * @since 9

     */

    public static enum Version {

        /**

         * HTTP version 1.1

         */

        HTTP_1_1,

        /**

         * HTTP version 2

         */

        HTTP_2

    }

    /**

     * Defines automatic redirection policy. This is checked whenever a 3XX

     * response code is received. If redirection does not happen automatically

     * then the response is returned to the user, where it can be handled

     * manually.

     *

     * <p> {@code Redirect} policy is set via the {@link

     * HttpClient.Builder#followRedirects(HttpClient.Redirect)} method.

     *

     * @since 9

     */

    public static enum Redirect {

        /**

         * Never redirect.

         */

        NEVER,

        /**

         * Always redirect.

         */

        ALWAYS,

        /**

         * Redirect to same protocol only. Redirection may occur from HTTP URLs

         * to other HTTP URLs, and from HTTPS URLs to other HTTPS URLs.

         */

        SAME_PROTOCOL,

        /**

         * Redirect always except from HTTPS URLs to HTTP URLs.

         */

        SECURE

    }

}