Module net.shibboleth.utilities.java.support
Package net.shibboleth.utilities.java.support.httpclient

Class HttpClientBuilder

  • Direct Known Subclasses:
    FileCachingHttpClientBuilder, InMemoryCachingHttpClientBuilder
    public class HttpClientBuilder
extends Object
    Builder used to construct HttpClient objects configured with particular settings.

    When using the single-arg constructor variant to wrap an existing instance of HttpClientBuilder, there are several caveats of which to be aware:

    • Instances of the following which are set as the default instance on the Apache builder will be unconditionally overwritten by this builder when buildClient() is called:
      • RequestConfig
      • ConnectionConfig

      This is due to the unfortunate fact that the Apache builder does not currently provide accessor methods to obtain the default instances currently set on the builder. Therefore, if you need to set any default request or connection config parameters which are not exposed by this builder, then you must use the Apache builder directly and may not use this builder.

    • If this builder's connectionDisregardTLSCertificate is set to true, then any value previously set via the Apache builder's HttpClientBuilder.setSSLSocketFactory(org.apache.http.conn.socket.LayeredConnectionSocketFactory) will be unconditionally overwritten.
    • If this builder is supplied with a connectionProxyHost, connectionProxyUsername and connectionProxyPassword, then any value previously set via the Apache builder's HttpClientBuilder.setDefaultCredentialsProvider(CredentialsProvider) will be unconditionally overwritten.
    • Per the Apache builder's Javadoc, if a non-null instance of HttpClientConnectionManager is set on the Apache builder via HttpClientBuilder.setConnectionManager(org.apache.http.conn.HttpClientConnectionManager), this supersedes various other properties set on the Apache builder. This includes the following instances/properties on the Apache builder:
      • SSLSocketFactory (LayeredConnectionSocketFactory)
      • SSLContext
      • HostnameVerifier
      • SocketConfig
      • ConnectionConfig
      • maxConnTotal
      • maxConnPerRoute

      Similarly, the following setters on this builder will become ineffective when a non-null connection manger is set on the Apache builder:

      Therefore, if you need to explicitly supply a connection manager instance to the Apache builder (for example in order to be able to use IdleConnectionSweeper), then you must supply these properties or instances directly to the connection manager rather than to this builder or the Apache builder.

    • Similar to the above issue, setting an explicit SSLSocketFactory on the Apache builder will supersede the following Apache builder properties:

    • Field Detail

      • socketLocalAddress

        private InetAddress socketLocalAddress
        Local IP address used when establishing connections. Default value: system default local address

      • socketTimeout

        @Nonnull
private Duration socketTimeout
        Maximum period inactivity between two consecutive data packets. Default value: (60 seconds)

      • socketBufferSize

        private int socketBufferSize
        Socket buffer size in bytes. Default size is 8192 bytes.

      • connectionTimeout

        @Nonnull
private Duration connectionTimeout
        Maximum length of time to wait for the connection to be established. Default value: (60 seconds)

      • connectionRequestTimeout

        @Nonnull
private Duration connectionRequestTimeout
        Maximum length of time to wait for a connection to be returned from the connection manager. Default value: (60 seconds);

      • maxConnectionsTotal

        private int maxConnectionsTotal
        Max total simultaneous connections allowed by the pooling connection manager.

      • maxConnectionsPerRoute

        private int maxConnectionsPerRoute
        Max simultaneous connections per route allowed by the pooling connection manager.

      • connectionDisregardTLSCertificate

        private boolean connectionDisregardTLSCertificate
        Whether the SSL/TLS certificates used by the responder should be ignored. Default value: false

      • tlsSocketFactory

        @Nullable
private org.apache.http.conn.socket.LayeredConnectionSocketFactory tlsSocketFactory
        The TLS socket factory to use. Optional, defaults to null.

      • connectionCloseAfterResponse

        private boolean connectionCloseAfterResponse
        Whether to instruct the server to close the connection after it has sent its response. Default value: true

      • connectionStaleCheck

        private boolean connectionStaleCheck
        Whether to check a connection for staleness before using. This can be an expensive operation. Default value: false

      • connectionProxyHost

        @Nullable
