/*
* 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.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 java.util.concurrent.Executors;
import java.util.concurrent.ThreadFactory;
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}.
*
* <p> If this method is not invoked before {@linkplain #build() build},
* then the {@link SSLContext#getDefault() default context} 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 has been installed
* and it denies {@linkplain java.net.NetPermission}
* ({@code "setSSLContext"})
*/
public abstract Builder sslContext(SSLContext sslContext);
/**
* Sets an {@code SSLParameters}.
*
* <p> If this method is not invoked before {@linkplain #build() build},
* then a default, implementation specific, set of parameters are used.
*
* <p> Some parameters which are used internally by the HTTP Client
* implementation (such as the application protocol list) should not be
* set by callers, as they may be ignored. The contents of the given
* object are copied.
*
* @param sslParameters the SSLParameters
* @return this builder
*/
public abstract Builder sslParameters(SSLParameters sslParameters);
/**
* Sets the executor to be used for asynchronous and dependent tasks.
*
* <p> If this method is not invoked before {@linkplain #build() build},
* a default executor is created for each newly built {@code HttpClient}.
* The default executor uses a {@linkplain
* Executors#newCachedThreadPool(ThreadFactory) cached thread pool}, with
* a custom thread factory.
*
* @implNote If a security manager has been installed, the thread
* factory creates threads that run with an access control context that
* has no permissions.
*
* @param executor the Executor
* @return this builder
*/
public abstract Builder executor(Executor executor);
/**
* Specifies whether requests will automatically follow redirects issued
* by the server. The default redirection policy for clients built by
* this builder, if this method has not been invoked, 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}.
*
* @implNote {@link ProxySelector#of(InetSocketAddress)}
* provides a {@code ProxySelector} which uses a single proxy for all
* requests. The system-wide proxy selector can be retrieved by
* {@link ProxySelector#getDefault()}.
*
* @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} containing 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 policy for this client. The default value
* for client's built by builders that do not specify a redirect policy is
* {@link HttpClient.Redirect#NEVER NEVER}.
*
* @return this client's follow redirects setting
*/
public abstract Redirect followRedirects();
/**
* Returns an {@code Optional} containing this client's {@code ProxySelector}.
* If no proxy selector was set in this client's builder, then the {@code
* Optional} is empty.
*
* @return an {@code Optional} containing this client's proxy selector
*/
public abstract Optional<ProxySelector> proxy();
/**
* Returns this client's {@code SSLContext}.
*
* <p> If no {@code SSLContext} was set in this client's builder, then the
* {@linkplain SSLContext#getDefault() default context} is returned.
*
* @return this client's SSLContext
* @throws SecurityException if a security manager has been installed
* and it denies {@linkplain java.net.NetPermission}
* ({@code "getSSLContext"})
*/
public abstract SSLContext sslContext();
/**
* Returns a copy of this client's {@link SSLParameters}.
*
* <p> If no {@code SSLParameters} were set in the client's builder, then an
* implementation specific default set of parameters, that the client will
* use, is returned.
*
* @return this client's {@code SSLParameters}
*/
public abstract 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 an {@code Optional} containing this client's {@linkplain
* Executor}. If no {@code Executor} was set in the client's builder,
* then the {@code Optional} is empty.
*
* <p> Even though this method may return an empty optional, the {@code
* HttpClient} may still have an non-exposed {@linkplain
* HttpClient.Builder#executor(Executor) default executor} that is used for
* executing asynchronous and dependent tasks.
*
* @return an {@code Optional} containing this client's {@code Executor}
*/
public abstract Optional<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 InterruptedException if the operation is interrupted
* @throws IllegalArgumentException if the request method is not supported
* @throws SecurityException If a security manager has been installed
* and it denies {@link java.net.URLPermission access} to the
* URL in the given request, or proxy if one is configured.
* See HttpRequest for further information about
* <a href="HttpRequest.html#securitychecks">security checks</a>.
*/
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.
*
* <p> The returned completable future is completed with a SecurityException
* if a security manager has been installed and it denies {@link
* java.net.URLPermission access} to the URI in the given request, or proxy
* if one is configured. See HttpRequest for further information about
* <a href="HttpRequest.html#securitychecks">security checks</a>.
*
* @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.
*
* <p> The returned completable future is completed with a SecurityException
* if a security manager has been installed and it denies {@link
* java.net.URLPermission access} to the URI in the given request, or proxy
* if one is configured. See HttpRequest for further information about
* <a href="HttpRequest.html#securitychecks">security checks</a>.
*
* @param <U> a type representing the aggregated results
* @param <T> a type representing all of the response bodies
* @param req the request
* @param multiSubscriber the multiSubscriber for the request
* @return a {@code CompletableFuture<U>}
*/
public abstract <U, T> CompletableFuture<U>
sendAsync(HttpRequest req, HttpResponse.MultiSubscriber<U, T> multiSubscriber);
/**
* 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
* @throws IllegalArgumentException if the given URI is not a valid WebSocket URI
*/
public WebSocket.Builder newWebSocketBuilder(URI uri,
WebSocket.Listener listener)
{
throw new UnsupportedOperationException();
}
}