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

Class HttpClientBuilder

java.lang.Object
net.shibboleth.utilities.java.support.httpclient.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 Details

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

    • requestInterceptorsFirst

      @Nonnull @NonnullElements @Unmodifiable @NotLive private List<org.apache.http.HttpRequestInterceptor> requestInterceptorsFirst
      List of request interceptors to add first.

    • requestInterceptorsLast

      @Nonnull @NonnullElements @Unmodifiable @NotLive private List<org.apache.http.HttpRequestInterceptor> requestInterceptorsLast
      List of request interceptors to add last.

    • responseInterceptorsFirst

      @Nonnull @NonnullElements @Unmodifiable @NotLive private List<org.apache.http.HttpResponseInterceptor> responseInterceptorsFirst
      List of response interceptors to add first.

    • responseInterceptorsLast

      @Nonnull @NonnullElements @Unmodifiable @NotLive private List<org.apache.http.HttpResponseInterceptor> responseInterceptorsLast
      List of response interceptors to add last.

    • staticContextHandlers

      @Nonnull @NonnullElements @Unmodifiable @NotLive private List<HttpClientContextHandler> staticContextHandlers
      List of static context handlers.

    • apacheBuilder

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

  • Constructor Details

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

    • 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

    • getStaticContextHandlers

      @Nonnull @NonnullElements @NotLive @Unmodifiable public List<HttpClientContextHandler> getStaticContextHandlers()
      Get the list of static HttpClientContextHandler.
      Returns:
      the list of handlers

    • setStaticContextHandlers

      public void setStaticContextHandlers(@Nullable @NonnullElements List<HttpClientContextHandler> handlers)
      Set the list of static HttpClientContextHandler.
      Parameters:
      handlers - the list of handlers, 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