org.eclipse.jetty.client

Class HttpClient

java.lang.Object

org.eclipse.jetty.util.component.AbstractLifeCycle

org.eclipse.jetty.util.component.ContainerLifeCycle

org.eclipse.jetty.client.HttpClient

All Implemented Interfaces:

Container, Destroyable, Dumpable, LifeCycle

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/").get().status();

 // Building a request with a timeout
 Response response = httpClient.newRequest("http://localhost:8080").send().get(5, TimeUnit.SECONDS);
 int status = response.status();

 // Asynchronously
 httpClient.newRequest("http://localhost:8080").send(new Response.CompleteListener()
 {
     @Override
     public void onComplete(Result result)
     {
         ...
     }
 });
 

Nested Class Summary

Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

AbstractLifeCycle.AbstractLifeCycleListener

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.Container

Container.InheritedListener, Container.Listener

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

LifeCycle.Listener

Field Summary

Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

FAILED, RUNNING, STARTED, STARTING, STOPPED, STOPPING

Constructor Summary

Constructors

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).

Method Summary

Methods

Modifier and Type	Method and Description
protected Request	copyRequest(HttpRequest oldRequest, URI newURI)
protected HttpDestination	destinationFor(String scheme, String host, int port)
protected void	doStart() Starts the managed lifecycle beans in the order they were added.
protected void	doStop() Stops the managed lifecycle beans in the reverse order they were added.
void	dump(Appendable out, String indent)
protected ProtocolHandler	findProtocolHandler(Request request, Response response)
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.
protected HttpField	getAcceptEncodingField()
long	getAddressResolutionTimeout()
AuthenticationStore	getAuthenticationStore()
SocketAddress	getBindAddress()
ByteBufferPool	getByteBufferPool()
long	getConnectTimeout()
Set<ContentDecoder.Factory>	getContentDecoderFactories() Returns a non thread-safe set of ContentDecoder.Factorys that can be modified before performing requests.
CookieStore	getCookieStore()
Destination	getDestination(String scheme, String host, int port) Returns a Destination for the given scheme, host and port.
List<Destination>	getDestinations()
Executor	getExecutor()
long	getIdleTimeout()
int	getMaxConnectionsPerDestination()
int	getMaxRedirects()
int	getMaxRequestsQueuedPerDestination()
protected List<ProtocolHandler>	getProtocolHandlers()
ProxyConfiguration	getProxyConfiguration()
int	getRequestBufferSize()
List<Request.Listener>	getRequestListeners() Returns a non thread-safe list of Request.Listeners that can be modified before performing requests.
int	getResponseBufferSize()
Scheduler	getScheduler()
SslContextFactory	getSslContextFactory()
HttpClientTransport	getTransport()
HttpField	getUserAgentField()
protected boolean	isDefaultPort(String scheme, int port)
boolean	isDispatchIO()
boolean	isFollowRedirects()
boolean	isRemoveIdleDestinations()
boolean	isStrictEventOrdering()
boolean	isTCPNoDelay()
protected void	newConnection(HttpDestination destination, Promise<Connection> promise)
protected HttpRequest	newHttpRequest(HttpConversation conversation, URI uri)
Request	newRequest(String uri) Creates a new request with the specified URI.
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 URI.
protected String	normalizeHost(String host)
protected 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.
protected boolean	removeDestination(HttpDestination destination)
protected void	send(HttpRequest request, List<Response.ResponseListener> listeners)
void	setAddressResolutionTimeout(long addressResolutionTimeout)
void	setBindAddress(SocketAddress bindAddress)
void	setByteBufferPool(ByteBufferPool byteBufferPool)
void	setConnectTimeout(long connectTimeout)
void	setCookieStore(CookieStore cookieStore)
void	setDispatchIO(boolean dispatchIO) Whether to dispatch I/O operations from the selector thread to a different thread.
void	setExecutor(Executor executor)
void	setFollowRedirects(boolean follow)
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	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	setStrictEventOrdering(boolean strictEventOrdering) Whether request/response events must be strictly ordered with respect to connection usage.
void	setTCPNoDelay(boolean tcpNoDelay)
void	setUserAgentField(HttpField agent)

Methods inherited from class org.eclipse.jetty.util.component.ContainerLifeCycle