private String connectionProxyHost
        Host name of the HTTP proxy server through which connections will be made. Default value: null.

      • userAgent

        @Nullable
private String userAgent
        Apache UserAgent.

      • connectionProxyPort

        private int connectionProxyPort
        Port number of the HTTP proxy server through which connections will be made. Default value: 8080.

      • connectionProxyUsername

        @Nullable
private String connectionProxyUsername
        Username used to connect to the HTTP proxy server. Default value: null.

      • connectionProxyPassword

        @Nullable
private String connectionProxyPassword
        Password used to connect to the HTTP proxy server. Default value: null.

      • httpFollowRedirects

        private boolean httpFollowRedirects
        Whether to follow HTTP redirects. Default value: true

      • httpContentCharSet

        @Nullable
private String httpContentCharSet
        Character set used for HTTP entity content. Default value: UTF-8

      • retryHandler

        @Nullable
private org.apache.http.client.HttpRequestRetryHandler retryHandler
        Handler which determines if a request should be retried after a recoverable exception during execution.

      • serviceUnavailStrategy

        @Nullable
private org.apache.http.client.ServiceUnavailableRetryStrategy serviceUnavailStrategy
        Strategy which determines if a request should be retried given the response from the target server.

      • disableAuthCaching

        private boolean disableAuthCaching
        Flag for disabling auth caching.

      • disableAutomaticRetries

        private boolean disableAutomaticRetries
        Flag for disabling automatic retries.

      • disableConnectionState

        private boolean disableConnectionState
        Flag for disabling connection state.

      • disableContentCompression

        private boolean disableContentCompression
        Flag for disabling content compression.

      • disableCookieManagement

        private boolean disableCookieManagement
        Flag for disabling cookie management.

      • disableRedirectHandling

        private boolean disableRedirectHandling
        Flag for disabling redirect handling.

      • useSystemProperties

        private boolean useSystemProperties
        Flag for enabling use of system properties.

      • apacheBuilder

        private org.apache.http.impl.client.HttpClientBuilder apacheBuilder
        The Apache HttpClientBuilder 4.3+ instance over which to layer this builder.

    • Constructor Detail

      • HttpClientBuilder

        public HttpClientBuilder()
        Constructor.

      • HttpClientBuilder

        public HttpClientBuilder​(@Nonnull
                         org.apache.http.impl.client.HttpClientBuilder builder)
        Constructor.
        Parameters:
        builder - the Apache HttpClientBuilder 4.3+ instance over which to layer this builder

    • Method Detail

      • resetDefaults

        public void resetDefaults()
        Resets all builder parameters to their defaults.

      • getMaxConnectionsTotal

        public int getMaxConnectionsTotal()
        Gets the max total simultaneous connections allowed by the pooling connection manager.
        Returns:
        the max total connections

      • setMaxConnectionsTotal

        public void setMaxConnectionsTotal​(int max)
        Sets the max total simultaneous connections allowed by the pooling connection manager.
        Parameters:
        max - the max total connection

      • getMaxConnectionsPerRoute

        public int getMaxConnectionsPerRoute()
        Gets the max simultaneous connections per route allowed by the pooling connection manager.
        Returns:
        the max connections per route

      • setMaxConnectionsPerRoute

        public void setMaxConnectionsPerRoute​(int max)
        Sets the max simultaneous connections per route allowed by the pooling connection manager.
        Parameters:
        max - the max connections per route

      • getSocketLocalAddress

        public InetAddress getSocketLocalAddress()
        Gets the local IP address used when making requests.
        Returns:
        local IP address used when making requests

      • setSocketLocalAddress

        public void setSocketLocalAddress​(InetAddress address)
        Sets the local IP address used when making requests.
        Parameters:
        address - local IP address used when making requests

      • setSocketLocalAddress

        public void setSocketLocalAddress​(String ipOrHost)
                           throws UnknownHostException
        Sets the local IP address used when making requests.
        Parameters:
        ipOrHost - IP address or hostname, never null
        Throws:
        UnknownHostException - thrown if the given IP or hostname can not be resolved

      • getSocketTimeout

        @Nonnull
