https://openjdk.java.net/ 
/*
 * 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 jdk.incubator.http;

import java.io.IOException;
import java.net.Authenticator;
import java.net.CookieManager;
import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.net.URI;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executor;
import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLParameters;


A container for configuration information common to multiple HttpRequests. All requests are sent through a HttpClient. {@Incubating} 
 HttpClients are immutable and created from a builder returned from newBuilder(). Request builders are created by calling HttpRequest.newBuilder(). 
 See HttpRequest for examples of usage of this API. 
Since:9
/**
 * A container for configuration information common to multiple {@link
 * HttpRequest}s. All requests are sent through a {@code HttpClient}.
 * {@Incubating}
 *
 * <p> {@code HttpClient}s are immutable and created from a builder returned
 * from {@link HttpClient#newBuilder()}. Request builders are created by calling
 * {@link HttpRequest#newBuilder() }.
 * <p>
 * See {@link HttpRequest} for examples of usage of this API.
 *
 * @since 9
 */
public abstract class HttpClient {

    
Creates an HttpClient.

/**
     * Creates an HttpClient.
     */
    protected HttpClient() {}

    
Returns a new HttpClient with default settings.

Returns:a new HttpClient
/**
     * Returns a new HttpClient with default settings.
     *
     * @return a new HttpClient
     */
    public static HttpClient newHttpClient() {
        return new HttpClientBuilderImpl().build();
    }

    
Creates a new HttpClient builder. 
Returns:a HttpClient.Builder
/**
     * Creates a new {@code HttpClient} builder.
     *
     * @return a {@code HttpClient.Builder}
     */
    public static Builder newBuilder() {
        return new HttpClientBuilderImpl();
    }

    
A builder of immutable HttpClients. HttpClient.Builders are created by calling HttpClient.newBuilder(). {@Incubating} 
 Each of the setter methods in this class modifies the state of the
builder and returns this (ie. the same instance). The methods are
not synchronized and should not be called from multiple threads without
external synchronization.

 build() returns a new HttpClient each time it is called. 
Since:9
/**
     * A builder of immutable {@link HttpClient}s. {@code HttpClient.Builder}s
     * are created by calling {@link HttpClient#newBuilder()}.
     * {@Incubating}
     *
     * <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 {

        protected Builder() {}

        
Sets a cookie manager.

Params:
  • cookieManager – the cookie manager
Returns:this builder
/**
         * Sets a cookie manager.
         *
         * @param cookieManager the cookie manager
         * @return this builder
         */
        public abstract Builder cookieManager(CookieManager cookieManager);

        
Sets an SSLContext. If a security manager is set, then the caller must have the NetPermission ("setSSLContext") 
 The effect of not calling this method, is that a default SSLContext is used, which is normally adequate for client applications that do not need to specify protocols, or require client authentication. 
Params:
  • sslContext – the SSLContext
Throws:
  • SecurityException – if a security manager is set and the
                          caller does not have any required permission
Returns:this builder
/**
         * Sets an {@code SSLContext}. If a security manager is set, then the caller
         * must have the {@link java.net.NetPermission NetPermission}
         * ({@code "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 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. 
Params:
  • sslParameters – the SSLParameters
Returns:this builder
/**
         * Sets an {@code 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
         */
        public abstract Builder sslParameters(SSLParameters sslParameters);

        
Sets the executor to be used for asynchronous tasks. If this method is not called, a default executor is set, which is the one returned from 
Executors.newCachedThreadPool. 
Params:
  • executor – the Executor
Returns:this builder
/**
         * Sets the executor to be used for asynchronous tasks. If this method is
         * not called, a default executor is set, which is the one returned from {@link
         * java.util.concurrent.Executors#newCachedThreadPool()
         * Executors.newCachedThreadPool}.
         *
         * @param executor the Executor
         * @return this builder
         */
        public abstract Builder executor(Executor executor);

        
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 NEVER 
Params:
  • policy – the redirection policy
Returns:this builder
/**
         * 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
         */
        public abstract Builder followRedirects(Redirect policy);

        
Requests a specific HTTP protocol version where possible. If not set, the version defaults to Version.HTTP_2. If 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 origin server
will use HTTP/2. If the upgrade fails, then the response will be
handled using HTTP/1.1

Params:
  • version – the requested HTTP protocol version
Returns:this builder
/**
         * Requests a specific HTTP protocol version where possible. If not set,
         * the version defaults to {@link HttpClient.Version#HTTP_2}. 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
         *
         * @param version the requested HTTP protocol version
         * @return this builder
         */
        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 1 and 256 (inclusive). 
Params:
  • priority – the priority weighting
Throws:
Returns:this builder
/**
         * Sets the default priority for any HTTP/2 requests sent from this
         * client. The value provided must be between {@code 1} and {@code 256}
         * (inclusive).
         *
         * @param priority the priority weighting
         * @return this builder
         * @throws IllegalArgumentException if the given priority is out of range
         */
        public abstract Builder priority(int priority);

        
Sets a ProxySelector for this client. If no selector is set, then no proxies are used. If a null parameter is given then the system wide default proxy selector is used. 
Params:
  • selector – the ProxySelector
Implementation Note:ProxySelector.of(InetSocketAddress) provides a ProxySelector which uses one proxy for all requests.
Returns:this builder
/**
         * 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 {@code 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.

Params:
  • a – the Authenticator
Returns:this builder
/**
         * Sets an authenticator to use for HTTP authentication.
         *
         * @param a the Authenticator
         * @return this builder
         */
        public abstract Builder authenticator(Authenticator a);

        
Returns a HttpClient built from the current state of this builder. 
Returns:this builder
/**
         * Returns a {@link HttpClient} built from the current state of this
         * builder.
         *
         * @return this builder
         */
        public abstract HttpClient build();
    }


    
