org.forgerock.openig.handler

Class ClientHandler

java.lang.Object

org.forgerock.openig.handler.ClientHandler

All Implemented Interfaces:

Handler

public class ClientHandler
extends Object
implements Handler

Submits requests to remote servers. In this implementation, requests are dispatched through a CHF HttpClient.

   
   {
     "name": "ClientHandler",
     "type": "ClientHandler",
     "config": {
       "connections": 64,
       "disableReuseConnection": true,
       "stateTrackingEnabled": true,
       "hostnameVerifier": "ALLOW_ALL",
       "soTimeout": "10 seconds",
       "connectionTimeout": "10 seconds",
       "connectionTimeToLive": "30 seconds",
       "numberOfWorkers": 6,
       "proxy" : {
           "uri": "http://proxy:3128",
           "username": "proxyuser",
           "passwordSecretId": "password.secret.id"
       },
       "temporaryStorage": {reference to or inline declaration of a TemporaryStorage},
       "asyncBehavior": "streaming" or "non_streaming",
       "tls": {
           "type": "TlsOptions",
           "config": {
               "sslContextAlgorithm": "TLS",
               "keyManager": [ "RefToKeyManager", ... ],
               "trustManager": [ "RefToTrustManager", ... ],
               "sslEnabledProtocols": [ "SSLv2", ... ],
               "sslCipherSuites": [ "TLS_DH_anon_WITH_AES_256_CBC_SHA256", ... ],
           }
       }
       "retries": {
           "enabled": true,
           "executor" "ScheduledExecutorService",
           "count: "5",
           "delay: "10 seconds"
       },
       "websocket": {
           "enabled": false,
           "soTimeout: "10 seconds",
           "connectionTimeout": "10 seconds",
           "tls": "RefToTlsOptions"
       }
     }
   }
   
 

Note: This implementation verifies hostnames for outgoing SSL connections by default. If this gateway access the SSL endpoint using a raw IP address rather than a fully-qualified hostname, then you need to configure hostnameVerifier to ALLOW_ALL.
Accepted values are:

• STRICT (the default)
• ALLOW_ALL

The soTimeout optional attribute specifies a socket timeout (the given amount of time a connection will live before being considered a stalled and automatically destroyed). It defaults to 10 seconds.
The connectionTimeout optional attribute specifies a connection timeout (the given amount of time to wait until the connection is established). It defaults to 10 seconds. *
The connectionTimeToLive optional attribute specifies a connection time-to-live (the amount of time before a reusable pooled connection expires). It defaults to never expiring. An example of where changing this from the default so connections from the pool expire would be where ClientHandler connections to an application go through a load-balancer and the load-balancer's IP address has changed due to resource changes so new connections should end up at the new IP based on underlying DNS updates.

The numberOfWorkers optional attribute specifies the number of threads dedicated to process outgoing requests. It defaults to the number of CPUs available to the JVM. This attribute is only used if an asynchronous Http client engine is used (that is the default).

The proxy optional attribute specifies a http(s) proxy server to use for any outgoing requests. Within the proxy configuration:

• The uri is a required item and if a username or password is specified then both username and passwordSecretId(or password) are required.
• passwordSecretId: a label of a Purpose, required to read the GenericSecret required to authenticate the client.
• password: [Deprecated since 6.5 in favor of passwordSecretId]. See above.

The systemProxy optional boolean attribute if true, specifies to use the system defined proxy for any outgoing requests. If both proxy and systemProxy are defined, proxy takes precedence.

The asyncBehavior optional attribute specifies how the HTTP client should behave with regard to asynchronous responses.

• streaming: response is processed as soon as all headers have been received (entity content is downloaded in a background thread). May lead to thread starvation issue, but is mandatory for SSE and very large file support
• non_streaming: response is processed when the entity content is entirely available, latency is higher but thread starvation will not happen. Does not support SSE or very large files (more than 2GB).

The retries optional attribute, if enabled, will retry the failed request a number of times, each separated by a delay. It is disabled by default, unless the retries attribute is provided, and its enabled setting not set to false (defaults to true).

The websocket optional attribute, if present gives access to Web Socket specific configuration options. It's disabled by default, and if the inner attributes are not valued, they default to the corresponding attribute's value in the ClientHandler configuration (/websocket/soTimeout -> /soTimeout for instance).

See Also:

Duration, KeyManagerHeaplet, TrustManagerHeaplet

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ClientHandler.Heaplet Creates and initializes a client handler in a heap environment.

Constructor Summary

Constructors

Constructor and Description
ClientHandler(Handler delegate) Creates a new client handler.

Method Summary

Modifier and Type	Method and Description
Promise<Response,NeverThrowsException>	handle(Context context, Request request) Returns a Promise representing the asynchronous Response of the given request.

Methods inherited from class java.lang.Object

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

Constructor Detail

ClientHandler

public ClientHandler(Handler delegate)

Creates a new client handler.

Parameters:

delegate - The HTTP Handler delegate.

Method Detail

handle

public Promise<Response,NeverThrowsException> handle(Context context,
                                                     Request request)

Description copied from interface: Handler

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.