public Duration getSocketTimeout()
        Gets the maximum period inactivity between two consecutive data packets. A value of less than 1 ms indicates no timeout.
        Returns:
        maximum period inactivity between two consecutive data packets

      • setSocketTimeout

        public void setSocketTimeout​(@Nonnull
                             Duration timeout)
        Sets the maximum period inactivity between two consecutive data packets. A value of less than 1 ms indicates no timeout.
        Parameters:
        timeout - maximum period inactivity between two consecutive data packets

      • getSocketBufferSize

        public int getSocketBufferSize()
        Gets the size of the socket buffer, in bytes, used for request/response buffering.
        Returns:
        size of the socket buffer, in bytes, used for request/response buffering

      • setSocketBufferSize

        public void setSocketBufferSize​(int size)
        Sets size of the socket buffer, in bytes, used for request/response buffering.
        Parameters:
        size - size of the socket buffer, in bytes, used for request/response buffering; must be greater than 0

      • getConnectionTimeout

        @Nonnull
public Duration getConnectionTimeout()
        Gets the maximum length of time to wait for the connection to be established. A value of less than 1 ms indicates no timeout.
        Returns:
        maximum length of time to wait for the connection to be established

      • setConnectionTimeout

        public void setConnectionTimeout​(@Nonnull
                                 Duration timeout)
        Sets the maximum length of time to wait for the connection to be established. A value of less than 1 ms indicates no timeout.
        Parameters:
        timeout - maximum length of time to wait for the connection to be established

      • getConnectionRequestTimeout

        @Nonnull
public Duration getConnectionRequestTimeout()
        Gets the maximum length of time to wait for a connection to be returned from the connection manager. A value of less than 1 ms indicates no timeout.
        Returns:
        maximum length of time to wait for the connection to be established

      • setConnectionRequestTimeout

        public void setConnectionRequestTimeout​(@Nonnull
                                        Duration timeout)
        Sets the maximum length of time to wait for a connection to be returned from the connection manager. A value of less than 1 ms indicates no timeout.
        Parameters:
        timeout - maximum length of time to wait for the connection to be established

      • isConnectionDisregardTLSCertificate

        public boolean isConnectionDisregardTLSCertificate()
        Gets whether the responder's SSL/TLS certificate should be ignored.

        This flag is overridden and ignored if a custom TLS socket factory is specified via setTLSSocketFactory(org.apache.http.conn.socket.LayeredConnectionSocketFactory).

        Returns:
        whether the responder's SSL/TLS certificate should be ignored

      • setConnectionDisregardTLSCertificate

        public void setConnectionDisregardTLSCertificate​(boolean disregard)
        Sets whether the responder's SSL/TLS certificate should be ignored.

        This flag is overridden and ignored if a custom TLS socket factory is specified via setTLSSocketFactory(org.apache.http.conn.socket.LayeredConnectionSocketFactory).

        Parameters:
        disregard - whether the responder's SSL/TLS certificate should be ignored

      • getTLSSocketFactory

        @Nullable
public org.apache.http.conn.socket.LayeredConnectionSocketFactory getTLSSocketFactory()
        Get the TLS socket factory to use.
        Returns:
        the socket factory, or null.

      • setTLSSocketFactory

        public void setTLSSocketFactory​(@Nullable
                                org.apache.http.conn.socket.LayeredConnectionSocketFactory factory)
        Set the TLS socket factory to use.
        Parameters:
        factory - the new socket factory, may be null

      • isConnectionCloseAfterResponse

        public boolean isConnectionCloseAfterResponse()
        Gets whether to instruct the server to close the connection after it has sent its response.
        Returns:
        whether to instruct the server to close the connection after it has sent its response

      • setConnectionCloseAfterResponse

        public void setConnectionCloseAfterResponse​(boolean close)
        Sets whether to instruct the server to close the connection after it has sent its response.
        Parameters:
        close - whether to instruct the server to close the connection after it has sent its response

      • isConnectionStalecheck

        @Deprecated(forRemoval=true)
