## HTTPClient
Class Response

    java.lang.Object
      HTTPClient.Response

All Implemented Interfaces:
  Cloneable, GlobalConstants, RoResponse

public final class Response
extends Object
implements RoResponse, GlobalConstants, 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`
`static int` `CD_CHUNKED`
`static int` `CD_CLOSE`
`static int` `CD_CONTLEN`
`static int` `CD_HDRS`
`static int` `CD_MP_BR`
`static int` `CD_NONE` Content delimiters
`(package private) int` `cd_type` this indicates how the length of the entity body is determined
`(package private) int` `ContentLength` the message length of the response if either there is no data (in which case ContentLength=0) or if the message length is controlled by a Content-Length header.
`(package private) byte[]` `Data` the data (body) returned.
`(package private) URI` `EffectiveURI` the final URI of the document.
`(package private) boolean` `final_resp` should this response be handled further?
`(package private) boolean` `got_headers` signals if we have got and parsed the headers yet
`(package private) boolean` `got_trailers` signals if we have got and parsed the trailers yet
`(package private) CIHashtable` `Headers` any headers which were received and do not fit in the above list.
`static int` `HTTP` possible http protocols we (might) handle
`static int` `HTTP_1_0` some known http versions
`static int` `HTTP_1_1`
`static int` `HTTP_NG`
`(package private) HTTPResponse` `http_resp` the HTTPResponse we're coupled with
`static int` `HTTPS`
`InputStream` `inp_stream` our input stream (usually from the stream demux).
`(package private) boolean` `isFirstResponse`
`(package private) boolean` `reading_headers` signals if we in the process of reading the headers
`(package private) String` `ReasonLine` the reason line associated with the status code.
`(package private) Request` `req`
`(package private) String` `resource` the resource in the request (for debugging purposes)
`(package private) boolean` `retry` should the request be retried by the application?
`static int` `SHTTP`
`(package private) int` `StatusCode` the status code returned.
`(package private) int` `timeout` the timeout for read operations
`(package private) CIHashtable` `Trailers` any trailers which were received and do not fit in the above list.
`(package private) boolean` `trailers_read`
`(package private) String` `Version` the HTTP version of the response.

Constructor Summary
`(package private)` `Response(Request request, boolean used_proxy, StreamDemultiplexor stream_handler)` Creates a new Response and registers it with the stream-demultiplexor.
`(package private)` `Response(Request request, InputStream is)` Creates a new Response that reads from the given stream.
`` `Response(String version, int status, String reason, NVPair[] headers, byte[] data, InputStream is, int cont_len)` Create a new response with the given info.

Method Summary
`Object` `clone()`
`void` `deleteHeader(String header)` Removes a header field from the list of headers.
`void` `deleteTrailer(String trailer)` Removes a trailer field from the list of trailers.
`(package private) int` `getContinue()` Wait for either a '100 Continue' or an error.
`byte[]` `getData()` Reads all the response data into a byte array.
`URI` `getEffectiveURI()` get the final URI of the document.
`URL` `getEffectiveURL()` Deprecated. use getEffectiveURI() instead
`String` `getHeader(String hdr)` retrieves the field for a given header.
`Date` `getHeaderAsDate(String hdr)` retrieves the field for a given header.
`int` `getHeaderAsInt(String hdr)` retrieves the field for a given header.
`InputStream` `getInputStream()` Gets an input stream from which the returned data can be read.
`String` `getReasonLine()` give the reason line associated with the status code.
`int` `getStatusCode()` give the status code for this request.
`String` `getTrailer(String trailer)` Retrieves the field for a given trailer.
`Date` `getTrailerAsDate(String trailer)` Retrieves the field for a given trailer.
`int` `getTrailerAsInt(String trailer)` Retrieves the field for a given tailer.
`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.
`(package private) void` `markAsFirstResponse(Request req)` This marks this response as belonging to the first request made over an HTTPConnection.
`(package private) void` `readTrailers(InputStream inp)` This is called by the StreamDemultiplexor to read all the trailers of a chunked encoded entity.
`boolean` `retryRequest()`
`void` `setEffectiveURI(URI final_uri)` set the final URI of the document.
`void` `setEffectiveURL(URL final_url)` Deprecated. use setEffectiveURI() instead
`void` `setHeader(String header, 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(String trailer, 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

### http_resp

    HTTPResponse http_resp

  the HTTPResponse we're coupled with

### timeout

    int timeout

  the timeout for read operations

### inp_stream

    public InputStream inp_stream

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

### resource

    String resource

  the resource in the request (for debugging purposes)

### StatusCode

    int StatusCode

  the status code returned.

### ReasonLine

    String ReasonLine

  the reason line associated with the status code.

### Version

    String Version

  the HTTP version of the response.

### EffectiveURI

    URI EffectiveURI

  the final URI of the document.

### Headers

    CIHashtable Headers

  any headers which were received and do not fit in the above list.

### Trailers

    CIHashtable Trailers

  any trailers which were received and do not fit in the above list.

### ContentLength

    int ContentLength

  the message length of the response if either there is no data (in which case ContentLength=0) or if the message length is controlled by a Content-Length header. If neither of these, then it's -1

### cd_type

    int cd_type

  this indicates how the length of the entity body is determined

### Data

    byte[] Data

  the data (body) returned.

### reading_headers

    boolean reading_headers

  signals if we in the process of reading the headers

### got_headers

    boolean got_headers

  signals if we have got and parsed the headers yet

### got_trailers

    boolean got_trailers

  signals if we have got and parsed the trailers yet

### final_resp

    boolean final_resp

  should this response be handled further?

### retry

    boolean retry

  should the request be retried by the application?

### trailers_read

    boolean trailers_read

### req

    Request req

### isFirstResponse

    boolean isFirstResponse

### HTTP

    public static final int HTTP

  possible http protocols we (might) handle

  See Also:
    Constant Field Values

### HTTPS

    public static final int HTTPS

See Also:
  Constant Field Values

### SHTTP

    public static final int SHTTP

See Also:
  Constant Field Values

### HTTP_NG

    public static final int HTTP_NG

See Also:
  Constant Field Values

### HTTP_1_0

    public static final int HTTP_1_0

  some known http versions

  See Also:
    Constant Field Values

### HTTP_1_1

    public static final int HTTP_1_1

See Also:
  Constant Field Values

### CD_NONE

    public static final int CD_NONE

  Content delimiters

  See Also:
    Constant Field Values

### CD_HDRS

    public static final int CD_HDRS

See Also:
  Constant Field Values

### CD_0

    public static final int CD_0

See Also:
  Constant Field Values

### CD_CLOSE

    public static final int CD_CLOSE

See Also:
  Constant Field Values

### CD_CONTLEN

    public static final int CD_CONTLEN

See Also:
  Constant Field Values

### CD_CHUNKED

    public static final int CD_CHUNKED

See Also:
  Constant Field Values

### CD_MP_BR

    public static final int CD_MP_BR

See Also:
  Constant Field Values

Constructor Detail

### Response

    Response(Request request,
             boolean used_proxy,
             StreamDemultiplexor stream_handler)
       throws IOException

  Creates a new Response and registers it with the stream-demultiplexor.

### Response

    Response(Request request,
             InputStream is)
       throws IOException

  Creates a new Response that reads from the given stream. This is used for the CONNECT subrequest which is used in establishing an SSL tunnel through a proxy.

Parameters:
  `request` - the subrequest
  `is` - the input stream from which to read the headers and data.

### Response

    public Response(String version,
                    int status,
                    String reason,
                    NVPair[] headers,
                    byte[] data,
                    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 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:
    `IOException` - If any exception occurs on the socket.

### getReasonLine

    public final String getReasonLine()
                               throws 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:
    `IOException` - If any exception occurs on the socket.

### getVersion

    public final String getVersion()
                            throws IOException

  get the HTTP version used for the response.

  Specified by:
    `getVersion` in interface `RoResponse`
  Returns:
    the HTTP version returned by the server.
  Throws:
    `IOException` - If any exception occurs on the socket.

### getContinue

    int getContinue()
              throws IOException

  Wait for either a '100 Continue' or an error.

  Returns:
    the return status.
  Throws:
    `IOException`

### getEffectiveURI

    public final URI getEffectiveURI()
                              throws 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:
    `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 URL getEffectiveURL()
                              throws 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:
    `IOException` - If any exception occurs on the socket.
  See Also:
    `getEffectiveURI()`

