HTTPClient
Class Response

java.lang.Object
HTTPClient.Response

All Implemented Interfaces:

java.lang.Cloneable, HTTPClient.GlobalConstants, RoResponse

public final class Response

extends java.lang.Object

implements RoResponse, HTTPClient.GlobalConstants, java.lang.Cloneable

This class represents an intermediate response. It's used internally by the modules. When all modules have handled the response then the HTTPResponse fills in its fields with the data from this class.

Field Summary

static int	CD_0 Content delimiter- no body
static int	CD_CHUNKED Content delimiter - via chunked transfer encoding
static int	CD_CLOSE Content delimiter - by closing connection
static int	CD_CONTLEN Content delimiter - via the Content-Length header
static int	CD_HDRS Content delimiter - reading headers/trailers
static int	CD_MP_BR Content delimiter - via multipart/byteranges
static int	CD_NONE Content delimiter - raw read from the stream
static int	HTTP plain http
static int	HTTP_1_0 HTTP 1.0
static int	HTTP_1_1 HTTP 1.1
static int	HTTP_NG http next-generation
static int	HTTPS http on top of SSL
java.io.InputStream	inp_stream our input stream (usually from the stream demux).
static int	SHTTP secure http

Constructor Summary

Response(java.lang.String version, int status, java.lang.String reason, NVPair[] headers, byte[] data, java.io.InputStream is, int cont_len)
Create a new response with the given info.

Method Summary

java.lang.Object	clone()
void	deleteHeader(java.lang.String header) Removes a header field from the list of headers.
void	deleteTrailer(java.lang.String trailer) Removes a trailer field from the list of trailers.
byte[]	getData() Reads all the response data into a byte array.
URI	getEffectiveURI() get the final URI of the document.
java.net.URL	getEffectiveURL() Deprecated. use getEffectiveURI() instead
java.lang.String	getHeader(java.lang.String hdr) retrieves the field for a given header.
java.util.Date	getHeaderAsDate(java.lang.String hdr) retrieves the field for a given header.
int	getHeaderAsInt(java.lang.String hdr) retrieves the field for a given header.
java.io.InputStream	getInputStream() Gets an input stream from which the returned data can be read.
int	getPhysicalConnections() Accessor for the number of physical connections created for this response, should be 0 or 1 in most cases
java.lang.String	getReasonLine() give the reason line associated with the status code.
int	getStatusCode() give the status code for this request.
java.lang.String	getTrailer(java.lang.String trailer) Retrieves the field for a given trailer.
java.util.Date	getTrailerAsDate(java.lang.String trailer) Retrieves the field for a given trailer.
int	getTrailerAsInt(java.lang.String trailer) Retrieves the field for a given tailer.
java.lang.String	getVersion() get the HTTP version used for the response.
boolean	hasEntity() Some responses such as those from a HEAD or with certain status codes don't have an entity.
boolean	retryRequest()
void	setEffectiveURI(URI final_uri) set the final URI of the document.
void	setEffectiveURL(java.net.URL final_url) Deprecated. use setEffectiveURI() instead
void	setHeader(java.lang.String header, java.lang.String value) Set a header field in the list of headers.
void	setRetryRequest(boolean flag) Should the request be retried by the application? This can be used by modules to signal to the application that it should retry the request.
void	setTrailer(java.lang.String trailer, java.lang.String value) Set a trailer field in the list of trailers.

Methods inherited from class java.lang.Object

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

Field Detail

inp_stream

public java.io.InputStream inp_stream

our input stream (usually from the stream demux). Push input streams onto this if necessary.

HTTP

public static final int HTTP

plain http

See Also:

Constant Field Values

HTTPS

public static final int HTTPS

http on top of SSL

See Also:

Constant Field Values

SHTTP

public static final int SHTTP

secure http

See Also:

Constant Field Values

HTTP_NG

public static final int HTTP_NG

http next-generation

See Also:

Constant Field Values

HTTP_1_0

public static final int HTTP_1_0

HTTP 1.0

See Also:

Constant Field Values

HTTP_1_1

public static final int HTTP_1_1

HTTP 1.1

See Also:

Constant Field Values

CD_NONE

public static final int CD_NONE

Content delimiter - raw read from the stream

See Also:

Constant Field Values

CD_HDRS

public static final int CD_HDRS

Content delimiter - reading headers/trailers

See Also:

Constant Field Values

CD_0

public static final int CD_0

Content delimiter- no body

See Also:

Constant Field Values

CD_CLOSE

public static final int CD_CLOSE

Content delimiter - by closing connection

See Also:

Constant Field Values

CD_CONTLEN

public static final int CD_CONTLEN

Content delimiter - via the Content-Length header

See Also:

Constant Field Values

CD_CHUNKED

