ot::web
class HttpClientConnectionManager

The HttpClientConnectionManager is primarily a repository of idle TCP/IP connections to HTTP servers (both origin and proxy servers). It also contains configuration options specifying such things as the proxy server to use and whether or not to make use of persistent HTTP connections.

When an instance of the HttpClient class needs to service a HTTP request, it asks its HttpClientConnectionManager for a connection to the appropriate host, which responds with either a new TCP/IP connection or an existing idle connection if a suitable one already exists.

When the application has completed the HTTP request/response conversation, it returns the connection back to the HttpClientConnectionManager. The HttpClientConnectionManager retains connections returned to it in a cache of idle connections, but only if the returned connections are persistent and the connection manager has been configured to make use of persistent conections.

Socket creation

The application can control how sockets are created by registering custom socket factories.

Idle connection management

The HttpClientConnectionManager provides two functions for managing the idle connection pool: manageIdleConnections() and manageClosedConnections(). In a process termed passive connection management, these functions are called automatically whenever a new HTTP connection is requested.

Sometimes it is insufficient for OpenTop to manage idle connections only when a new connection is required. For example, many HTTP servers employ a timeout mechanism where they close connections which haven't been used for a preset amount of time. In order for the network resources associated with these zombie connections to be released, the client side of the socket needs to be closed also. This is what happens when manageClosedConnections() is called, but this may occur some time after the server has closed its side of the connection.

The corollary to the above is when OpenTop decides that a connection has been idle for too long, even though the server appears content to leave it open. Connections that fall into this category are closed by the manageIdleConnections() function.

Applications are free to actively call these two connection management functions themselves (perhaps within an idle processing loop), or they may make use of OpenTop's active connection management by invoking enableActiveConnectionManagement(), which is available within the multi-threaded build of OpenTop.

The following example shows how an application can configure the global HttpClientConnectionManager to use active connection management:-

    #include "ot/web/HttpClientConnectionManager.h"
    #include "ot/base/SystemMonitor.h"
    #include <iostream>
    using namespace ot;
    using namespace ot::web;
    using namespace std;

    int main(int argc, char* argv[])
    {
        SystemMonitor monitor;
        try
        {
            //
            // enable active connection management for OpenTop's HTTP implementation
            //
            HttpClientConnectionManager::GetConnectionManager()->enableActiveConnectionManagement(true);

            //
            // Now perform a long-running task containing HTTP processing,
            // safe in the knowledge that HTTP client connections will be managed effectively
            doStuff();
        }
        catch(Exception& e)
        {
            cerr << e.toString() << endl;
        }
        return 0;
    }

See also:

HttpClient , HttpClientConnection

Since:

OpenTop 1.4

HttpClientConnectionManager

 HttpClientConnectionManager()

Default constructor that configures a new HttpClientConnectionManager using default settings. If the system property http.proxySet is set to true, default values for the proxy server and port are read from the http.proxyHost and http.proxyPort system properties respectively. These values may be configured on a per-instance basis using the setProxy() mehod.

See also:

System::SetProperty()

HttpClientConnectionManager

 HttpClientConnectionManager(const HttpClientConnectionManager& rhs)

Copy constructor that configures a new HttpClientConnectionManager using the settings (but not the idle connections) from an existing HttpClientConnectionManager.

Parameters:

rhs - the existing HttpClientConnectionManager object to copy.

~HttpClientConnectionManager

 ~HttpClientConnectionManager()

Destructor. When a HttpClientConnectionManager is destroyed, all network and system resources (including idle persistent HTTP connections which it created) are released.

enableActiveConnectionManagement

void enableActiveConnectionManagement(bool bEnable,
                                      size_t sleepInterval)

Configures active connection management for this HttpClientConnectionManager. Active connection management is implemented by the creation of a worker thread which enters a processing loop where it alternately sleeps for a while then calls the connection management functions:- manageIdleConnections() and manageClosedConnections().

Parameters:

bEnable - set to true to enable active connection management for this HttpClientConnectionManager; false to disable it.
sleepInterval - specifies the number of seconds the worker thread should sleep between each cycle. A value of zero causes OpenTop to use a reasonable default value.

Exceptions:

UnsupportedOperationException - in single-threaded versions of OpenTop.

See also:

isActiveConnectionManagementEnabled()

getConnection

virtual RefPtr< HttpClientConnection > getConnection(const String& hostName,
                                                     int port,
                                                     bool bSecure,
                                                     HttpProtocolVersion version,
                                                     size_t timeoutMS)