addBean, addBean, addBean, addEventListener, addManaged, contains, destroy, dump, dump, dump, dump, dumpBeans, dumpObject, dumpStdErr, dumpThis, getBean, getBeans, getBeans, isManaged, manage, removeBean, removeBeans, removeEventListener, setBeans, setStopTimeout, start, stop, unmanage, updateBean, updateBeans

Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

addLifeCycleListener, getState, getState, getStopTimeout, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HttpClient

public 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").

See Also:

to perform requests to TLS destinations.

HttpClient

public 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).

Parameters:

sslContextFactory - the SslContextFactory that manages TLS encryption

See Also:

getSslContextFactory()

HttpClient

public HttpClient(HttpClientTransport transport,
          SslContextFactory sslContextFactory)

Method Detail

getTransport

public HttpClientTransport getTransport()

getSslContextFactory

public SslContextFactory getSslContextFactory()

Returns:

the SslContextFactory that manages TLS encryption

See Also:

HttpClient(SslContextFactory)

doStart

protected void doStart()
                throws Exception

Description copied from class: ContainerLifeCycle

Starts the managed lifecycle beans in the order they were added.

Overrides:

doStart in class ContainerLifeCycle

Throws:

Exception

doStop

protected void doStop()
               throws Exception

Description copied from class: ContainerLifeCycle

Stops the managed lifecycle beans in the reverse order they were added.

Overrides:

doStop in class ContainerLifeCycle

Throws:

Exception

getRequestListeners

public List<Request.Listener> getRequestListeners()

Returns a non thread-safe list of Request.Listeners that can be modified before performing requests.

Returns:

a list of Request.Listener that can be used to add and remove listeners

getCookieStore

public CookieStore getCookieStore()

Returns:

the cookie store associated with this instance

setCookieStore

public void setCookieStore(CookieStore cookieStore)

Parameters:

cookieStore - the cookie store associated with this instance

getAuthenticationStore

public AuthenticationStore getAuthenticationStore()

Returns:

the authentication store associated with this instance

getContentDecoderFactories

public Set<ContentDecoder.Factory> getContentDecoderFactories()

Returns a non thread-safe set of ContentDecoder.Factorys that can be modified before performing requests.

Returns:

a set of ContentDecoder.Factory that can be used to add and remove content decoder factories

GET

public ContentResponse GET(String uri)
                    throws InterruptedException,
                           ExecutionException,
                           TimeoutException

Performs a GET request to the specified URI.

Parameters:

uri - the URI to GET

Returns:

the ContentResponse for the request

Throws:

InterruptedException

ExecutionException

TimeoutException

See Also:

GET(URI)

GET

public ContentResponse GET(URI uri)
                    throws InterruptedException,
                           ExecutionException,
                           TimeoutException

Performs a GET request to the specified URI.

Parameters:

uri - the URI to GET

Returns:

the ContentResponse for the request

Throws:

InterruptedException

ExecutionException

TimeoutException

See Also:

newRequest(URI)

FORM

public ContentResponse FORM(String uri,
                   Fields fields)
                     throws InterruptedException,
                            ExecutionException,
                            TimeoutException

Performs a POST request to the specified URI with the given form parameters.

Parameters:

uri - the URI to POST

fields - the fields composing the form name/value pairs

Returns:

the ContentResponse for the request

Throws:

InterruptedException

ExecutionException

TimeoutException

FORM

public ContentResponse FORM(URI uri,
                   Fields fields)
                     throws InterruptedException,
                            ExecutionException,
                            TimeoutException

Performs a POST request to the specified URI with the given form parameters.

Parameters:

uri - the URI to POST

fields - the fields composing the form name/value pairs

Returns:

the ContentResponse for the request

Throws:

InterruptedException

ExecutionException

TimeoutException

POST

public Request POST(String uri)

Creates a POST request to the specified URI.

Parameters:

uri - the URI to POST to

Returns:

the POST request

See Also:

POST(URI)

POST

public Request POST(URI uri)

Creates a POST request to the specified URI.

Parameters:

uri - the URI to POST to

Returns:

the POST request

newRequest

public Request newRequest(String host,
                 int port)

Creates a new request with the "http" scheme and the specified host and port