Returns an Optional which contains this client's CookieManager. If no CookieManager was set in this client's builder, then the Optional is empty. 
Returns:an Optional containing this client's CookieManager
/**
     * Returns an {@code Optional} which contains this client's {@link
     * CookieManager}. If no {@code CookieManager} was set in this client's builder,
     * then the {@code Optional} is empty.
     *
     * @return an {@code Optional} containing this client's {@code CookieManager}
     */
    public abstract Optional<CookieManager> cookieManager();

    
Returns the follow-redirects setting for this client. The default value for this setting is Redirect.NEVER 
Returns:this client's follow redirects setting
/**
     * 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 Optional containing the ProxySelector for this client. If no proxy is set then the Optional is empty. 
Returns:an Optional containing this client's proxy selector
/**
     * Returns an {@code Optional} containing the {@code 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 the caller must have the NetPermission("getSSLContext") permission. If no SSLContext was set, then the default context is returned. 
Throws:
Returns:this client's SSLContext
/**
     * Returns the {@code SSLContext}, if one was set on this client. If a security
     * manager is set, then the caller must have the
     * {@link java.net.NetPermission NetPermission}("getSSLContext") permission.
     * If no {@code SSLContext} was set, then the default context is returned.
     *
     * @return this client's SSLContext
     * @throws SecurityException if the caller does not have permission to get
     *         the SSLContext
     */
    public abstract SSLContext sslContext();

    
Returns an Optional containing the SSLParameters set on this client. If no SSLParameters were set in the client's builder, then the Optional is empty. 
Returns:an Optional containing this client's SSLParameters
/**
     * 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 {@code SSLParameters}
     */
    public abstract Optional<SSLParameters> sslParameters();

    
Returns an Optional containing the Authenticator set on this client. If no Authenticator was set in the client's builder, then the Optional is empty. 
Returns:an Optional containing this client's Authenticator
/**
     * 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 {@code Authenticator}
     */
    public abstract Optional<Authenticator> authenticator();

    
Returns the HTTP protocol version requested for this client. The default value is Version.HTTP_2 
Returns:the HTTP protocol version requested
/**
     * Returns the HTTP protocol version requested for this client. The default
     * value is {@link HttpClient.Version#HTTP_2}
     *
     * @return the HTTP protocol version requested
     */
    public abstract HttpClient.Version version();

    
Returns the Executor set on this client. If an 
Executor was not set on the client's builder, then a default object is returned. The default Executor is created independently for each client. 
Returns:this client's Executor
/**
     * Returns the {@code Executor} set on this client. If an {@code
     * Executor} was not set on the client's builder, then a default
     * object is returned. The default {@code Executor} is created independently
     * for each client.
     *
     * @return this client's Executor
     */
    public abstract Executor executor();

    
The HTTP protocol version.
{@Incubating}

Since:9
/**
     * The HTTP protocol version.
     * {@Incubating}
     *
     * @since 9
     */
    public enum Version {

        
HTTP version 1.1

/**
         * HTTP version 1.1
         */
        HTTP_1_1,

        
HTTP version 2

/**
         * HTTP version 2
         */
        HTTP_2
    }

    
Defines automatic redirection policy.
{@Incubating}

 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. 
 Redirect policy is set via the Builder.followRedirects(Redirect) method. 
Since:9
/**
     * Defines automatic redirection policy.
     * {@Incubating}
     *
     * <p> This is checked whenever a {@code 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 enum Redirect {

        
Never redirect.

/**
         * Never redirect.
         */
        NEVER,

        
Always redirect.

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

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

/**
         * Redirect always except from HTTPS URLs to HTTP URLs.
         */
        SECURE
    }

    
Sends the given request using this client, blocking if necessary to get the response. The returned HttpResponse<T> contains the response status, headers, and body ( as handled by given response body handler ). 
Params:
  • req – the request
  • responseBodyHandler – the response body handler