public boolean isConnectionStalecheck()
        Deprecated, for removal: This API element is subject to removal in a future version.
        use isConnectionStaleCheck()
        Gets whether reused connections are checked if they are closed before being used by the client.
        Returns:
        whether reused connections are checked if they are closed before being used by the client

      • setConnectionStalecheck

        @Deprecated(forRemoval=true)
public void setConnectionStalecheck​(boolean check)
        Deprecated, for removal: This API element is subject to removal in a future version.
        use setConnectionStaleCheck(boolean)
        Sets whether reused connections are checked if they are closed before being used by the client. Checking can take up to 30ms (per request). If checking is turned off an I/O error occurs if the connection is used request. This should be enabled uncles the code using the client explicitly handles the error case and retries connection as appropriate.
        Parameters:
        check - whether reused connections are checked if they are closed before being used by the client

      • isConnectionStaleCheck

        @Deprecated(forRemoval=true)
public boolean isConnectionStaleCheck()
        Deprecated, for removal: This API element is subject to removal in a future version.
        use a custom-configured connection pool manger. See PoolingHttpClientConnectionManager.setValidateAfterInactivity(int)
        Gets whether reused connections are checked if they are closed before being used by the client.
        Returns:
        whether reused connections are checked if they are closed before being used by the client

      • setConnectionStaleCheck

        @Deprecated(forRemoval=true)
public void setConnectionStaleCheck​(boolean check)
        Deprecated, for removal: This API element is subject to removal in a future version.
        use a custom-configured connection pool manger. See PoolingHttpClientConnectionManager.setValidateAfterInactivity(int)
        Sets whether reused connections are checked if they are closed before being used by the client. Checking can take up to 30ms (per request). If checking is turned off an I/O error occurs if the connection is used request. This should be enabled uncles the code using the client explicitly handles the error case and retries connection as appropriate.
        Parameters:
        check - whether reused connections are checked if they are closed before being used by the client

      • getConnectionProxyHost

        @Nullable
public String getConnectionProxyHost()
        Gets the hostname of the default proxy used when making connection. A null indicates no default proxy.
        Returns:
        hostname of the default proxy used when making connection

      • setConnectionProxyHost

        public void setConnectionProxyHost​(@Nullable
                                   String host)
        Sets the hostname of the default proxy used when making connection. A null indicates no default proxy.
        Parameters:
        host - hostname of the default proxy used when making connection

      • getConnectionProxyPort

        public int getConnectionProxyPort()
        Gets the port of the default proxy used when making connection.
        Returns:
        port of the default proxy used when making connection

      • setConnectionProxyPort

        public void setConnectionProxyPort​(int port)
        Sets the port of the default proxy used when making connection.
        Parameters:
        port - port of the default proxy used when making connection; must be greater than 0 and less than 65536

      • getConnectionProxyUsername

        @Nullable
public String getConnectionProxyUsername()
        Gets the username to use when authenticating to the proxy.
        Returns:
        username to use when authenticating to the proxy

      • setConnectionProxyUsername

        public void setConnectionProxyUsername​(@Nullable
                                       String usename)
        Sets the username to use when authenticating to the proxy.
        Parameters:
        usename - username to use when authenticating to the proxy; may be null

      • getConnectionProxyPassword

        @Nullable
