Package org.eclipse.jetty.client

Class HttpClient

  • All Implemented Interfaces:
    Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle
    @ManagedObject("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)
     {
         ...
     }
 });

    • Method Detail

      • dump

        public void dump​(java.lang.Appendable out,
                 java.lang.String indent)
          throws java.io.IOException
        Description copied from interface: Dumpable
        Dump this object (and children) into an Appendable using the provided indent after any new lines. The indent should not be applied to the first object dumped.
        Specified by:
        dump in interface Dumpable
        Overrides:
        dump in class ContainerLifeCycle
        Parameters:
        out - The appendable to dump to
        indent - The indent to apply after any new lines.
        Throws:
        java.io.IOException - if unable to write to Appendable

      • doStart

        protected void doStart()
                throws java.lang.Exception
        Description copied from class: ContainerLifeCycle
        Starts the managed lifecycle beans in the order they were added.
        Overrides:
        doStart in class ContainerLifeCycle
        Throws:
        java.lang.Exception

      • doStop

        protected void doStop()
               throws java.lang.Exception
        Description copied from class: ContainerLifeCycle
        Stops the managed lifecycle beans in the reverse order they were added.
        Overrides:
        doStop in class ContainerLifeCycle
        Throws:
        java.lang.Exception

      • getRequestListeners

        public java.util.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 java.net.CookieStore getCookieStore()
        Returns:
        the cookie store associated with this instance

      • setCookieStore

        public void setCookieStore​(java.net.CookieStore cookieStore)
        Parameters:
        cookieStore - the cookie store associated with this instance

      • getAuthenticationStore

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

      • setAuthenticationStore

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

      • GET

        public ContentResponse GET​(java.lang.String uri)
                    throws java.lang.InterruptedException,
                           java.util.concurrent.ExecutionException,
                           java.util.concurrent.TimeoutException
        Performs a GET request to the specified URI.
        Parameters:
        uri - the URI to GET
        Returns:
        the ContentResponse for the request
        Throws:
        java.lang.InterruptedException - if send threading has been interrupted
        java.util.concurrent.ExecutionException - the execution failed
        java.util.concurrent.TimeoutException - the send timed out
        See Also:
        GET(URI)

      • GET

        public ContentResponse GET​(java.net.URI uri)
                    throws java.lang.InterruptedException,
                           java.util.concurrent.ExecutionException,
                           java.util.concurrent.TimeoutException
        Performs a GET request to the specified URI.
        Parameters:
        uri - the URI to GET
        Returns:
        the ContentResponse for the request
        Throws:
        java.lang.InterruptedException - if send threading has been interrupted
        java.util.concurrent.ExecutionException - the execution failed
        java.util.concurrent.TimeoutException - the send timed out
        See Also:
        newRequest(URI)

      • FORM

        public ContentResponse FORM​(java.lang.String uri,
                            Fields fields)
                     throws java.lang.InterruptedException,
                            java.util.concurrent.ExecutionException,
                            java.util.concurrent.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:
        java.lang.InterruptedException - if send threading has been interrupted
        java.util.concurrent.ExecutionException - the execution failed
        java.util.concurrent.TimeoutException - the send timed out

      • FORM

        public ContentResponse FORM​(java.net.URI uri,
                            Fields fields)
                     throws java.lang.InterruptedException,
                            java.util.concurrent.ExecutionException,
                            java.util.concurrent.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:
        java.lang.InterruptedException - if send threading has been interrupted
        java.util.concurrent.ExecutionException - the execution failed
        java.util.concurrent.TimeoutException - the send timed out

      • POST

        public Request POST​(java.lang.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​(java.net.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​(java.lang.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​(java.lang.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​(java.net.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​(HttpRequest oldRequest,
                              java.net.URI newURI)

      • getDestination

        public Destination getDestination​(java.lang.String scheme,
                                  java.lang.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​(java.lang.String scheme,
                                         java.lang.String host,
                                         int port)

      • resolveDestination

        protected HttpDestination resolveDestination​(java.lang.String scheme,
                                             java.lang.String host,
                                             int port,
                                             java.lang.Object tag)

      • createOrigin

        protected Origin createOrigin​(java.lang.String scheme,
                              java.lang.String host,
                              int port,
                              java.lang.Object tag)

      • resolveDestination

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

        protected boolean removeDestination​(HttpDestination destination)

      • getDestinations

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

      • getName

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

      • setName

        public void setName​(java.lang.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:
        Socket.connect(SocketAddress, int)

      • 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)
        Parameters:
        idleTimeout - the max time, in milliseconds, a connection can be idle (that is, without traffic of bytes in either direction)

      • getBindAddress

        public java.net.SocketAddress getBindAddress()
        Returns:
        the address to bind socket channels to
        See Also:
        setBindAddress(SocketAddress)

      • setBindAddress

        public void setBindAddress​(java.net.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

      • setFollowRedirects

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

      • getExecutor

        public java.util.concurrent.Executor getExecutor()
        Returns:
        the Executor of this HttpClient

      • setExecutor

        public void setExecutor​(java.util.concurrent.Executor executor)
        Parameters:
        executor - the Executor 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")
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

        @ManagedAttribute("The response buffer size")
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 in a conversation
        See Also:
        setMaxRedirects(int)

      • 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:
        setFollowRedirects(boolean)

      • isTCPNoDelay

        @ManagedAttribute(value="Whether the TCP_NODELAY option is enabled",
                  name="tcpNoDelay")
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

        @Deprecated
public boolean isDispatchIO()
        Deprecated.
        Returns:
        true to dispatch I/O operations in a different thread, false to execute them in the selector thread
        See Also:
        setDispatchIO(boolean)

      • setDispatchIO

        @Deprecated
public void setDispatchIO​(boolean dispatchIO)
        Deprecated.
        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

      • 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(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

      • 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(long)

      • 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

      • setRemoveIdleDestinations

        @Deprecated
public void setRemoveIdleDestinations​(boolean removeIdleDestinations)
        Deprecated.
        replaced by setDestinationIdleTimeout(long), calls the latter with a value of 10000 ms.
        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:
        DuplexConnectionPool

      • 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 java.lang.String getDefaultRequestContentType()
        Returns:
        the default content type for request content

      • setDefaultRequestContentType

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

      • getProxyConfiguration

        public ProxyConfiguration getProxyConfiguration()
        Returns:
        the forward proxy configuration

      • getAcceptEncodingField

        protected HttpField getAcceptEncodingField()

      • normalizeHost

        @Deprecated
protected java.lang.String normalizeHost​(java.lang.String host)
        Deprecated.
        no replacement, do not use it
        Parameters:
        host - the host to normalize
        Returns:
        the host itself

      • normalizePort

        public static int normalizePort​(java.lang.String scheme,
                                int port)

      • isDefaultPort

        public boolean isDefaultPort​(java.lang.String scheme,
                             int port)