Package org.forgerock.http.handler

Class HttpClientHandler

java.lang.Object
org.forgerock.http.handler.HttpClientHandler
All Implemented Interfaces:
Closeable, AutoCloseable, Handler
public final class HttpClientHandler extends Object implements Handler, Closeable
An HTTP client for sending requests to remote servers.

  • Field Details

    • OPTION_CONNECT_TIMEOUT

      public static final Option<Duration> OPTION_CONNECT_TIMEOUT
      The TCP connect timeout for new HTTP connections. The default timeout is 10 seconds.

    • OPTION_SO_TIMEOUT

      public static final Option<Duration> OPTION_SO_TIMEOUT
      The TCP socket timeout when waiting for HTTP responses. The default timeout is 10 seconds.

    • OPTION_SO_KEEP_ALIVE

      public static final Option<Boolean> OPTION_SO_KEEP_ALIVE
      The TCP socket keep-alive feature. The default is false, to be consistent with StandardSocketOptions.SO_KEEPALIVE

    • OPTION_SO_REUSE_ADDRESS

      public static final Option<Boolean> OPTION_SO_REUSE_ADDRESS
      The TCP socket reuse address feature. There is no default value, to be consistent with StandardSocketOptions.SO_REUSEADDR as the default value is system dependent.

    • OPTION_SO_LINGER

      public static final Option<Integer> OPTION_SO_LINGER
      The TCP socket feature to linger on close if data is present. The default is -1, meaning that it is disabled, to be consistent with StandardSocketOptions.SO_LINGER.

    • OPTION_TCP_NO_DELAY

      public static final Option<Boolean> OPTION_TCP_NO_DELAY
      The TCP socket feature to disable the Nagle algorithm; that algorithm aims to coalesce short segments and improve network efficiency. The default is FALSE, meaning that it is disabled, to be consistent with StandardSocketOptions.TCP_NODELAY.

    • OPTION_REUSE_CONNECTIONS

      public static final Option<Boolean> OPTION_REUSE_CONNECTIONS
      Specifies whether HTTP connections should be kept alive and reused for additional requests. By default, connections will be reused if possible.

    • OPTION_DISABLE_CONNECTION_STATE

      public static final Option<Boolean> OPTION_DISABLE_CONNECTION_STATE
      This option is only taken into account when OPTION_REUSE_CONNECTIONS is also set to true. Setting this to true can help with performance in the case where a client certificate is being used as it will change the Apache HTTP Client default behaviour which is to not allow connection reuse when a client certificate is being used for authentication. Since the client certificate is defined at the client level, all requests to the same target will be sharing the same client certificate so enabling this should not be an issue. This option is not enabled by default to ensure that there is still control over when it is applied. In the context of Apache HTTP Client and stateful requests:

      There are cases when HTTP connections are created with a particular user identity or within a particular security context and therefore cannot be shared with other users and can be reused by the same user only. Examples of such stateful HTTP connections are NTLM authenticated connections and SSL connections with client certificate authentication.

    • OPTION_RETRY_REQUESTS

      public static final Option<Boolean> OPTION_RETRY_REQUESTS
      Specifies whether requests should be retried if a failure is detected. By default requests will be retried.

    • OPTION_KEY_MANAGERS

      public static final Option<KeyManager[]> OPTION_KEY_MANAGERS
      Specifies the list of key managers that should be used when configuring SSL/TLS connections. By default the system key manager(s) will be used.

    • OPTION_KEY_MANAGER_FACTORY

      public static final Option<KeyManagerFactory> OPTION_KEY_MANAGER_FACTORY
      Specifies the key manager factory that should be used when configuring SSL/TLS connections.

    • OPTION_LOADER

      public static final Option<Loader> OPTION_LOADER
      The strategy which should be used for loading the HttpClientProvider. By default, the provider will be loaded using a ServiceLoader.
      See Also:

    • OPTION_MAX_CONNECTIONS

      public static final Option<Integer> OPTION_MAX_CONNECTIONS
      Specifies the maximum number of connections that should be pooled by the HTTP client. At most 64 connections will be cached by default.

    • OPTION_TEMPORARY_STORAGE

      public static final Option<Factory<Buffer>> OPTION_TEMPORARY_STORAGE
      Specifies the temporary storage that should be used for storing HTTP responses. By default IO.newTemporaryStorage() is used.

    • OPTION_TRUST_MANAGERS

      public static final Option<TrustManager[]> OPTION_TRUST_MANAGERS
      Specifies the list of trust managers that should be used when configuring SSL/TLS connections. By default the system trust manager(s) will be used.

    • OPTION_TRUST_MANAGER_FACTORY

      public static final Option<TrustManagerFactory> OPTION_TRUST_MANAGER_FACTORY
      Specifies the trust manager factory that should be used when configuring SSL/TLS connections.

    • OPTION_PROXY

      public static final Option<HttpClientHandler.ProxyInfo> OPTION_PROXY
      Specifies a proxy to use for requests by the HTTP Client.

    • OPTION_PROXY_SYSTEM

      public static final Option<Boolean> OPTION_PROXY_SYSTEM
      Specifies that the system defined proxy should be used for requests by the HTTP Client. When OPTION_PROXY is defined it takes precedence over this option. By default, no proxies are used.

    • OPTION_NON_PROXY_HOSTS

      public static final Option<List<String>> OPTION_NON_PROXY_HOSTS
      Specifies the list of hosts for which requests should not be proxied. Only used when OPTION_PROXY is also specified.

    • OPTION_POOLED_CONNECTION_TTL

      public static final Option<Long> OPTION_POOLED_CONNECTION_TTL
      Specifies the time to live (expiry time) in milliseconds of connections from the pool. By default they are set to not expire. The underlying Apache API uses a negative value to indicate no expiry.

    • OPTION_HOSTNAME_VERIFIER

      public static final Option<HttpClientHandler.HostnameVerifier> OPTION_HOSTNAME_VERIFIER
      Specifies the SSL host name verification policy. The default is strict matching.

    • OPTION_SSLCONTEXT_ALGORITHM

      public static final Option<String> OPTION_SSLCONTEXT_ALGORITHM
      SSLContext algorithm to be used when making SSL/TLS connections.

    • OPTION_SSL_ENABLED_PROTOCOLS

      public static final Option<List<String>> OPTION_SSL_ENABLED_PROTOCOLS
      List of SSL protocols to be enabled on the HttpClient. Defaults to TLSv1.3 and TLSv1.2.
      See Also:

    • OPTION_SSL_CIPHER_SUITES

      public static final Option<List<String>> OPTION_SSL_CIPHER_SUITES
      List of JSSE ciphers to be enabled on the HttpClient. Defaults to the list of ciphers supported by the Java runtime.
      See Also:

  • Constructor Details

    • HttpClientHandler

      public HttpClientHandler() throws HttpApplicationException
      Creates a new HTTP client using default client options. The returned client must be closed when it is no longer needed by the application.
      Throws:
      HttpApplicationException - If no client provider could be found.

    • HttpClientHandler

      public HttpClientHandler(Options options) throws HttpApplicationException
      Creates a new HTTP client using the provided client options. The returned client must be closed when it is no longer needed by the application.
      Parameters:
      options - The options which will be used to configure the client.
      Throws:
      HttpApplicationException - If no client provider could be found, or if the client could not be configured using the provided set of options.
      NullPointerException - If options was null.

  • Method Details

    • close

      public void close() throws IOException
      Completes all pending requests and release resources associated with underlying implementation.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - if an I/O error occurs

    • handle

      public Promise<Response,NeverThrowsException> handle(Context context, Request request)
      Sends an HTTP request to a remote server and returns a Promise representing the asynchronous response.

      Returns a Promise representing the asynchronous Response of the given request. If any (asynchronous) processing goes wrong, the promise still contains a Response (probably from the 4xx or 5xx status code family).

      A handler that doesn't hand-off the processing to another downstream handler is responsible for creating the response.

      The returned Promise contains the response returned from the server as-is. This is responsibility of the handler to produce the appropriate error response (404, 500, ...) in case of processing error.

      Note: As of Promise 2.0 implementation, it is not permitted to throw any runtime exception here. Doing so produce unexpected behaviour (most likely a server-side hang of the processing thread).

      Specified by:
      handle in interface Handler
      Parameters:
      context - The request context.
      request - The request.
      Returns:
      A Promise representing the response to be returned to the caller.