public String getConnectionProxyPassword()
        Gets the password used when authenticating to the proxy.
        Returns:
        password used when authenticating to the proxy

      • setConnectionProxyPassword

        public void setConnectionProxyPassword​(@Nullable
                                       String password)
        Sets the password used when authenticating to the proxy.
        Parameters:
        password - password used when authenticating to the proxy; may be null

      • isHttpFollowRedirects

        public boolean isHttpFollowRedirects()
        Gets whether HTTP redirects will be followed.
        Returns:
        whether HTTP redirects will be followed

      • setHttpFollowRedirects

        public void setHttpFollowRedirects​(boolean followRedirects)
        Gets whether HTTP redirects will be followed.
        Parameters:
        followRedirects - true if redirects are followed, false otherwise

      • getHttpContentCharSet

        @Nullable
public String getHttpContentCharSet()
        Gets the character set used with the HTTP entity (body).
        Returns:
        character set used with the HTTP entity (body)

      • setHttpContentCharSet

        public void setHttpContentCharSet​(@Nullable
                                  String charSet)
        Sets the character set used with the HTTP entity (body).
        Parameters:
        charSet - character set used with the HTTP entity (body)

      • getUserAgent

        @Nullable
public String getUserAgent()
        Gets user agent.
        Returns:
        The user agent.

      • setUserAgent

        public void setUserAgent​(@Nullable
                         String what)
        Sets user agent.
        Parameters:
        what - what to set. If this is null Apache will use the default.

      • getHttpRequestRetryHandler

        @Nullable
public org.apache.http.client.HttpRequestRetryHandler getHttpRequestRetryHandler()
        Get the handler which determines if a request should be retried after a recoverable exception during execution.
        Returns:
        handler which determines if a request should be retried

      • setHttpRequestRetryHandler

        public void setHttpRequestRetryHandler​(@Nullable
                                       org.apache.http.client.HttpRequestRetryHandler handler)
        Set the handler which determines if a request should be retried after a recoverable exception during execution.
        Parameters:
        handler - handler which determines if a request should be retried

      • getServiceUnavailableRetryHandler

        @Nullable
public org.apache.http.client.ServiceUnavailableRetryStrategy getServiceUnavailableRetryHandler()
        Get the handler which determines if a request should be retried given the response from the target server.
        Returns:
        handler which determines if a request should be retried

      • setServiceUnavailableRetryHandler

        public void setServiceUnavailableRetryHandler​(@Nullable
                                              org.apache.http.client.ServiceUnavailableRetryStrategy strategy)
        Set the strategy which determines if a request should be retried given the response from the target server.
        Parameters:
        strategy - handler which determines if a request should be retried

      • isDisableAuthCaching

        public boolean isDisableAuthCaching()
        Get the flag for disabling auth caching.
        Returns:
        true if disabled, false if not

      • setDisableAuthCaching

        public void setDisableAuthCaching​(boolean flag)
        Set the flag for disabling auth caching.
        Parameters:
        flag - true if disabled, false if not

      • isDisableAutomaticRetries

        public boolean isDisableAutomaticRetries()
        Get the flag for disabling automatic retries.
        Returns:
        true if disabled, false if not

      • setDisableAutomaticRetries

        public void setDisableAutomaticRetries​(boolean flag)
        Set the flag for disabling automatic retries.
        Parameters:
        flag - true if disabled, false if not

      • isDisableConnectionState

        public boolean isDisableConnectionState()
        Get the flag for disabling connection state.
        Returns:
        true if disabled, false if not

      • setDisableConnectionState

        public void setDisableConnectionState​(boolean flag)
        Set the flag for disabling connection state.
        Parameters:
        flag - true if disabled, false if not

      • isDisableContentCompression

        public boolean isDisableContentCompression()
        Get the flag for disabling content compression.
        Returns:
        true if disabled, false if not

      • setDisableContentCompression

        public void setDisableContentCompression​(boolean flag)
        Set the flag for disabling content compression.
        Parameters:
        flag - true if disabled, false if not

      • isDisableCookieManagement

        public boolean isDisableCookieManagement()
        Get the flag for disabling cookie management.
        Returns:
        true if disabled, false if not

      • setDisableCookieManagement

        public void setDisableCookieManagement​(boolean flag)
        Set the flag for disabling cookie management.
        Parameters:
        flag - true if disabled, false if not

      • isDisableRedirectHandling

        public boolean isDisableRedirectHandling()
        Get the flag for disabling redirect handling.
        Returns:
        true if disabled, false if not

      • setDisableRedirectHandling

        public void setDisableRedirectHandling​(boolean flag)
        Set the flag for disabling redirect handling.
        Parameters:
        flag - true if disabled, false if not

      • isUseSystemProperties

        public boolean isUseSystemProperties()
        Get the flag enabling use of system properties.
        Returns:
        true if enabled, false if not

      • setUseSystemProperties

        public void setUseSystemProperties​(boolean flag)
        Set the flag enabling use of system properties.
        Parameters:
        flag - true if enabled, false if not

      • getFirstRequestInterceptors

        @Nonnull
