Package 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:
AutoCloseable, Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle
@ManagedObject("The HTTP client") public class HttpClient extends ContainerLifeCycle implements AutoCloseable

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

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(result ->
 {
     Response response = result.getResponse();
     ...
 });

  • Field Details

    • USER_AGENT

      public static final String USER_AGENT

  • Constructor Details

    • HttpClient

      public HttpClient()
      Creates a HttpClient instance that can perform HTTP/1.1 requests to non-TLS and TLS destinations.

    • HttpClient

      public HttpClient(HttpClientTransport transport)

  • Method Details

    • getTransport

      public HttpClientTransport getTransport()

    • getSslContextFactory

      public SslContextFactory.Client getSslContextFactory()
      Returns:
      the SslContextFactory.Client that manages TLS encryption

    • setSslContextFactory

      public void setSslContextFactory(SslContextFactory.Client sslContextFactory)
      Set the SslContextFactory.Client that manages TLS encryption.
      Parameters:
      sslContextFactory - the SslContextFactory.Client that manages TLS encryption

    • 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:
      AbstractLifeCycle.StopException - If thrown, the lifecycle will immediately be stopped.
      Exception - If there was a problem starting. Will cause a transition to FAILED state

    • 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 - If there was a problem stopping. Will cause a transition to FAILED state

    • getRequestListeners

      public RequestListeners getRequestListeners()
      Returns a non thread-safe container of Request.Listeners that allows to add request listeners before performing requests.
      Returns:
      a RequestListeners instance that can be used to add request listeners

    • getHttpCookieStore

      public HttpCookieStore getHttpCookieStore()
      Get the cookie store associated with this instance.
      Returns:
      the cookie store associated with this instance

    • setHttpCookieStore

      public void setHttpCookieStore(HttpCookieStore cookieStore)
      Set the cookie store associated with this instance.
      Parameters:
      cookieStore - the cookie store associated with this instance

    • putCookie

      public void putCookie(URI uri, HttpField field)

    • getAuthenticationStore

      public AuthenticationStore getAuthenticationStore()
      Get the authentication store associated with this instance.
      Returns:
      the authentication store associated with this instance

    • setAuthenticationStore

      public void setAuthenticationStore(AuthenticationStore authenticationStore)
      Set the authentication store associated with this instance.
      Parameters:
      authenticationStore - the authentication store associated with this instance

    • getContentDecoderFactories

      public ContentDecoder.Factories 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 - if send threading has been interrupted
      ExecutionException - the execution failed
      TimeoutException - the send timed out
      See Also:

    • 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 - if send threading has been interrupted
      ExecutionException - the execution failed
      TimeoutException - the send timed out
      See Also:

    • 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 - if send threading has been interrupted
      ExecutionException - the execution failed
      TimeoutException - the send timed out

    • 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 - if send threading has been interrupted
      ExecutionException - the execution failed
      TimeoutException - the send timed out

    • 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

      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 absolute URI in string format.
      Parameters:
      uri - the request absolute URI
      Returns:
      the request just created

    • newRequest

      public Request newRequest(URI uri)
      Creates a new request with the specified absolute URI.
      Parameters:
      uri - the request absolute URI
      Returns:
      the request just created

    • copyRequest

      protected Request copyRequest(Request oldRequest, URI newURI)

    • resolveDestination

      public Destination resolveDestination(Request request)

    • createOrigin

      public Origin createOrigin(Request request, Origin.Protocol protocol)

    • resolveDestination

      public Destination resolveDestination(Origin origin)

      Returns, creating it if absent, the destination with the given origin.

      Parameters:
      origin - the origin that identifies the destination
      Returns:
      the destination for the given origin

    • removeDestination

      public boolean removeDestination(Destination destination)

    • getDestinations

      public List<Destination> getDestinations()
      Returns:
      the list of destinations known to this HttpClient.

    • newConnection

      public void newConnection(Destination destination, Promise<Connection> promise)

    • getProtocolHandlers

      public ProtocolHandlers getProtocolHandlers()

    • findProtocolHandler

      public ProtocolHandler findProtocolHandler(Request request, Response response)

    • getByteBufferPool

      public ByteBufferPool getByteBufferPool()
      Get the ByteBufferPool of this HttpClient.
      Returns:
      the ByteBufferPool of this HttpClient

    • setByteBufferPool

      public void setByteBufferPool(ByteBufferPool byteBufferPool)
      Set the ByteBufferPool of this HttpClient.
      Parameters:
      byteBufferPool - the ByteBufferPool of this HttpClient

    • getName

      @ManagedAttribute("The name of this HttpClient") public String getName()
      Returns:
      the name of this HttpClient

    • setName

      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.

      Parameters:
      name - the name of this HttpClient

    • getConnectTimeout

      @ManagedAttribute("The timeout, in milliseconds, for connect() operations") public long getConnectTimeout()
      Returns:
      the max time, in milliseconds, a connection can take to connect to destinations. Zero value means infinite timeout.

    • setConnectTimeout

      public void setConnectTimeout(long connectTimeout)
      Parameters:
      connectTimeout - the max time, in milliseconds, a connection can take to connect to destinations. Zero value means infinite timeout.
      See Also:

    • getAddressResolutionTimeout

      public long getAddressResolutionTimeout()
      Returns:
      the timeout, in milliseconds, for the default SocketAddressResolver created at startup
      See Also:

    • setAddressResolutionTimeout

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

      Parameters:
      addressResolutionTimeout - the timeout, in milliseconds, for the default SocketAddressResolver created at startup
      See Also:

    • getIdleTimeout

      @ManagedAttribute("The timeout, in milliseconds, to close idle connections") 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)
      Set the max time, in milliseconds, a connection can be idle (that is, without traffic of bytes in either direction).
      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

      public void setBindAddress(SocketAddress bindAddress)
      Parameters:
      bindAddress - the address to bind socket channels to
      See Also:

    • getUserAgentField

      public HttpField getUserAgentField()
      Get the "User-Agent" HTTP field of this HttpClient.
      Returns:
      the "User-Agent" HTTP field of this HttpClient

    • setUserAgentField

      public void setUserAgentField(HttpField agent)
      Set the "User-Agent" HTTP header string of this HttpClient.
      Parameters:
      agent - the "User-Agent" HTTP header string of this HttpClient

    • isFollowRedirects

      @ManagedAttribute("Whether HTTP redirects are followed") public boolean isFollowRedirects()
      Returns:
      whether this HttpClient follows HTTP redirects
      See Also:

    • setFollowRedirects

      public void setFollowRedirects(boolean follow)
      Parameters:
      follow - whether this HttpClient follows HTTP redirects
      See Also:

    • getExecutor

      public Executor getExecutor()
      Get the Executor of this HttpClient.
      Returns:
      the Executor of this HttpClient

    • setExecutor

      public void setExecutor(Executor executor)
      Set the Executor of this HttpClient.
      Parameters:
      executor - the Executor of this HttpClient

    • getScheduler

      public Scheduler getScheduler()
      Get the Scheduler of this HttpClient.
      Returns:
      the Scheduler of this HttpClient

    • setScheduler

      public void setScheduler(Scheduler scheduler)
      Set the Scheduler of this HttpClient.
      Parameters:
      scheduler - the Scheduler of this HttpClient

    • getSocketAddressResolver

      public SocketAddressResolver getSocketAddressResolver()
      Get the SocketAddressResolver of this HttpClient.
      Returns:
      the SocketAddressResolver of this HttpClient

    • setSocketAddressResolver

      public void setSocketAddressResolver(SocketAddressResolver resolver)
      Set the SocketAddressResolver of this HttpClient.
      Parameters:
      resolver - the SocketAddressResolver of this HttpClient

    • getMaxConnectionsPerDestination

      @ManagedAttribute("The max number of connections per each destination") 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

      @ManagedAttribute("The max number of requests queued per each destination") 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

      @ManagedAttribute("The request buffer size in bytes") public int getRequestBufferSize()
      Returns:
      the size of the buffer (in bytes) used to write requests

    • setRequestBufferSize

      public void setRequestBufferSize(int requestBufferSize)
      Set the size of the buffer (in bytes) used to write requests.
      Parameters:
      requestBufferSize - the size of the buffer (in bytes) used to write requests

    • getResponseBufferSize

      @ManagedAttribute("The response buffer size in bytes") public int getResponseBufferSize()
      Returns:
      the size of the buffer (in bytes) used to read responses

    • setResponseBufferSize

      public void setResponseBufferSize(int responseBufferSize)
      Set the size of the buffer used to read responses.
      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 in a conversation
      See Also:

    • setMaxRedirects

      public void setMaxRedirects(int maxRedirects)
      Parameters:
      maxRedirects - the max number of HTTP redirects that are followed in a conversation, or -1 for unlimited redirects
      See Also:

    • getHttpCompliance

      public HttpCompliance getHttpCompliance()
      Gets the http compliance mode for parsing http responses. The default http compliance level is HttpCompliance.RFC7230 which is the latest HTTP/1.1 specification
      Returns:
      the HttpCompliance instance

    • setHttpCompliance

      public void setHttpCompliance(HttpCompliance httpCompliance)
      Sets the http compliance mode for parsing http responses. This affect how weak the HttpParser parses http responses and which http protocol level is supported
      Parameters:
      httpCompliance - The compliance level which is used to actually parse http responses

    • isStrictEventOrdering

      @ManagedAttribute("Whether request/response events must be strictly ordered") public boolean isStrictEventOrdering()
      Returns:
      whether request events must be strictly ordered
      See Also:

    • 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

    • getDestinationIdleTimeout

      @ManagedAttribute("The time in ms after which idle destinations are removed, disabled when zero or negative") public long getDestinationIdleTimeout()
      The default value is 0
      Returns:
      the time in ms after which idle destinations are removed
      See Also:

    • setDestinationIdleTimeout

      public void setDestinationIdleTimeout(long destinationIdleTimeout)

      Whether destinations that have no connections (nor active nor idle) and no exchanges should be removed after the specified timeout.

      If the specified destinationIdleTimeout is 0 or negative, then the destinations are not removed.

      Avoids accumulating destinations when applications (e.g. a spider bot or web crawler) hit a lot of different destinations that won't be visited again.

      Parameters:
      destinationIdleTimeout - the time in ms after which idle destinations are removed

    • isConnectBlocking

      @ManagedAttribute("Whether the connect() operation is blocking") public boolean isConnectBlocking()
      Returns:
      whether connect() operations are performed in blocking mode

    • setConnectBlocking

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

      Parameters:
      connectBlocking - whether connect() operations are performed in blocking mode

    • getDefaultRequestContentType

      @ManagedAttribute("The default content type for request content") public String getDefaultRequestContentType()
      Returns:
      the default content type for request content

    • setDefaultRequestContentType

      public void setDefaultRequestContentType(String contentType)
      Set the default content type for request content.
      Parameters:
      contentType - the default content type for request content

    • isUseInputDirectByteBuffers

      @ManagedAttribute("Whether to use direct ByteBuffers for reading") public boolean isUseInputDirectByteBuffers()
      Returns:
      whether to use direct ByteBuffers for reading

    • setUseInputDirectByteBuffers

      public void setUseInputDirectByteBuffers(boolean useInputDirectByteBuffers)
      Set whether to use direct ByteBuffers for reading.
      Parameters:
      useInputDirectByteBuffers - whether to use direct ByteBuffers for reading

    • isUseOutputDirectByteBuffers

      @ManagedAttribute("Whether to use direct ByteBuffers for writing") public boolean isUseOutputDirectByteBuffers()
      Returns:
      whether to use direct ByteBuffers for writing

    • setUseOutputDirectByteBuffers

      public void setUseOutputDirectByteBuffers(boolean useOutputDirectByteBuffers)
      Set whether to use direct ByteBuffers for writing.
      Parameters:
      useOutputDirectByteBuffers - whether to use direct ByteBuffers for writing

    • getMaxResponseHeadersSize

      @ManagedAttribute("The max size in bytes of the response headers") public int getMaxResponseHeadersSize()
      Returns:
      the max size in bytes of the response headers

    • setMaxResponseHeadersSize

      public void setMaxResponseHeadersSize(int maxResponseHeadersSize)
      Set the max size in bytes of the response headers.
      Parameters:
      maxResponseHeadersSize - the max size in bytes of the response headers

    • getProxyConfiguration

      public ProxyConfiguration getProxyConfiguration()
      Get the forward proxy configuration.
      Returns:
      the forward proxy configuration

    • normalizePort

      public static int normalizePort(String scheme, int port)
      Return a normalized port suitable for use by Origin and Address
      Parameters:
      scheme - the scheme to use for the default port (if port is unspecified)
      port - the port (0 or negative means the port is unspecified)
      Returns:
      the normalized port.

    • newSslClientConnectionFactory

      public ClientConnectionFactory newSslClientConnectionFactory(SslContextFactory.Client sslContextFactory, ClientConnectionFactory connectionFactory)

    • close

      public void close() throws Exception
      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception