/*
* 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}.
*
* <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() }
*
* <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_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
*
* @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_1_1}
*
* @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.
*
* @since 9
*/
public enum Version {
/**
* HTTP version 1.1
*/
HTTP_1_1,
/**
* HTTP version 2
*/
HTTP_2
}
/**
* Defines automatic redirection policy. 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();
}
}