@ManagedObject(value="The HTTP client") public class HttpClient extends ContainerLifeCycle
HttpClient
provides an efficient, asynchronous, non-blocking implementation
to perform HTTP requests to a server through a simple API that offers also blocking semantic.
HttpClient
provides easy-to-use methods such as GET(String)
that allow to perform HTTP
requests in a one-liner, but also gives the ability to fine tune the configuration of requests via
newRequest(URI)
.
HttpClient
acts as a central configuration point for network parameters (such as idle timeouts)
and HTTP parameters (such as whether to follow redirects).
HttpClient
transparently pools connections to servers, but allows direct control of connections
for cases where this is needed.
HttpClient
also acts as a central configuration point for cookies, via getCookieStore()
.
Typical usage:
HttpClient httpClient = new HttpClient(); httpClient.start(); // One liner: httpClient.GET("http://localhost:8080/").getStatus(); // Building a request with a timeout ContentResponse response = httpClient.newRequest("http://localhost:8080") .timeout(5, TimeUnit.SECONDS) .send(); int status = response.status(); // Asynchronously httpClient.newRequest("http://localhost:8080").send(new Response.CompleteListener() { @Override public void onComplete(Result result) { ... } });
AbstractLifeCycle.AbstractLifeCycleListener
Container.InheritedListener, Container.Listener
LifeCycle.Listener
Constructor and Description |
---|
HttpClient()
Creates a
HttpClient instance that can perform requests to non-TLS destinations only
(that is, requests with the "http" scheme only, and not "https"). |
HttpClient(HttpClientTransport transport,
SslContextFactory sslContextFactory) |
HttpClient(SslContextFactory sslContextFactory)
Creates a
HttpClient instance that can perform requests to non-TLS and TLS destinations
(that is, both requests with the "http" scheme and with the "https" scheme). |
Modifier and Type | Method and Description |
---|---|
void |
dump(Appendable out,
String indent)
Dump this object (and children) into an Appendable using the provided indent after any new lines.
|
ContentResponse |
FORM(String uri,
Fields fields)
Performs a POST request to the specified URI with the given form parameters.
|
ContentResponse |
FORM(URI uri,
Fields fields)
Performs a POST request to the specified URI with the given form parameters.
|
ContentResponse |
GET(String uri)
Performs a GET request to the specified URI.
|
ContentResponse |
GET(URI uri)
Performs a GET request to the specified URI.
|
long |
getAddressResolutionTimeout() |
AuthenticationStore |
getAuthenticationStore() |
SocketAddress |
getBindAddress() |
ByteBufferPool |
getByteBufferPool() |
long |
getConnectTimeout() |
Set<ContentDecoder.Factory> |
getContentDecoderFactories()
Returns a non thread-safe set of
ContentDecoder.Factory s that can be modified before
performing requests. |
CookieStore |
getCookieStore() |
String |
getDefaultRequestContentType() |
Destination |
getDestination(String scheme,
String host,
int port)
Returns a
Destination for the given scheme, host and port. |
List<Destination> |
getDestinations() |
Executor |
getExecutor() |
HttpCompliance |
getHttpCompliance()
Gets the http compliance mode for parsing http responses.
|
long |
getIdleTimeout() |
int |
getMaxConnectionsPerDestination() |
int |
getMaxRedirects() |
int |
getMaxRequestsQueuedPerDestination() |
String |
getName() |
ProtocolHandlers |
getProtocolHandlers() |
ProxyConfiguration |
getProxyConfiguration() |
int |
getRequestBufferSize() |
List<Request.Listener> |
getRequestListeners()
Returns a non thread-safe list of
Request.Listener s that can be modified before
performing requests. |
int |
getResponseBufferSize() |
Scheduler |
getScheduler() |
SocketAddressResolver |
getSocketAddressResolver() |
SslContextFactory |
getSslContextFactory() |
HttpClientTransport |
getTransport() |
HttpField |
getUserAgentField() |
boolean |
isConnectBlocking() |
boolean |
isDefaultPort(String scheme,
int port) |
boolean |
isDispatchIO()
Deprecated.
|
boolean |
isFollowRedirects() |
boolean |
isRemoveIdleDestinations() |
boolean |
isStrictEventOrdering() |
boolean |
isTCPNoDelay() |
Request |
newRequest(String uri)
Creates a new request with the specified absolute URI in string format.
|
Request |
newRequest(String host,
int port)
Creates a new request with the "http" scheme and the specified host and port
|
Request |
newRequest(URI uri)
Creates a new request with the specified absolute URI.
|
static int |
normalizePort(String scheme,
int port) |
Request |
POST(String uri)
Creates a POST request to the specified URI.
|
Request |
POST(URI uri)
Creates a POST request to the specified URI.
|
void |
setAddressResolutionTimeout(long addressResolutionTimeout)
Sets the socket address resolution timeout used by the default
SocketAddressResolver
created by this HttpClient at startup. |
void |
setAuthenticationStore(AuthenticationStore authenticationStore) |
void |
setBindAddress(SocketAddress bindAddress) |
void |
setByteBufferPool(ByteBufferPool byteBufferPool) |
void |
setConnectBlocking(boolean connectBlocking)
Whether
connect() operations are performed in blocking mode. |
void |
setConnectTimeout(long connectTimeout) |
void |
setCookieStore(CookieStore cookieStore) |
void |
setDefaultRequestContentType(String contentType) |
void |
setDispatchIO(boolean dispatchIO)
Deprecated.
|
void |
setExecutor(Executor executor) |
void |
setFollowRedirects(boolean follow) |
void |
setHttpCompliance(HttpCompliance httpCompliance)
Sets the http compliance mode for parsing http responses.
|
void |
setIdleTimeout(long idleTimeout) |
void |
setMaxConnectionsPerDestination(int maxConnectionsPerDestination)
Sets the max number of connections to open to each destinations.
|
void |
setMaxRedirects(int maxRedirects) |
void |
setMaxRequestsQueuedPerDestination(int maxRequestsQueuedPerDestination)
Sets the max number of requests that may be queued to a destination.
|
void |
setName(String name)
Sets the name of this HttpClient.
|
void |
setRemoveIdleDestinations(boolean removeIdleDestinations)
Whether destinations that have no connections (nor active nor idle) should be removed.
|
void |
setRequestBufferSize(int requestBufferSize) |
void |
setResponseBufferSize(int responseBufferSize) |
void |
setScheduler(Scheduler scheduler) |
void |
setSocketAddressResolver(SocketAddressResolver resolver) |
void |
setStrictEventOrdering(boolean strictEventOrdering)
Whether request/response events must be strictly ordered with respect to connection usage.
|
void |
setTCPNoDelay(boolean tcpNoDelay) |
void |
setUserAgentField(HttpField agent) |
addBean, addBean, addEventListener, addManaged, contains, destroy, dump, dump, dump, dump, dumpObject, dumpStdErr, getBean, getBeans, getBeans, getContainedBeans, isAuto, isManaged, isUnmanaged, manage, removeBean, removeBeans, removeEventListener, setBeans, setStopTimeout, unmanage, updateBean, updateBean, updateBeans
addLifeCycleListener, getState, getState, getStopTimeout, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop, toString
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
dumpContainer, dumpIterable, dumpMapEntries, dumpObjects, dumpSelf, named
public HttpClient()
HttpClient
instance that can perform requests to non-TLS destinations only
(that is, requests with the "http" scheme only, and not "https").to perform requests to TLS destinations.
public HttpClient(SslContextFactory sslContextFactory)
HttpClient
instance that can perform requests to non-TLS and TLS destinations
(that is, both requests with the "http" scheme and with the "https" scheme).sslContextFactory
- the SslContextFactory
that manages TLS encryptiongetSslContextFactory()
public HttpClient(HttpClientTransport transport, SslContextFactory sslContextFactory)
public void dump(Appendable out, String indent) throws IOException
Dumpable
dump
in interface Dumpable
dump
in class ContainerLifeCycle
out
- The appendable to dump toindent
- The indent to apply after any new lines.IOException
- if unable to write to Appendablepublic HttpClientTransport getTransport()
public SslContextFactory getSslContextFactory()
SslContextFactory
that manages TLS encryptionHttpClient(SslContextFactory)
public List<Request.Listener> getRequestListeners()
Request.Listener
s that can be modified before
performing requests.Request.Listener
that can be used to add and remove listenerspublic CookieStore getCookieStore()
public void setCookieStore(CookieStore cookieStore)
cookieStore
- the cookie store associated with this instancepublic AuthenticationStore getAuthenticationStore()
public void setAuthenticationStore(AuthenticationStore authenticationStore)
authenticationStore
- the authentication store associated with this instancepublic Set<ContentDecoder.Factory> getContentDecoderFactories()
ContentDecoder.Factory
s that can be modified before
performing requests.ContentDecoder.Factory
that can be used to add and remove content decoder factoriespublic ContentResponse GET(String uri) throws InterruptedException, ExecutionException, TimeoutException
uri
- the URI to GETContentResponse
for the requestInterruptedException
- if send threading has been interruptedExecutionException
- the execution failedTimeoutException
- the send timed outGET(URI)
public ContentResponse GET(URI uri) throws InterruptedException, ExecutionException, TimeoutException
uri
- the URI to GETContentResponse
for the requestInterruptedException
- if send threading has been interruptedExecutionException
- the execution failedTimeoutException
- the send timed outnewRequest(URI)
public ContentResponse FORM(String uri, Fields fields) throws InterruptedException, ExecutionException, TimeoutException
uri
- the URI to POSTfields
- the fields composing the form name/value pairsContentResponse
for the requestInterruptedException
- if send threading has been interruptedExecutionException
- the execution failedTimeoutException
- the send timed outpublic ContentResponse FORM(URI uri, Fields fields) throws InterruptedException, ExecutionException, TimeoutException
uri
- the URI to POSTfields
- the fields composing the form name/value pairsContentResponse
for the requestInterruptedException
- if send threading has been interruptedExecutionException
- the execution failedTimeoutException
- the send timed outpublic Request POST(String uri)
uri
- the URI to POST toPOST(URI)
public Request POST(URI uri)
uri
- the URI to POST topublic Request newRequest(String host, int port)
host
- the request hostport
- the request portpublic Request newRequest(String uri)
uri
- the request absolute URIpublic Request newRequest(URI uri)
uri
- the request absolute URIpublic Destination getDestination(String scheme, String host, int port)
Destination
for the given scheme, host and port.
Applications may use Destination
s to create Connection
s
that will be outside HttpClient
's pooling mechanism, to explicitly
control the connection lifecycle (in particular their termination with
Connection.close()
).scheme
- the destination schemehost
- the destination hostport
- the destination portgetDestinations()
public List<Destination> getDestinations()
HttpClient
.public ProtocolHandlers getProtocolHandlers()
public ByteBufferPool getByteBufferPool()
ByteBufferPool
of this HttpClient
public void setByteBufferPool(ByteBufferPool byteBufferPool)
byteBufferPool
- the ByteBufferPool
of this HttpClient
@ManagedAttribute(value="The name of this HttpClient") public String getName()
public void setName(String name)
Sets the name of this HttpClient.
The name is also used to generate the JMX ObjectName of this HttpClient and must be set before the registration of the HttpClient MBean in the MBeanServer.
name
- the name of this HttpClient@ManagedAttribute(value="The timeout, in milliseconds, for connect() operations") public long getConnectTimeout()
public void setConnectTimeout(long connectTimeout)
connectTimeout
- the max time, in milliseconds, a connection can take to connect to destinationsSocket.connect(SocketAddress, int)
public long getAddressResolutionTimeout()
SocketAddressResolver
created at startupgetSocketAddressResolver()
public void setAddressResolutionTimeout(long addressResolutionTimeout)
Sets the socket address resolution timeout used by the default SocketAddressResolver
created by this HttpClient
at startup.
For more fine tuned configuration of socket address resolution, see
setSocketAddressResolver(SocketAddressResolver)
.
addressResolutionTimeout
- the timeout, in milliseconds, for the default SocketAddressResolver
created at startupsetSocketAddressResolver(SocketAddressResolver)
@ManagedAttribute(value="The timeout, in milliseconds, to close idle connections") public long getIdleTimeout()
public void setIdleTimeout(long idleTimeout)
idleTimeout
- the max time, in milliseconds, a connection can be idle (that is, without traffic of bytes in either direction)public SocketAddress getBindAddress()
setBindAddress(SocketAddress)
public void setBindAddress(SocketAddress bindAddress)
bindAddress
- the address to bind socket channels togetBindAddress()
,
SocketChannel.bind(SocketAddress)
public HttpField getUserAgentField()
HttpClient
public void setUserAgentField(HttpField agent)
agent
- the "User-Agent" HTTP header string of this HttpClient
@ManagedAttribute(value="Whether HTTP redirects are followed") public boolean isFollowRedirects()
HttpClient
follows HTTP redirectsRequest.isFollowRedirects()
public void setFollowRedirects(boolean follow)
follow
- whether this HttpClient
follows HTTP redirectssetMaxRedirects(int)
public Executor getExecutor()
Executor
of this HttpClient
public void setExecutor(Executor executor)
executor
- the Executor
of this HttpClient
public Scheduler getScheduler()
Scheduler
of this HttpClient
public void setScheduler(Scheduler scheduler)
scheduler
- the Scheduler
of this HttpClient
public SocketAddressResolver getSocketAddressResolver()
SocketAddressResolver
of this HttpClient
public void setSocketAddressResolver(SocketAddressResolver resolver)
resolver
- the SocketAddressResolver
of this HttpClient
@ManagedAttribute(value="The max number of connections per each destination") public int getMaxConnectionsPerDestination()
HttpClient
opens to Destination
spublic void setMaxConnectionsPerDestination(int maxConnectionsPerDestination)
RFC 2616 suggests that 2 connections should be opened per each destination,
but browsers commonly open 6.
If this HttpClient
is used for load testing, it is common to have only one destination
(the server to load test), and it is recommended to set this value to a high value (at least as
much as the threads present in the executor
).
maxConnectionsPerDestination
- the max number of connections that this HttpClient
opens to Destination
s@ManagedAttribute(value="The max number of requests queued per each destination") public int getMaxRequestsQueuedPerDestination()
Destination
.public void setMaxRequestsQueuedPerDestination(int maxRequestsQueuedPerDestination)
If this HttpClient
performs a high rate of requests to a destination,
and all the connections managed by that destination are busy with other requests,
then new requests will be queued up in the destination.
This parameter controls how many requests can be queued before starting to reject them.
If this HttpClient
is used for load testing, it is common to have this parameter
set to a high value, although this may impact latency (requests sit in the queue for a long
time before being sent).
maxRequestsQueuedPerDestination
- the max number of requests that may be queued to a Destination
.@ManagedAttribute(value="The request buffer size") public int getRequestBufferSize()
public void setRequestBufferSize(int requestBufferSize)
requestBufferSize
- the size of the buffer used to write requests@ManagedAttribute(value="The response buffer size") public int getResponseBufferSize()
public void setResponseBufferSize(int responseBufferSize)
responseBufferSize
- the size of the buffer used to read responsespublic int getMaxRedirects()
setMaxRedirects(int)
public void setMaxRedirects(int maxRedirects)
maxRedirects
- the max number of HTTP redirects that are followed in a conversation, or -1 for unlimited redirectssetFollowRedirects(boolean)
@ManagedAttribute(value="Whether the TCP_NODELAY option is enabled", name="tcpNoDelay") public boolean isTCPNoDelay()
public void setTCPNoDelay(boolean tcpNoDelay)
tcpNoDelay
- whether TCP_NODELAY is enabledSocket.setTcpNoDelay(boolean)
@Deprecated public boolean isDispatchIO()
setDispatchIO(boolean)
@Deprecated public void setDispatchIO(boolean dispatchIO)
This implementation never blocks on I/O operation, but invokes application callbacks that may
take time to execute or block on other I/O.
If application callbacks are known to take time or block on I/O, then parameter dispatchIO
should be set to true.
If application callbacks are known to be quick and never block on I/O, then parameter dispatchIO
may be set to false.
dispatchIO
- true to dispatch I/O operations in a different thread,
false to execute them in the selector threadpublic HttpCompliance getHttpCompliance()
HttpCompliance.RFC7230
which is the latest HTTP/1.1 specificationpublic void setHttpCompliance(HttpCompliance httpCompliance)
HttpParser
parses http responses and which http protocol level is supportedhttpCompliance
- The compliance level which is used to actually parse http responses@ManagedAttribute(value="Whether request/response events must be strictly ordered") public boolean isStrictEventOrdering()
setStrictEventOrdering(boolean)
public void setStrictEventOrdering(boolean strictEventOrdering)
From the point of view of connection usage, the connection can be reused just before the
"complete" event notified to Response.CompleteListener
s
(but after the "success" event).
When a request/response exchange is completing, the destination may have another request queued to be sent to the server. If the connection for that destination is reused for the second request before the "complete" event of the first exchange, it may happen that the "begin" event of the second request happens before the "complete" event of the first exchange.
Enforcing strict ordering of events so that a "begin" event of a request can never happen before the "complete" event of the previous exchange comes with the cost of increased connection usage. In case of HTTP redirects and strict event ordering, for example, the redirect request will be forced to open a new connection because it is typically sent from the complete listener when the connection cannot yet be reused. When strict event ordering is not enforced, the redirect request will reuse the already open connection making the system more efficient.
The default value for this property is false
.
strictEventOrdering
- whether request/response events must be strictly ordered@ManagedAttribute(value="Whether idle destinations are removed") public boolean isRemoveIdleDestinations()
setRemoveIdleDestinations(boolean)
public void setRemoveIdleDestinations(boolean removeIdleDestinations)
Applications typically make request to a limited number of destinations so keeping destinations around is not a problem for the memory or the GC. However, for applications that hit millions of different destinations (e.g. a spider bot) it would be useful to be able to remove the old destinations that won't be visited anymore and leave space for new destinations.
removeIdleDestinations
- whether destinations that have no connections should be removedDuplexConnectionPool
@ManagedAttribute(value="Whether the connect() operation is blocking") public boolean isConnectBlocking()
connect()
operations are performed in blocking modepublic void setConnectBlocking(boolean connectBlocking)
Whether connect()
operations are performed in blocking mode.
If connect()
are performed in blocking mode, then Socket.connect(SocketAddress, int)
will be used to connect to servers.
Otherwise, SocketChannel.connect(SocketAddress)
will be used in non-blocking mode,
therefore registering for SelectionKey.OP_CONNECT
and finishing the connect operation
when the NIO system emits that event.
connectBlocking
- whether connect()
operations are performed in blocking mode@ManagedAttribute(value="The default content type for request content") public String getDefaultRequestContentType()
public void setDefaultRequestContentType(String contentType)
contentType
- the default content type for request contentpublic ProxyConfiguration getProxyConfiguration()
public static int normalizePort(String scheme, int port)
public boolean isDefaultPort(String scheme, int port)
Copyright © 2010 - 2020 Adobe. All Rights Reserved