public class HttpClient extends Object
HttpClient is used to send requests to servers and receive responses. For example
HttpClient client = new HttpClient();
HttpRequest request = HttpRequest.toGet("https://example.com");
Async<HttpResponse> asyncRes = client.send( request );
// or more conveniently
Async<HttpResponse> asyncRes = client.doGet( "https://example.com" );
Configuration is done by HttpClientConf, for example
HttpClient client = new HttpClientConf()
.proxy("127.0.0.1", 8080)
.trafficDump(System.err::print)
...
.newClient();
An HttpClient should be closed eventually.
| Constructor and Description |
|---|
HttpClient()
Create an HttpClient with default configurations.
|
HttpClient(HttpClientConf conf)
Create an HttpClient with the configuration.
|
| Instance Methods | |
|---|---|
Async<HttpResponse> |
doGet(String absoluteUri)
Send a GET request.
|
Async<HttpResponse> |
send(HttpRequest request)
Send a request and wait for the final response.
|
Async<HttpResponse> |
send0(HttpRequest request,
TcpAddress dest)
Send a request to `dest`.
|
Async<HttpClientConnection> |
newConnection(TcpAddress dest)
Create a new HTTP connection to `dest` address.
|
List<Executor> |
getExecutors()
Get executors associated with selector threads.
|
Async<Void> |
close()
Close this client and free resources.
|
public HttpClient()
Equivalent to new HttpClient( new HttpClientConf() ) .
public HttpClient(HttpClientConf conf)
A copy of `conf` is created and used by this client; further changes to `conf` will not affect this client.
conf.newClient()public Async<HttpResponse> doGet(String absoluteUri)
public Async<HttpResponse> send(HttpRequest request)
Requests/responses may be modified/transformed to handle cookies, decompression, etc.
Multiple request-response trips may occur during send(request)
to handle redirection, authentication, etc.
If the request could be re-sent in this process, e.g. due to authentication challenge, its entity should be sharable.
See also send0().
This method eventually calls send0(),
possibly multiple times.
Notes: (for both send() and send0() methods)
The response will tie up an underlying connection
if response.entity!=null;
the caller MUST eventually close() the entity body to free the connection.
Note that convenience methods
response.bodyBytes() and
response.bodyString()
will close the response entity body.
The response entity is not sharable; its body can be read only once.
Intermediary 1xx responses will be handled internally; the response returned by send() or send0() has a non-1xx status.
If the request contains a body (e.g. a POST request),
the request entity should has a known contentLength.
Otherwise, the request body will be sent in "Transfer-Encoding: chunked"
which is not supported by many servers.
"CONNECT" requests are not supported; the behavior would be undefined.
public Async<HttpResponse> send0(HttpRequest request, TcpAddress dest)
If `dest` is null
proxy is configured,
the request will be sent to the proxy
host()
This is a lower level API that sends the request and receives the response as-is, without any automatic handling of redirection, decompression, etc.
The connection will go through tunnles
if they are configured for this client.
public Async<HttpClientConnection> newConnection(TcpAddress dest)
If `dest` is null, a proxy must be configured,
and the connection will connect to the proxy address.
The connection will go through tunnles
if they are configured for this client.
This is a very low level API, see HttpClientConnection.
The caller is responsible for the life cycle of the connection.
public List<Executor> getExecutors()
Return one executor for every selector thread; see HttpClientConf.selectorIds(int...).
The executor can be used to execute non-blocking tasks on the selector thread; tasks will be executed sequentially in the order they are submitted.
public Async<Void> close()
All connections will be forcefully closed,
including those created by newConnection().
All outstanding requests and responses will be aborted.