Module org.eclipse.jetty.client
Package org.eclipse.jetty.client

Class HttpClient

  • All Implemented Interfaces:
    org.eclipse.jetty.util.component.Container, org.eclipse.jetty.util.component.Destroyable, org.eclipse.jetty.util.component.Dumpable, org.eclipse.jetty.util.component.Dumpable.DumpableContainer, org.eclipse.jetty.util.component.LifeCycle
    @ManagedObject("The HTTP client")
public class HttpClient
extends org.eclipse.jetty.util.component.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)
     {
         ...
     }
 });

    • Field Detail

      • USER_AGENT

        public static final java.lang.String USER_AGENT

    • Constructor Detail

      • HttpClient

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

    • Method Detail

      • dump

        public void dump​(java.lang.Appendable out,
                 java.lang.String indent)
          throws java.io.IOException
        Specified by:
        dump in interface org.eclipse.jetty.util.component.Dumpable
        Overrides:
        dump in class org.eclipse.jetty.util.component.ContainerLifeCycle
        Throws:
        java.io.IOException

      • getSslContextFactory

        public org.eclipse.jetty.util.ssl.SslContextFactory.Client getSslContextFactory()
        Returns:
        the SslContextFactory that manages TLS encryption

      • doStart

        protected void doStart()
                throws java.lang.Exception
        Overrides:
        doStart in class org.eclipse.jetty.util.component.ContainerLifeCycle
        Throws:
        java.lang.Exception

      • doStop

        protected void doStop()
               throws java.lang.Exception
        Overrides:
        doStop in class org.eclipse.jetty.util.component.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,
                            org.eclipse.jetty.util.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,
                            org.eclipse.jetty.util.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)

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

      • newConnection

        protected void newConnection​(HttpDestination destination,
                             org.eclipse.jetty.util.Promise<Connection> promise)

      • getByteBufferPool

        public org.eclipse.jetty.io.ByteBufferPool getByteBufferPool()
        Returns:
        the ByteBufferPool of this HttpClient

      • setByteBufferPool

        public void setByteBufferPool​(org.eclipse.jetty.io.ByteBufferPool byteBufferPool)
        Parameters:
        byteBufferPool - the ByteBufferPool of 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)

      • getAddressResolutionTimeout

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

      • 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:
        setSocketAddressResolver(SocketAddressResolver)

      • 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 org.eclipse.jetty.http.HttpField getUserAgentField()
        Returns:
        the "User-Agent" HTTP field of this HttpClient

      • setUserAgentField

        public void setUserAgentField​(org.eclipse.jetty.http.HttpField agent)
        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:
        Request.isFollowRedirects()

      • 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

      • getScheduler

        public org.eclipse.jetty.util.thread.Scheduler getScheduler()
        Returns:
        the Scheduler of this HttpClient

      • setScheduler

        public void setScheduler​(org.eclipse.jetty.util.thread.Scheduler scheduler)
        Parameters:
        scheduler - the Scheduler of this HttpClient

      • getSocketAddressResolver

        public org.eclipse.jetty.util.SocketAddressResolver getSocketAddressResolver()
        Returns:
        the SocketAddressResolver of this HttpClient

      • setSocketAddressResolver

        public void setSocketAddressResolver​(org.eclipse.jetty.util.SocketAddressResolver resolver)
        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")
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)

      • getHttpCompliance

        public org.eclipse.jetty.http.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​(org.eclipse.jetty.http.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

      • isRemoveIdleDestinations

        @ManagedAttribute("Whether idle destinations are removed")
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:
        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

      • 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)
        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)
        Parameters:
        useOutputDirectByteBuffers - whether to use direct ByteBuffers for writing

      • getProxyConfiguration

        public ProxyConfiguration getProxyConfiguration()
        Returns:
        the forward proxy configuration

      • getAcceptEncodingField

        protected org.eclipse.jetty.http.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)

      • isSchemeSecure

        public static boolean isSchemeSecure​(java.lang.String scheme)

      • newSslClientConnectionFactory

        protected org.eclipse.jetty.io.ClientConnectionFactory newSslClientConnectionFactory​(org.eclipse.jetty.util.ssl.SslContextFactory.Client sslContextFactory,
                                                                                     org.eclipse.jetty.io.ClientConnectionFactory connectionFactory)