--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpClient.java Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,429 @@
+/*
+ * 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 {@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.
+ */
+ protected HttpClient() {}
+
+ /**
+ * Returns a new HttpClient with default settings.
+ *
+ * @return a new HttpClient
+ */
+ public static HttpClient newHttpClient() {
+ return new HttpClientBuilderImpl().build();
+ }
+
+ /**
+ * Creates a new {@code HttpClient} builder.
+ *
+ * @return a {@code HttpClient.Builder}
+ */
+ public static Builder newBuilder() {
+ return new HttpClientBuilderImpl();
+ }
+
+ /**
+ * 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.
+ *
+ * @param cookieManager the cookie manager
+ * @return this builder
+ */
+ public abstract Builder cookieManager(CookieManager cookieManager);
+
+ /**
+ * 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 {@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 {@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 {@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 {@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 {@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 {@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.
+ *
+ * @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 {@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 {@link HttpClient.Redirect#NEVER}
+ *
+ * @return this client's follow redirects setting
+ */
+ public abstract Redirect followRedirects();
+
+ /**
+ * 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 {@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 {@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 {@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 {@link HttpClient.Version#HTTP_2}
+ *
+ * @return the HTTP protocol version requested
+ */
+ public abstract HttpClient.Version version();
+
+ /**
+ * 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
+ */
+ public enum Version {
+
+ /**
+ * HTTP version 1.1
+ */
+ HTTP_1_1,
+
+ /**
+ * HTTP version 2
+ */
+ HTTP_2
+ }
+
+ /**
+ * 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,
+
+ /**
+ * 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
+ }
+
+ /**
+ * 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.
+ *
+ * @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.
+ *
+ * @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 {@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();
+ }
+}