Type parameters:
  • <T> – the response body type
Throws:
Returns:the response body
/**
     * Sends the given request using this client, blocking if necessary to get
     * the response. The returned {@link HttpResponse}{@code <T>} contains the
     * response status, headers, and body ( as handled by given response body
     * handler ).
     *
     * @param <T> the response body type
     * @param req the request
     * @param responseBodyHandler the response body handler
     * @return the response body
     * @throws java.io.IOException if an I/O error occurs when sending or receiving
     * @throws java.lang.InterruptedException if the operation is interrupted
     */
    public abstract <T> HttpResponse<T>
    send(HttpRequest req, HttpResponse.BodyHandler<T> responseBodyHandler)
        throws IOException, InterruptedException;

    
Sends the given request asynchronously using this client and the given
response handler.

Params:
  • req – the request
  • responseBodyHandler – the response body handler
Type parameters:
  • <T> – the response body type
Returns:a CompletableFuture<HttpResponse<T>>
/**
     * Sends the given request asynchronously using this client and the given
     * response handler.
     *
     * @param <T> the response body type
     * @param req the request
     * @param responseBodyHandler the response body handler
     * @return a {@code CompletableFuture<HttpResponse<T>>}
     */
    public abstract <T> CompletableFuture<HttpResponse<T>>
    sendAsync(HttpRequest req, HttpResponse.BodyHandler<T> responseBodyHandler);

    
Sends the given request asynchronously using this client and the given
multi response handler.

Params:
  • req – the request
  • multiProcessor – the MultiProcessor for the request
Type parameters:
  • <U> – a type representing the aggregated results
  • <T> – a type representing all of the response bodies
Returns:a CompletableFuture<U>
/**
     * Sends the given request asynchronously using this client and the given
     * multi response handler.
     *
     * @param <U> a type representing the aggregated results
     * @param <T> a type representing all of the response bodies
     * @param req the request
     * @param multiProcessor the MultiProcessor for the request
     * @return a {@code CompletableFuture<U>}
     */
    public abstract <U, T> CompletableFuture<U>
    sendAsync(HttpRequest req, HttpResponse.MultiProcessor<U, T> multiProcessor);

    
Creates a builder of WebSocket instances connected to the given URI and receiving events and messages with the given Listener. 
 Example


    HttpClient client = HttpClient.newHttpClient();
    WebSocket.Builder builder = client.newWebSocketBuilder(
            URI.create("ws://websocket.example.com"),
            listener);



 Finer control over the WebSocket Opening Handshake can be achieved by using a custom HttpClient. 
 Example


    InetSocketAddress addr = new InetSocketAddress("proxy.example.com", 80);
    HttpClient client = HttpClient.newBuilder()
            .proxy(ProxySelector.of(addr))
            .build();
    WebSocket.Builder builder = client.newWebSocketBuilder(
            URI.create("ws://websocket.example.com"),
            listener);



Params:
  • uri – 
        the WebSocket URI
  • listener – 
        the listener
Throws:
Implementation Requirements:The default implementation of this method throws 
UnsupportedOperationException. However, clients obtained through newHttpClient() or newBuilder() provide WebSocket capability.
Returns:a builder of WebSocket instances
/**
     * Creates a builder of {@link WebSocket} instances connected to the given
     * URI and receiving events and messages with the given {@code Listener}.
     *
     * <p> <b>Example</b>
     * <pre>{@code
     *     HttpClient client = HttpClient.newHttpClient();
     *     WebSocket.Builder builder = client.newWebSocketBuilder(
     *             URI.create("ws://websocket.example.com"),
     *             listener);
     * }</pre>
     *
     * <p> Finer control over the WebSocket Opening Handshake can be achieved
     * by using a custom {@code HttpClient}.
     *
     * <p> <b>Example</b>
     * <pre>{@code
     *     InetSocketAddress addr = new InetSocketAddress("proxy.example.com", 80);
     *     HttpClient client = HttpClient.newBuilder()
     *             .proxy(ProxySelector.of(addr))
     *             .build();
     *     WebSocket.Builder builder = client.newWebSocketBuilder(
     *             URI.create("ws://websocket.example.com"),
     *             listener);
     * }</pre>
     *
     * @implSpec The default implementation of this method throws {@code
     * UnsupportedOperationException}. However, clients obtained through
     * {@link HttpClient#newHttpClient()} or {@link HttpClient#newBuilder()}
     * provide WebSocket capability.
     *
     * @param uri
     *         the WebSocket URI
     * @param listener
     *         the listener
     *
     * @return a builder of {@code WebSocket} instances
     * @throws UnsupportedOperationException
     *         if this {@code HttpClient} does not provide WebSocket support
     */
    public WebSocket.Builder newWebSocketBuilder(URI uri,
                                                 WebSocket.Listener listener)
    {
        throw new UnsupportedOperationException();
    }
}