### setEffectiveURL

    public void setEffectiveURL(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 String getHeader(String hdr)
                     throws 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:
    `IOException` - If any exception occurs on the socket.

### getHeaderAsInt

    public int getHeaderAsInt(String hdr)
                       throws IOException,
                              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:
    `NumberFormatException` - if the header's value is not a number or if the header does not exist.
    `IOException` - if any exception occurs on the socket.

### getHeaderAsDate

    public Date getHeaderAsDate(String hdr)
                         throws IOException,
                                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:
    `IOException` - If any exception occurs on the socket.
    `IllegalArgumentException` - If the header cannot be parsed as a date or time.

### setHeader

    public void setHeader(String header,
                          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(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 String getTrailer(String trailer)
                      throws 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:
    `IOException` - If any exception occurs on the socket.

### getTrailerAsInt

    public int getTrailerAsInt(String trailer)
                        throws IOException,
                               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:
    `NumberFormatException` - if the trailer's value is not a number or if the trailer does not exist.
    `IOException` - if any exception occurs on the socket.

### getTrailerAsDate

    public Date getTrailerAsDate(String trailer)
                          throws IOException,
                                 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:
    `IllegalArgumentException` - if the trailer's value is neither a legal date nor a number.
    `IOException` - if any exception occurs on the socket.
    `IllegalArgumentException` - If the header cannot be parsed as a date or time.

### setTrailer

    public void setTrailer(String trailer,
                           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(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 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:
    `IOException` - If any io exception occured while reading the data
  See Also:
    `getInputStream()`

### getInputStream

    public InputStream getInputStream()
                               throws 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:
    `IOException` - If any exception occurs on the socket.
  See Also:
    `getData()`

### hasEntity

    public boolean hasEntity()
                      throws 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:
    `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.

### readTrailers

    void readTrailers(InputStream inp)
                throws IOException

  This is called by the StreamDemultiplexor to read all the trailers of a chunked encoded entity.

  Parameters:
    `inp` - the raw input stream to read from
  Throws:
    `IOException` - if any IOException is thrown by the stream

### markAsFirstResponse

    void markAsFirstResponse(Request req)

  This marks this response as belonging to the first request made over an HTTPConnection. The con and req parameters are needed in case we have to do a resend of the request - this is to handle buggy servers which barf upon receiving a request marked as HTTP/1.1 .

  Parameters:
    `req` - The Request sent

### clone

    public Object clone()

  Returns:
    a clone of this request object