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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	HttpClientHandler.HostnameVerifier SSL host name verification policies.
static class	HttpClientHandler.ProxyInfo Encapsulates the details of the proxy if one is required when making outgoing requests.

Field Summary

Fields

Modifier and Type	Field and Description
static Option<Duration>	OPTION_CONNECT_TIMEOUT The TCP connect timeout for new HTTP connections.
static Option<Boolean>	OPTION_DISABLE_CONNECTION_STATE This option is only taken into account when OPTION_REUSE_CONNECTIONS is also set to true.
static Option<HttpClientHandler.HostnameVerifier>	OPTION_HOSTNAME_VERIFIER Specifies the SSL host name verification policy.
static Option<KeyManager[]>	OPTION_KEY_MANAGERS Specifies the list of key managers that should be used when configuring SSL/TLS connections.
static Option<Loader>	OPTION_LOADER The strategy which should be used for loading the HttpClientProvider.
static Option<Integer>	OPTION_MAX_CONNECTIONS Specifies the maximum number of connections that should be pooled by the HTTP client.
static Option<Long>	OPTION_POOLED_CONNECTION_TTL Specifies the time to live (expiry time) in milliseconds of connections from the pool.
static Option<HttpClientHandler.ProxyInfo>	OPTION_PROXY Specifies a proxy to use for requests by the HTTP Client.
static Option<Boolean>	OPTION_PROXY_SYSTEM Specifies that the system defined proxy should be used for requests by the HTTP Client.
static Option<Boolean>	OPTION_RETRY_REQUESTS Specifies whether requests should be retried if a failure is detected.
static Option<Boolean>	OPTION_REUSE_CONNECTIONS Specifies whether HTTP connections should be kept alive and reused for additional requests.
static Option<Duration>	OPTION_SO_TIMEOUT The TCP socket timeout when waiting for HTTP responses.
static Option<List<String>>	OPTION_SSL_CIPHER_SUITES List of JSSE ciphers to be enabled on the HttpClient.
static Option<List<String>>	OPTION_SSL_ENABLED_PROTOCOLS List of SSL protocols to be enabled on the HttpClient.
static Option<String>	OPTION_SSLCONTEXT_ALGORITHM SSLContext algorithm to be used when making SSL/TLS connections.
static Option<Factory<Buffer>>	OPTION_TEMPORARY_STORAGE Specifies the temporary storage that should be used for storing HTTP responses.
static Option<TrustManager[]>	OPTION_TRUST_MANAGERS Specifies the list of trust managers that should be used when configuring SSL/TLS connections.

Constructor Summary

Constructors

Constructor and Description
HttpClientHandler() Creates a new HTTP client using default client options.
HttpClientHandler(Options options) Creates a new HTTP client using the provided client options.

Method Summary

Modifier and Type	Method and Description
void	close() Completes all pending requests and release resources associated with underlying implementation.
Promise<Response,NeverThrowsException>	handle(Context context, Request request) Sends an HTTP request to a remote server and returns a Promise representing the asynchronous response.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

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_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_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:

Loader.SERVICE_LOADER

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_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_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 the list of SSL protocols supported by the Java runtime.

See Also:

JDK 7 Supported Protocols

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:

JDK 7 Cipher Suite Names

Constructor Detail

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 Detail

close

public void close()
           throws IOException

Completes all pending requests and release resources associated with underlying implementation.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

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.