ot::web
class HttpResponse

The main difference between and interim and a final HttpResponse if that the former contains an OutputStream for the application to stream an entity to the HTTP server, whereas the latter contains the actual response from the server including a response line, MIME headers and an InputStream object when the request results in an entity being delivered to the client.

Applications can differentiate between the two kinds of HttpResponse via the isRequestInProgress() method. This returns true for interim responses and false for final responses.

Resource Management

An HTTP request normally involves the use of a TCP/IP socket connection to a remote server. This connection remains allocated to the application until the InputStream contained within a final response is closed or read to EndOFFile.

If the HttpResponse contains an entity which is not required by the application, and the application wishes to be able to reuse the physical network connection, then it is recommended to call discardEntity(), which will reset and free the HttpClientConnection for re-use by other requests. This action is not required if the application will read the entire entity or if no entity is returned from the HTTP server.

If the application closes the InputStream (by calling the close() method) before reaching EndOfFile, the HTTP request is terminated by physically closing the network connection. This action will obviously prevent the network connection from being re-used by subsequent requests.

See also:

HttpClient , HttpRequest

Since:

OpenTop 1.4

HttpResponse

 HttpResponse()

Default constructor.

HttpResponse

 HttpResponse(const HttpRequest& request)

Constructor taking a HttpRequest argument. This constructs a new HttpResponse with the fields initialized to values from the passes request.

clearResponseInfo

void clearResponseInfo()

Clears the response code, response message and MIME headers.

discardEntity

void discardEntity()

Provides a means for the application to release resources associated with this HttpResponse if the contained entity (InputStream) is not required. This method may block while data is read from the network stream in order to position the stream at the next logical entity.

getFinalURL

const URL& getFinalURL() const

Returns the URL representing the HTTP request that generated this HttpResponse. This URL may differ from the URL contained within the HttpRequest created by the application due to HTTP redirection processing.

See also:

setFinalURL()

getInputStream

RefPtr< InputStream > getInputStream() const

Returns an InputStream which can be used to read the entity associated with this HTTP response (if any). Most HTTP responses do contain an entity, even if the entity sometimes has a length of zero. Section 4.3 [Message Body] of RFC 2616 specifies the rules for for when a response message contains an entity.

Returns:

An InputStream or a null RefPtr if this HTTP response does not include an entity.

Note:

If an InputStream is present, the stream must be read until EndOfFile or discarded before the HTTP connection over which the HTTP request was sent will be released and possibly reused for further HTTP requests. If the application does not need the entity, or cannot guarantee that the InputStream will be completely read to EndOFFile, then discardEntity() method should be called when it is no longer required.

See also:

discardEntity()

getMimeHeaders

RefPtr< MimeHeaderSequence > getMimeHeaders() const

Returns the sequence of MIME-type headers that accompany this HTTP response.

getOutputStream

RefPtr< OutputStream > getOutputStream() const

Returns an OutputStream which can be used by the application to write an entity to the remote HTTP server. The returned OutputStream reference will be null if this HttpResponse is not an interim response for an in-progress HTTP request.

See also:

isRequestInProgress()

getProtocolVersion

HttpProtocolVersion getProtocolVersion() const

Returns a HttpProtocolVersion representing the version of the HTTP protocol contained within the HTTP response line.

getRequestMethod

const String& getRequestMethod() const

Returns the method from the HttpRequest used to generate this response.

See also:

HttpRequest::getMethod()

getResponseCode

int getResponseCode() const

Returns the numeric response code portion of the HTTP response line. See ot::net::HttpURLConnection for a list of valid response code values.

getResponseLine

const String& getResponseLine() const

Returns the entire HTTP response line as a String.

See also:

setResponseLine()

getResponseMessage

const String& getResponseMessage() const

Returns the message portion of the HTTP response line.

isRequestInProgress

bool isRequestInProgress() const

Tests if this HttpResponse is an interim response for a HTTP request that is still in progress. An interim response is returned to the application when an HTTP request contains an entity that must be streamed to the HTTP server. When the application has finished sending the entity, this response should be used to

Returns:

true is this is an interim response; false otherwise

setFinalURL

void setFinalURL(const URL& url)

Sets the URL representing the HTTP request that generated this HttpResponse. This URL may differ from the URL contained within the HttpRequest created by the application due to HTTP redirection processing.

Parameters:

url - the URL of the request.

See also:

getFinalURL()

setInputStream

void setInputStream(InputStream* pInputStream)

Sets the InputStream for this HttpResponse.

Parameters:

pInputStream - a pointer to an InputStream or null.

setMimeHeaders

void setMimeHeaders(MimeHeaderSequence* pHeaders)

Sets the MimeHeaderSequence used by this HttpResponse to store the HTTP response headers.

Parameters:

pHeaders - a pointer to a MimeHeaderSequence.

Exceptions:

NullPointerException - if pHeader is null.

setRequestDetails

void setRequestDetails(const HttpRequest& request)

Sets the method and url fields from the passed request argument.

setRequestInProgress

void setRequestInProgress(HttpClientConnection* pConnection,
                          OutputStream* pOutputStream)

Marks this HttpResponse as an interim response, used by the application to stream an entity to the remote HTTP server.

Parameters:

pConnection - a pointer to the HttpClientConnection used to process the in-progress request.
pOutputStream - a pointer to the OutputStream which will be returned to the application for streaming the entity.

setRequestMethod

void setRequestMethod(const String& method)

Sets the request method (e.g. "POST" or "GET") which was used to generate this HttpResponse.

Parameters:

method - the method.

setResponseLine

void setResponseLine(const String& responseLine)

Sets the protocol version, response code and response message from the first response line from a HTTP server. The response line should be in the form:-

    HTTP/v.v nnn [message]

Where v.v is the HTTP version and nnn is the response code.

Parameters:

responseLine - the response received from a HTTP request.