Parameters:

host - the request host

port - the request port

Returns:

the request just created

newRequest

public Request newRequest(String uri)

Creates a new request with the specified URI.

Parameters:

uri - the URI to request

Returns:

the request just created

newRequest

public Request newRequest(URI uri)

Creates a new request with the specified URI.

Parameters:

uri - the URI to request

Returns:

the request just created

copyRequest

protected Request copyRequest(HttpRequest oldRequest,
                  URI newURI)

newHttpRequest

protected HttpRequest newHttpRequest(HttpConversation conversation,
                         URI uri)

getDestination

public Destination getDestination(String scheme,
                         String host,
                         int port)

Returns a Destination for the given scheme, host and port. Applications may use Destinations to create Connections that will be outside HttpClient's pooling mechanism, to explicitly control the connection lifecycle (in particular their termination with Connection.close()).

Parameters:

scheme - the destination scheme

host - the destination host

port - the destination port

Returns:

the destination

See Also:

getDestinations()

destinationFor

protected HttpDestination destinationFor(String scheme,
                             String host,
                             int port)

removeDestination

protected boolean removeDestination(HttpDestination destination)

getDestinations

public List<Destination> getDestinations()

Returns:

the list of destinations known to this HttpClient.

send

protected void send(HttpRequest request,
        List<Response.ResponseListener> listeners)

newConnection

protected void newConnection(HttpDestination destination,
                 Promise<Connection> promise)

getProtocolHandlers

protected List<ProtocolHandler> getProtocolHandlers()

findProtocolHandler

protected ProtocolHandler findProtocolHandler(Request request,
                                  Response response)

getByteBufferPool

public ByteBufferPool getByteBufferPool()

Returns:

the ByteBufferPool of this HttpClient

setByteBufferPool

public void setByteBufferPool(ByteBufferPool byteBufferPool)

Parameters:

byteBufferPool - the ByteBufferPool of this HttpClient

getConnectTimeout

public long getConnectTimeout()

Returns:

the max time, in milliseconds, a connection can take to connect to destinations

setConnectTimeout

public void setConnectTimeout(long connectTimeout)

Parameters:

connectTimeout - the max time, in milliseconds, a connection can take to connect to destinations

See Also:

Socket.connect(SocketAddress, int)

getAddressResolutionTimeout

public long getAddressResolutionTimeout()

Returns:

the timeout, in milliseconds, for the DNS resolution of host addresses

setAddressResolutionTimeout

public void setAddressResolutionTimeout(long addressResolutionTimeout)

Parameters:

addressResolutionTimeout - the timeout, in milliseconds, for the DNS resolution of host addresses

getIdleTimeout

public long getIdleTimeout()

Returns:

the max time, in milliseconds, a connection can be idle (that is, without traffic of bytes in either direction)

setIdleTimeout

public void setIdleTimeout(long idleTimeout)

Parameters:

idleTimeout - the max time, in milliseconds, a connection can be idle (that is, without traffic of bytes in either direction)

getBindAddress

public SocketAddress getBindAddress()

Returns:

the address to bind socket channels to

See Also:

setBindAddress(SocketAddress)

setBindAddress

public void setBindAddress(SocketAddress bindAddress)

Parameters:

bindAddress - the address to bind socket channels to

See Also:

getBindAddress(), SocketChannel#bind(SocketAddress)

getUserAgentField

public HttpField getUserAgentField()

Returns:

the "User-Agent" HTTP field of this HttpClient

setUserAgentField

public void setUserAgentField(HttpField agent)

Parameters:

agent - the "User-Agent" HTTP header string of this HttpClient

isFollowRedirects

public boolean isFollowRedirects()

Returns:

whether this HttpClient follows HTTP redirects

See Also:

Request.isFollowRedirects()

setFollowRedirects

public void setFollowRedirects(boolean follow)

Parameters:

follow - whether this HttpClient follows HTTP redirects

See Also:

setMaxRedirects(int)

getExecutor

public Executor getExecutor()

Returns:

the Executor of this HttpClient

setExecutor

public void setExecutor(Executor executor)

Parameters:

executor - the Executor of this HttpClient

getScheduler

public Scheduler getScheduler()

Returns:

