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

Modifier and Type	Class and Description
protected class	HttpClient.ClientSelectorManager

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(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 String	address(String scheme, String host, int port)
protected void	configure(SocketChannel channel)
protected Request	copyRequest(Request 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	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.
protected HttpConversation	getConversation(long id, boolean create)
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()
protected SelectorManager	getSelectorManager()
SslContextFactory	getSslContextFactory()
HttpField	getUserAgentField()
protected boolean	isDefaultPort(String scheme, int port)
boolean	isDispatchIO()
boolean	isFollowRedirects()
boolean	isTCPNoDelay()
protected void	newConnection(HttpDestination destination, Promise<Connection> promise)
protected HttpConnection	newHttpConnection(HttpClient httpClient, EndPoint endPoint, HttpDestination destination)
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 SelectorManager	newSelectorManager()
protected SslConnection	newSslConnection(HttpClient httpClient, EndPoint endPoint, SSLEngine engine)
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 void	removeConversation(HttpConversation conversation)
protected void	send(Request 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	setProxyConfiguration(ProxyConfiguration proxyConfig)
void	setRequestBufferSize(int requestBufferSize)
void	setResponseBufferSize(int responseBufferSize)
void	setScheduler(Scheduler scheduler)
void	setTCPNoDelay(boolean tcpNoDelay)
void	setUserAgentField(HttpField agent)

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

addBean, addBean, addBean, contains, destroy, dump, dump, dump, dump, dumpBeans, dumpObject, dumpStdErr, dumpThis, getBean, getBeans, getBeans, isManaged, manage, removeBean, removeBeans, setBeans, setStopTimeout, start, 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()

Method Detail

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

newSelectorManager

protected SelectorManager newSelectorManager()

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)

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(Request oldRequest,
                  URI newURI)

address

protected String address(String scheme,
             String host,
             int port)

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)

getDestinations

public List<Destination> getDestinations()

Returns:

the list of destinations known to this HttpClient.

send

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

newConnection

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

configure

protected void configure(SocketChannel channel)
                  throws SocketException

Throws:

SocketException

getConversation

protected HttpConversation getConversation(long id,
                               boolean create)

removeConversation

protected void removeConversation(HttpConversation conversation)

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 a connection can take to connect to destinations

setConnectTimeout

public void setConnectTimeout(long connectTimeout)

Parameters:

connectTimeout - the max time 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 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 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

getSelectorManager

protected SelectorManager getSelectorManager()

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

getProxyConfiguration

public ProxyConfiguration getProxyConfiguration()

Returns:

the forward proxy configuration

setProxyConfiguration

public void setProxyConfiguration(ProxyConfiguration proxyConfig)

Parameters:

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

newHttpConnection

protected HttpConnection newHttpConnection(HttpClient httpClient,
                               EndPoint endPoint,
                               HttpDestination destination)

newSslConnection

protected SslConnection newSslConnection(HttpClient httpClient,
                             EndPoint endPoint,
                             SSLEngine engine)

dump

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

Specified by:

dump in interface Dumpable

Overrides:

dump in class ContainerLifeCycle

Throws:

IOException