Returns a HttpClientConnection for the specified host and port number. If persistent connections are being used, and an existing connection is available for reuse, the existing connection will be rerturned; otherwise a new TCP/IP connection will be established.

Parameters:

hostName - the name of the peer network host to connect with.
port - the number of the port on the peer network host.
bSecure - true if this request is for a SSL connection; false otherwise.
timeoutMS - the maximum time (in milliseconds) to wait for a new connection to be established.

Exceptions:

SocketException - if an error occurs connecting to the remote host.
SocketTimeoutException - if timeoutMS milliseconds elapses before a new connection is successfully established.
UnknownHostException - if hostName cannot be resolved into an Internet address.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

GetDefault

static RefPtr< HttpClientConnectionManager > GetDefault()

Returns a reference to the global default HttpClientConnectionManager object. If a default HttpClientConnectionManager has not yet been registered then a new instance is automatically created.

See also:

SetDefault()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

getHostnameVerifier

RefPtr< HostnameVerifier > getHostnameVerifier() const

Returns the HostnameVerifier which will be used to verify SSL connections where the server's certificate does not match the host name of the remote HTTP server. If a HostnameVerifier has not been provided by the application, then a null RefPtr<> is returned.

See also:

setHostnameVerifier()

getIdleConnectionTimeout

size_t getIdleConnectionTimeout() const

Returns the number of seconds that may elapse before an idle HTTP connection with an origin server is considered stale. Stale connections are released when manageIdleConnections() or getConnection() is called.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

See also:

manageIdleConnections() , setIdleConnectionTimeout()

getIdleProxyConnectionTimeout

size_t getIdleProxyConnectionTimeout() const

Returns the number of seconds that may elapse before an idle HTTP connection with a proxy server is considered stale. Stale connections are released when manageIdleConnections() or getConnection() is called.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

See also:

manageIdleConnections() , setIdleProxyConnectionTimeout()

getProxyForHost

protected virtual bool getProxyForHost(const String& hostName,
                                       bool bSecure,
                                       String& proxyHost,
                                       int& proxyPort)

Virtual function called before allocating a TCP/IP connection to process a HTTP request. This function is responsible for deciding if a proxy server should be used to communicate with the origin server and, if so, the host name and port number of the proxy server to use.

Parameters:

hostName - The name of the host which is being contacted. This is taken from the URL which was used to generate the HTTP request, and may be a host name or a 'dotted' IP address.
bSecure - Flag set to true if this is a secure (HTTPS) request; false otherwise.
proxyHost - return parameter containing the name of the proxy host to use for the HTTP request. This is only set when true is returned from the function.
proxyPort - return parameter containing the port number on the proxy host to use fir the HTTP request. This is only set when true is returned from the function.

Returns:

true if a proxy server has been allocated and the return parameters populated; false otherwise.

getSocketFactory

RefPtr< SocketFactory > getSocketFactory() const

Returns the SocketFactory that will be used by this connection manager when creating standard (insecure) connections with HTTP servers.

See also:

setSocketFactory()

getSSLSocketFactory

RefPtr< SSLSocketFactory > getSSLSocketFactory() const

Returns the SSLSocketFactory that will be used by this connection manager to create secure connections with HTTP servers. If a SSLSocketFactory has not already been assigned to this HttpClientConnectionManager then a new one will be created by calling SSLSocketFactory::GetDefault()

Exceptions:

UnsupportedOperationException - if OpenTop has been built without support for a built-in SSL provider such as OpenSSL, and the application has not provided a custom default.

See also:

setSSLSocketFactory()

getUsePersistentConnections

bool getUsePersistentConnections() const

Returns a flag indicating whether this HttpClientConnectionManager will make use of persistent HTTP connections (also known as keep-alive connections).

Returns:

true if persistent connections will be used; false otherwise.

See also:

setUsePersistentConnections()

isActiveConnectionManagementEnabled

bool isActiveConnectionManagementEnabled() const

Returns a flag indicating whether active connection management is enabled for this HttpClientConnectionManager.

Returns:

true if active connection management is enabled; false otherwise.

See also:

enableActiveConnectionManagement

makeAvailable

protected virtual void makeAvailable(HttpClientConnection* pConnection)

Called by a client of this HttpClientConnectionManager when it has finished using a HttpClientConnection. If the HttpClientConnection is a persistent connection and is deemed to still be useful, it will be saved for possible use by future HTTP requests.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

manageClosedConnections

virtual void manageClosedConnections()