the Scheduler of this HttpClient

setScheduler

public void setScheduler(Scheduler scheduler)

Parameters:

scheduler - the Scheduler of this HttpClient

getMaxConnectionsPerDestination

public int getMaxConnectionsPerDestination()

Returns:

the max number of connections that this HttpClient opens to Destinations

setMaxConnectionsPerDestination

public void setMaxConnectionsPerDestination(int maxConnectionsPerDestination)

Sets the max number of connections to open to each destinations.

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).

Parameters:

maxConnectionsPerDestination - the max number of connections that this HttpClient opens to Destinations

getMaxRequestsQueuedPerDestination

public int getMaxRequestsQueuedPerDestination()

Returns:

the max number of requests that may be queued to a Destination.

setMaxRequestsQueuedPerDestination

public void setMaxRequestsQueuedPerDestination(int maxRequestsQueuedPerDestination)

Sets the max number of requests that may be queued to a destination.

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).

Parameters:

maxRequestsQueuedPerDestination - the max number of requests that may be queued to a Destination.

getRequestBufferSize

public int getRequestBufferSize()

Returns:

the size of the buffer used to write requests

setRequestBufferSize

public void setRequestBufferSize(int requestBufferSize)

Parameters:

requestBufferSize - the size of the buffer used to write requests

getResponseBufferSize

public int getResponseBufferSize()

Returns:

the size of the buffer used to read responses

setResponseBufferSize

public void setResponseBufferSize(int responseBufferSize)

Parameters:

responseBufferSize - the size of the buffer used to read responses

getMaxRedirects

public int getMaxRedirects()

Returns:

the max number of HTTP redirects that are followed

See Also:

setMaxRedirects(int)

setMaxRedirects

public void setMaxRedirects(int maxRedirects)

Parameters:

maxRedirects - the max number of HTTP redirects that are followed

See Also:

setFollowRedirects(boolean)

isTCPNoDelay

public boolean isTCPNoDelay()

Returns:

whether TCP_NODELAY is enabled

setTCPNoDelay

public void setTCPNoDelay(boolean tcpNoDelay)

Parameters:

tcpNoDelay - whether TCP_NODELAY is enabled

See Also:

Socket.setTcpNoDelay(boolean)

isDispatchIO

public boolean isDispatchIO()

Returns:

true to dispatch I/O operations in a different thread, false to execute them in the selector thread

See Also:

setDispatchIO(boolean)

setDispatchIO

public void setDispatchIO(boolean dispatchIO)

Whether to dispatch I/O operations from the selector thread to a different thread.

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.

Parameters:

dispatchIO - true to dispatch I/O operations in a different thread, false to execute them in the selector thread

isStrictEventOrdering

public boolean isStrictEventOrdering()

Returns:

whether request events must be strictly ordered

See Also:

setStrictEventOrdering(boolean)

setStrictEventOrdering

public void setStrictEventOrdering(boolean strictEventOrdering)

Whether request/response events must be strictly ordered with respect to connection usage.

From the point of view of connection usage, the connection can be reused just before the "complete" event notified to Response.CompleteListeners (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.

Parameters:

strictEventOrdering - whether request/response events must be strictly ordered

isRemoveIdleDestinations

public boolean isRemoveIdleDestinations()

Returns:

whether destinations that have no connections should be removed

See Also:

setRemoveIdleDestinations(boolean)

setRemoveIdleDestinations

public void setRemoveIdleDestinations(boolean removeIdleDestinations)

Whether destinations that have no connections (nor active nor idle) should be removed.

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.

Parameters:

removeIdleDestinations - whether destinations that have no connections should be removed

See Also:

ConnectionPool

getProxyConfiguration

public ProxyConfiguration getProxyConfiguration()

Returns:

the forward proxy configuration

getAcceptEncodingField

protected HttpField getAcceptEncodingField()

normalizeHost

protected String normalizeHost(String host)

normalizePort

protected int normalizePort(String scheme,
                int port)

isDefaultPort

protected boolean isDefaultPort(String scheme,
                    int port)

dump

public void dump(Appendable out,
        String indent)
          throws IOException

Specified by:

dump in interface Dumpable

Overrides:

dump in class ContainerLifeCycle

Throws:

IOException