ot::web
class HttpClientConnection

This class derives from ManagedObject, and is therefore reference-counted in the usual way. When all references to an instance of this class are released, the destructor calls returnToOwner() to return control of the socket connection to the HttpClientConnectionManager which created it.

This is a simple implementation of the handle/body pattern, which is employed here to help OpenTop manage persistent HTTP connections without requiring explicit support from client applications.

Generally, this class is used by the HTTP framework classes and is not of direct interest to client applications.

Since:

OpenTop 1.4

~HttpClientConnection

virtual ~HttpClientConnection()

Destructor, specifically implemented to call returnToOwner() to return the underlying socket conenction to the HttpClientConnectionManager which created it.

close

void close()

Closes the TCP/IP socket connection with the HTTP server.

getInputStream

RefPtr< InputStream > getInputStream() const

Returns an InputStream that can be used to read data from this HttpClientConnection. The stream returned is a buffered InputStream, so the application need not perform its own buffering.

Note:

This method is primarily intended for use by the HTTP framework classes, not client applications. Application which need to read the entity returned from a HTTP request will use the InputStream returned in the HttpResponse object.

See also:

HttpResponse::getInputStream()

getLastUsedDate

const DateTime& getLastUsedDate() const

Returns the date/time on which this HttpClientConnection was last used to send an HTTP request. This time is set by the HttpClientConnectionManager when the connection is returned to it via returnToOwner().

getOutputStream

RefPtr< OutputStream > getOutputStream() const

Returns an OutputStream that can be used to write data to this HttpClientConnection. The stream returned is a buffered OutputStream, so the application need not perform its own buffering and must call flush() when all the data has been written.

Note:

This method is primarily intended for use by the HTTP framework classes, not client applications. Applications which need to write an entity as part of a HTTP request will use the OutputStream returned by the interim HttpResponse object.

See also:

HttpResponse::getOutputStream()

getProtocolVersion

HttpProtocolVersion getProtocolVersion() const

Returns the version of the HTTP protocol being used for this connection. This is established by parsing response messages from the HTTP server.

getRequestCount

size_t getRequestCount() const

Returns the number of HTTP requests that have been made though this HttpClientConnection. The request count is zero-based and is incremented after a complete response is received from the server.

getServerAddress

RefPtr< InetAddress > getServerAddress() const

Returns the internet address HTTP server to which this HttpClientConnection is connected. If this HttpClientConnection is connected directly or via a proxy tunnel to an origin server, the origin server's address is returned. Otherwise, if this is a proxy connection, the address of the proxy server is returned.

getServerHostName

const String& getServerHostName() const

Returns the host name of the HTTP server to which this HttpClientConnection is connected. If this HttpClientConnection is connected directly or via a proxy tunnel to an origin server, the origin server's host name is returned. Otherwise, if this is a proxy connection, the host name of the proxy server is returned.

See also:

getServerPort()

getServerPort

int getServerPort() const

Returns the port number of the HTTP server to which this HttpClientConnection is connected. If this HttpClientConnection is a connected directly or via a proxy tunnel to an origin server, the origin server's port number is returned. Otherwise, if this is a proxy connection, the port number of the proxy server is returned.

See also:

getServerHostName()

handleResponse

void handleResponse(const HttpResponse& response)

Called by the HTTP framework classes when a new HTTP response is received over this HttpClientConnection. This method must be called in order to set properties on this client connection which can only be determined from the MIME headers contained within a server response.

isPersistent

bool isPersistent() const

Returns a flag indicating whether or not this HttpClientConnection is persistent. Persistent HTTP connections may be employed for multiple HTTP requests, thereby saving the time taken to create and tear-down TCP/IP connections.

OpenTop uses persistent connections by default unless the HttpClientConnectionManager is configured not to use persistent connections or the HTTP server to which this HttpClientConnection is connected does not support persistent connections.

Returns:

true if this HttpClientConnection is deemed persistent; false otherwise.

See also:

HttpClientConnectionManager::setUsePersistentConnections()

isProxyConnection

bool isProxyConnection() const

Returns a flag indicating whether or not this HttpClientConnection is connected to a proxy server. Connections established to an origin server via a proxy tunnel (e.g. for SSL communications) are not considered proxy connections.

Returns:

true if this HttpClientConnection is connected to a proxy server; false otherwise.

See also:

isTunnelledConnection()

isSecureConnection

bool isSecureConnection() const

Returns a flag indicating whether or not this HttpClientConnection is communicating over a SSL/TLS (secure) connection.

Returns:

true if this HttpClientConnection is secure; false otherwise.

See also:

isProxyConnection()

isTunnelledConnection

bool isTunnelledConnection() const

Returns a flag indicating whether or not this HttpClientConnection is connected to an origin server via a proxy tunnel. Proxy tunnelled connections are typically established for secure communications to an origin server where the host cannot be contacted directly due to the network topology.

Returns:

true if this HttpClientConnection is connected to an origin server via a proxy tunnel; false otherwise.

See also:

isProxyConnection()

markForClosure

void markForClosure()

Marks a persistent connection for closure when the current HTTP request has been fully processed.

See also:

isPersistent()

prepareForRequest

void prepareForRequest(const HttpRequest& request)

Prepares this HttpClientConnection for a new request. This method is called by the HTTP framework classes just before transmitting a new HTTP request over this connection. Its purpose is to allow the connection to configure itself to be consistent with the contents of the passed HttpRequest object.

If the HttpRequest contains a timeout value, the TCP/IP socket underlying this connection will be configured to timeout after the specified number of milliseconds.

returnToOwner

void returnToOwner()

Releases this HttpClientConnection and returns it to the control of the HttpClientConnectionManager which created it. In this way, this connection may be reused by a subsequent HTTP request.

Before this connection is made available for further HTTP requests, it is first quiesced to ensure that there is no pending I/O activity which would confuse subsequent users.

Once returnToOwner() has been called, the reference to this HttpClientConnection must be released and no further operations performed on it. Attempts to call member functions after returnToOwner() will result in a RuntimeException being thrown.

See also:

HttpClientConnectionManager::getConnection()