public static final int CD_CHUNKED

Content delimiter - via chunked transfer encoding

See Also:

Constant Field Values

CD_MP_BR

public static final int CD_MP_BR

Content delimiter - via multipart/byteranges

See Also:

Constant Field Values

Constructor Detail

Response

public Response(java.lang.String version,
                int status,
                java.lang.String reason,
                NVPair[] headers,
                byte[] data,
                java.io.InputStream is,
                int cont_len)

Create a new response with the given info. This is used when creating a response in a requestHandler().

If data is not null then that is used; else if the is is not null that is used; else the entity is empty. If the input stream is used then cont_len specifies the length of the data that can be read from it, or -1 if unknown.

Parameters:

version - the response version (such as "HTTP/1.1")

status - the status code

reason - the reason line

headers - the response headers

data - the response entity

is - the response entity as an InputStream

cont_len - the length of the data in the InputStream

Method Detail

getStatusCode

public final int getStatusCode()
                        throws java.io.IOException

give the status code for this request. These are grouped as follows:

• 1xx - Informational (new in HTTP/1.1)
• 2xx - Success
• 3xx - Redirection
• 4xx - Client Error
• 5xx - Server Error

Specified by:

getStatusCode in interface RoResponse

Returns:

the status code

Throws:

java.io.IOException - If any exception occurs on the socket.

getReasonLine

public final java.lang.String getReasonLine()
                                     throws java.io.IOException

give the reason line associated with the status code.

Specified by:

getReasonLine in interface RoResponse

Returns:

the reason line associated with the status code.

Throws:

java.io.IOException - If any exception occurs on the socket.

getVersion

public final java.lang.String getVersion()
                                  throws java.io.IOException

get the HTTP version used for the response.

Specified by:

getVersion in interface RoResponse

Returns:

the HTTP version returned by the server.

Throws:

java.io.IOException - If any exception occurs on the socket.

getPhysicalConnections

public int getPhysicalConnections()

Accessor for the number of physical connections created for this response, should be 0 or 1 in most cases

Returns:

number of socket connections created for this response

getEffectiveURI

public final URI getEffectiveURI()
                          throws java.io.IOException

get the final URI of the document. This is set if the original request was deferred via the "moved" (301, 302, or 303) return status.

Returns:

the new URI, or null if not redirected

Throws:

java.io.IOException - If any exception occurs on the socket.

setEffectiveURI

public void setEffectiveURI(URI final_uri)

set the final URI of the document. This is only for internal use.

getEffectiveURL

public final java.net.URL getEffectiveURL()
                                   throws java.io.IOException

Deprecated. use getEffectiveURI() instead

get the final URL of the document. This is set if the original request was deferred via the "moved" (301, 302, or 303) return status.

Throws:

java.io.IOException - If any exception occurs on the socket.

See Also:

getEffectiveURI()

setEffectiveURL

public void setEffectiveURL(java.net.URL final_url)

Deprecated. use setEffectiveURI() instead

set the final URL of the document. This is only for internal use.

See Also:

setEffectiveURI(HTTPClient.URI)

getHeader

public java.lang.String getHeader(java.lang.String hdr)
                           throws java.io.IOException

retrieves the field for a given header.

Specified by:

getHeader in interface RoResponse

Parameters:

hdr - the header name.

Returns:

the value for the header, or null if non-existent.

Throws:

java.io.IOException - If any exception occurs on the socket.

getHeaderAsInt

public int getHeaderAsInt(java.lang.String hdr)
                   throws java.io.IOException,
                          java.lang.NumberFormatException

retrieves the field for a given header. The value is parsed as an int.

Specified by:

getHeaderAsInt in interface RoResponse

Parameters:

hdr - the header name.

Returns:

the value for the header if the header exists

Throws:

java.lang.NumberFormatException - if the header's value is not a number or if the header does not exist.

java.io.IOException - if any exception occurs on the socket.

getHeaderAsDate

public java.util.Date getHeaderAsDate(java.lang.String hdr)
                               throws java.io.IOException,
                                      java.lang.IllegalArgumentException

retrieves the field for a given header. The value is parsed as a date; if this fails it is parsed as a long representing the number of seconds since 12:00 AM, Jan 1st, 1970. If this also fails an IllegalArgumentException is thrown.

Note: When sending dates use Util.httpDate().

Specified by:

getHeaderAsDate in interface RoResponse

Parameters:

hdr - the header name.

Returns:

the value for the header, or null if non-existent.

Throws:

java.io.IOException - If any exception occurs on the socket.

java.lang.IllegalArgumentException - If the header cannot be parsed as a date or time.

setHeader

public void setHeader(java.lang.String header,
                      java.lang.String value)