@NonnullElements
@NotLive
@Unmodifiable
public List<org.apache.http.HttpRequestInterceptor> getFirstRequestInterceptors()
        Get the list of request interceptors to add first.
        Returns:
        the list of interceptors

      • setFirstRequestInterceptors

        public void setFirstRequestInterceptors​(@Nullable @NonnullElements
                                        List<org.apache.http.HttpRequestInterceptor> interceptors)
        Set the list of request interceptors to add first.
        Parameters:
        interceptors - the list of interceptors, may be null

      • getLastRequestInterceptors

        @Nonnull
@NonnullElements
@NotLive
@Unmodifiable
public List<org.apache.http.HttpRequestInterceptor> getLastRequestInterceptors()
        Get the list of request interceptors to add last.
        Returns:
        the list of interceptors

      • setLastRequestInterceptors

        public void setLastRequestInterceptors​(@Nullable @NonnullElements
                                       List<org.apache.http.HttpRequestInterceptor> interceptors)
        Set the list of request interceptors to add last.
        Parameters:
        interceptors - the list of interceptors, may be null

      • getFirstResponseInterceptors

        @Nonnull
@NonnullElements
@NotLive
@Unmodifiable
public List<org.apache.http.HttpResponseInterceptor> getFirstResponseInterceptors()
        Get the list of response interceptors to add first.
        Returns:
        the list of interceptors

      • setFirstResponseInterceptors

        public void setFirstResponseInterceptors​(@Nullable @NonnullElements
                                         List<org.apache.http.HttpResponseInterceptor> interceptors)
        Set the list of response interceptors to add first.
        Parameters:
        interceptors - the list of interceptors, may be null

      • getLastResponseInterceptors

        @Nonnull
@NonnullElements
@NotLive
@Unmodifiable
public List<org.apache.http.HttpResponseInterceptor> getLastResponseInterceptors()
        Get the list of response interceptors to add last.
        Returns:
        the list of interceptors

      • setLastResponseInterceptors

        public void setLastResponseInterceptors​(@Nullable @NonnullElements
                                        List<org.apache.http.HttpResponseInterceptor> interceptors)
        Set the list of response interceptors to add last.
        Parameters:
        interceptors - the list of interceptors, may be null

      • buildClient

        public org.apache.http.client.HttpClient buildClient()
                                              throws Exception
        Constructs an HttpClient using the settings of this builder.
        Returns:
        the constructed client
        Throws:
        Exception - if there is any problem building the new client instance

      • decorateApacheBuilder

        protected void decorateApacheBuilder()
                              throws Exception
        Decorate the Apache builder as determined by this builder's parameters. Subclasses will likely add additional decoration.
        Throws:
        Exception - if there is a problem decorating the Apache builder

      • getApacheBuilder

        protected org.apache.http.impl.client.HttpClientBuilder getApacheBuilder()
        Get the Apache HttpClientBuilder instance over which this builder will be layered. Subclasses may override to return a specialized subclass.
        Returns:
        the Apache HttpClientBuilder instance to use