Removes persistent TCP/IP connections from the free pool which have been closed by the remote HTTP server. This function should be called on a regular basis to ensure that connections which have been closed remotely are freed and the associated network resources released.

In the multi-threaded build of OpenTop, this method can be called automatically by a background thread by enabling active connection management.

See also:

manageIdleConnections() , enableActiveConnectionManagement()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

manageIdleConnections

virtual void manageIdleConnections()

Manages the pool of persistent TCP/IP connections which are currently idle. This function should be called on a regular basis to ensure that persistent connections which have been idle for longer than the relevant timeout limit are closed and the associated network resources released.

In the multi-threaded build of OpenTop, this method can be called automatically by a background thread by enabling active connection management.

See also:

manageClosedConnections() , enableActiveConnectionManagement()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

SetDefault

static void SetDefault(HttpClientConnectionManager* pConnectionManager)

Sets the global default HttpClientConnectionManager object. The global default instance is used to create and manage HttpClientConnections when a specific instance is not provided by the application.

To ensure that the passed object exists for as long as the application needs it, the HttpClientConnectionManager object is registered with the system's ObjectManager which holds a (counted) reference to it until system termination.

See also:

GetDefault()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

setHostnameVerifier

void setHostnameVerifier(HostnameVerifier* pVerifier)

Set the HostnameVerifier object which will be used whenever new SSL sessions are established with a HTTP server whose certificate does not match the hostname contained within the URL. OpenTop performs the standard hostname matching which is described in RFC2818.

Parameters:

pVerifier - a pointer to a HostnameVerifier, or null. If a valid pointer is passed, its reference count will be incremented and its value saved for use whenever a new connection must be established.

See also:

getHostnameVerifier()

setIdleConnectionTimeout

void setIdleConnectionTimeout(size_t secs)

Configures the number of seconds that may elapse before an idle HTTP connection with an origin server is considered stale. Stale connections are released when manageIdleConnections() or getConnection() is called.

A value of zero indicates that no timeout will occur.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

See also:

manageIdleConnections() , getIdleConnectionTimeout()

setIdleProxyConnectionTimeout

void setIdleProxyConnectionTimeout(size_t secs)

Configures the number of seconds that may elapse before an idle HTTP connection with a proxy server is considered stale. Stale connections are released when manageIdleConnections() or getConnection() is called.

A value of zero indicates that no timeout will occur.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

See also:

manageIdleConnections() , getIdleProxyConnectionTimeout()

setProxy

void setProxy(const String& proxyHost,
              int proxyPort)

Sets a HTTP proxy server to be used for connections originated by this HttpClientConnectionManager.

Parameters:

proxyHost - the hostname of the HTTP proxy server. Setting this value to an empty string disables proxy connection processing for this HttpClientConnectionManager.
proxyPort - the port number of the HTTP proxy server.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

setSocketFactory

void setSocketFactory(SocketFactory* pFactory)

Sets the SocketFactory that will be used by this connection manager when creating standard (insecure) connections with HTTP servers. If a null SocketFactory pointer is provided, the default SocketFactory will be used.

Parameters:

pFactory - a pointer to an instance of SocketFactory or null.

See also:

getSocketFactory()

setSSLSocketFactory

void setSSLSocketFactory(SSLSocketFactory* pFactory)

Sets the SSLSocketFactory that will be used by this connection manager when creating secure (SSL) connections with HTTP servers. If a null SSLSocketFactory pointer is provided, the default SSLSocketFactory (if one is available) will be used.

Parameters:

pFactory - a pointer to an instance of SSLSocketFactory or null.

See also:

getSSLSocketFactory()

setUsePersistentConnections

void setUsePersistentConnections(bool bUsePersistentConnections)

Configures this HttpClientConnectionManager to use persistent HTTP connections (also known as keep-alive connections) where possible. If persistent connections are currently being used and bUsePersistentConnections is set to false, any idle persistent connections being managed by this HttpClientConnectionManager will be released immediately.

Parameters:

bUsePersistentConnections - true to configure this HttpClientConnectionManager to use persistent connections; false otherwise.

useProxyForHost

protected virtual bool useProxyForHost(const String& hostName)

Virtual function called by the default implementation of getPRoxyForHost() when deciding whether to use a proxy server to contact a HTTP origin server. By default a proxy server is not used for connecting to the local host.

Parameters:

hostName - The name of the host which is being contacted. This is taken from the URL which was used to generate the HTTP request, and may be a host name or a 'dotted' IP address.

Returns:

true if a proxy server should be used; false otherwise.

See also:

getProxyForHost()