Set a header field in the list of headers. If the header already exists it will be overwritten; otherwise the header will be added to the list. This is used by some modules when they process the header so that higher level stuff doesn't get confused when the headers and data don't match.

Parameters:

header - The name of header field to set.

value - The value to set the field to.

deleteHeader

public void deleteHeader(java.lang.String header)

Removes a header field from the list of headers. This is used by some modules when they process the header so that higher level stuff doesn't get confused when the headers and data don't match.

Parameters:

header - The name of header field to remove.

getTrailer

public java.lang.String getTrailer(java.lang.String trailer)
                            throws java.io.IOException

Retrieves the field for a given trailer. Note that this should not be invoked until all the response data has been read. If invoked before, it will force the data to be read via getData().

Specified by:

getTrailer in interface RoResponse

Parameters:

trailer - the trailer name.

Returns:

the value for the trailer, or null if non-existent.

Throws:

java.io.IOException - If any exception occurs on the socket.

getTrailerAsInt

public int getTrailerAsInt(java.lang.String trailer)
                    throws java.io.IOException,
                           java.lang.NumberFormatException

Retrieves the field for a given tailer. The value is parsed as an int.

Specified by:

getTrailerAsInt in interface RoResponse

Parameters:

trailer - the tailer name.

Returns:

the value for the trailer if the trailer exists

Throws:

java.lang.NumberFormatException - if the trailer's value is not a number or if the trailer does not exist.

java.io.IOException - if any exception occurs on the socket.

getTrailerAsDate

public java.util.Date getTrailerAsDate(java.lang.String trailer)
                                throws java.io.IOException,
                                       java.lang.IllegalArgumentException

Retrieves the field for a given trailer. The value is parsed as a date; if this fails it is parsed as a long representing the number of seconds since 12:00 AM, Jan 1st, 1970. If this also fails an IllegalArgumentException is thrown.

Note: When sending dates use Util.httpDate().

Specified by:

getTrailerAsDate in interface RoResponse

Parameters:

trailer - the trailer name.

Returns:

the value for the trailer, or null if non-existent.

Throws:

java.lang.IllegalArgumentException - if the trailer's value is neither a legal date nor a number.

java.io.IOException - if any exception occurs on the socket.

java.lang.IllegalArgumentException - If the header cannot be parsed as a date or time.

setTrailer

public void setTrailer(java.lang.String trailer,
                       java.lang.String value)

Set a trailer field in the list of trailers. If the trailer already exists it will be overwritten; otherwise the trailer will be added to the list. This is used by some modules when they process the trailer so that higher level stuff doesn't get confused when the trailer and data don't match.

Parameters:

trailer - The name of trailer field to set.

value - The value to set the field to.

deleteTrailer

public void deleteTrailer(java.lang.String trailer)

Removes a trailer field from the list of trailers. This is used by some modules when they process the trailer so that higher level stuff doesn't get confused when the trailers and data don't match.

Parameters:

trailer - The name of trailer field to remove.

getData

public byte[] getData()
               throws java.io.IOException

Reads all the response data into a byte array. Note that this method won't return until all the data has been received (so for instance don't invoke this method if the server is doing a server push). If getInputStream() had been previously called then this method only returns any unread data remaining on the stream and then closes it.

Specified by:

getData in interface RoResponse

Returns:

an array containing the data (body) returned. If no data was returned then it's set to a zero-length array.

Throws:

java.io.IOException - If any io exception occured while reading the data

See Also:

getInputStream()

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException

Gets an input stream from which the returned data can be read. Note that if getData() had been previously called it will actually return a ByteArrayInputStream created from that data.

Specified by:

getInputStream in interface RoResponse

Returns:

the InputStream.

Throws:

java.io.IOException - If any exception occurs on the socket.

See Also:

getData()

hasEntity

public boolean hasEntity()
                  throws java.io.IOException

Some responses such as those from a HEAD or with certain status codes don't have an entity. This is detected by the client and can be queried here. Note that this won't try to do a read() on the input stream (it will however cause the headers to be read and parsed if not already done).

Returns:

true if the response has an entity, false otherwise

Throws:

java.io.IOException

Since:

V0.3-1

setRetryRequest

public void setRetryRequest(boolean flag)

Should the request be retried by the application? This can be used by modules to signal to the application that it should retry the request. It's used when the request used an HttpOutputStream and the module is therefore not able to retry the request itself. This flag is false by default.

If a module sets this flag then it must also reset() the the HttpOutputStream so it may be reused by the application. It should then also use this HttpOutputStream to recognize the retried request in the requestHandler().

Parameters:

flag - indicates whether the application should retry the request.

retryRequest

public boolean retryRequest()

Returns:

true if the request should be retried.

clone

public java.lang.Object clone()

Returns:

a clone of this request object