## HTTPClient
Class HTTPResponse

    java.lang.Object
      HTTPClient.HTTPResponse

All Implemented Interfaces:
  HTTPClientModuleConstants

public class HTTPResponse
extends Object
implements HTTPClientModuleConstants

This defines the http-response class returned by the requests. It's basically a wrapper around the Response class which first lets all the modules handle the response before finally giving the info to the user.

Since:
  0.3

Field Summary
`(package private) Response` `response` the current response

Fields inherited from interface HTTPClient.HTTPClientModuleConstants
`REQ_CONTINUE, REQ_NEWCON_RST, REQ_NEWCON_SND, REQ_RESPONSE, REQ_RESTART, REQ_RETURN, REQ_SHORTCIRC, RSP_CONTINUE, RSP_NEWCON_REQ, RSP_NEWCON_SND, RSP_REQUEST, RSP_RESTART, RSP_SEND, RSP_SHORTCIRC`

Constructor Summary
`(package private)` `HTTPResponse(HTTPClientModule[] modules, int timeout, Request orig)` Creates a new HTTPResponse.

Method Summary
`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 value for a given header.
`Date` `getHeaderAsDate(String hdr)` Retrieves the value for a given header.
`int` `getHeaderAsInt(String hdr)` Retrieves the value for a given header.
`InputStream` `getInputStream()` Gets an input stream from which the returned data can be read.
`(package private) HTTPClientModule[]` `getModules()`
`URI` `getOriginalURI()` Get the original URI used in the request.
`String` `getReasonLine()` Give the reason line associated with the status code.
`String` `getServer()` Deprecated. This method is a remnant of V0.1; use `getHeader("Server")` instead.
`int` `getStatusCode()` Give the status code for this request.
`String` `getText()` Reads all the response data into a buffer and turns it into a string using the appropriate character converter.
`(package private) int` `getTimeout()`
`String` `getTrailer(String trailer)` Retrieves the value for a given trailer.
`Date` `getTrailerAsDate(String trailer)` Retrieves the value for a given trailer.
`int` `getTrailerAsInt(String trailer)` Retrieves the value for a given tailer.
`String` `getVersion()` Get the HTTP version used for the response.
`(package private) boolean` `handleResponse()` Processes a Response.
`(package private) void` `init(Response resp)` Copies the relevant fields from Response and marks this as initialized.
`(package private) void` `invokeTrailerHandlers(boolean force)` This is invoked by the RespInputStream when it is close()'d.
`Enumeration` `listHeaders()` Returns an enumeration of all the headers available via getHeader().
`Enumeration` `listTrailers()` Returns an enumeration of all the trailers available via getTrailer().
`(package private) void` `markAborted()` Mark this request as having been aborted.
`boolean` `retryRequest()` Should the request be retried by the application? If the application used an HttpOutputStream in the request then various modules (such as the redirection and authorization modules) are not able to resend the request themselves.
`(package private) void` `set(Request req, HttpOutputStream out_stream)`
`(package private) void` `set(Request req, Response resp)`
`String` `toString()` produces a full list of headers and their values, one per line.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### response

    Response response

  the current response

Constructor Detail

### HTTPResponse

    HTTPResponse(HTTPClientModule[] modules,
                 int timeout,
                 Request orig)

  Creates a new HTTPResponse.

Parameters:
  `modules` - the list of modules handling this response
  `timeout` - the timeout to be used on stream read()'s

Method Detail

### set

    void set(Request req,
             Response resp)

  Parameters:
    `req` - the request
    `resp` - the response

### set

    void set(Request req,
             HttpOutputStream out_stream)

  Parameters:
    `req` - the request

### getStatusCode

    public final int getStatusCode()
                            throws IOException,
                                   ModuleException

  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

  Throws:
    `IOException` - if any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.

### getReasonLine

    public final String getReasonLine()
                               throws IOException,
                                      ModuleException

  Give the reason line associated with the status code.

  Throws:
    `IOException` - If any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.

### getVersion

    public final String getVersion()
                            throws IOException,
                                   ModuleException

  Get the HTTP version used for the response.

  Throws:
    `IOException` - If any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.

### getServer

    public final String getServer()
                           throws IOException,
                                  ModuleException

  Deprecated. This method is a remnant of V0.1; use `getHeader("Server")` instead.

  Get the name and type of server.

  Throws:
    `IOException` - If any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.
  See Also:
    `getHeader(java.lang.String)`

### getOriginalURI

    public final URI getOriginalURI()

  Get the original URI used in the request.

  Returns:
    the URI used in primary request

### getEffectiveURL

    public final URL getEffectiveURL()
                              throws IOException,
                                     ModuleException

  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.

  Returns:
    the effective URL, or null if no redirection occured
  Throws:
    `IOException` - If any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.
  See Also:
    `getEffectiveURI()`

### getEffectiveURI

    public final URI getEffectiveURI()
                              throws IOException,
                                     ModuleException

  Get the final URI of the document. If the request was redirected via the "moved" (301, 302, 303, or 307) return status this returns the URI used in the last redirection; otherwise it returns the original URI.

  Returns:
    the effective URI
  Throws:
    `IOException` - If any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.

### getHeader

    public String getHeader(String hdr)
                     throws IOException,
                            ModuleException

  Retrieves the value for a given header.

  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.
    `ModuleException` - if any module encounters an exception.

### getHeaderAsInt

    public int getHeaderAsInt(String hdr)
                       throws IOException,
                              ModuleException,
                              NumberFormatException

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

  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.
    `ModuleException` - if any module encounters an exception.

### getHeaderAsDate

    public Date getHeaderAsDate(String hdr)
                         throws IOException,
                                IllegalArgumentException,
                                ModuleException

  Retrieves the value 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 exception is thrown.
  Note: When sending dates use Util.httpDate().

  Parameters:
    `hdr` - the header name.
  Returns:
    the value for the header, or null if non-existent.
  Throws:
    `IllegalArgumentException` - if the header's value is neither a legal date nor a number.
    `IOException` - if any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.

### listHeaders

    public Enumeration listHeaders()
                            throws IOException,
                                   ModuleException

  Returns an enumeration of all the headers available via getHeader().

  Throws:
    `IOException` - If any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.

### getTrailer

    public String getTrailer(String trailer)
                      throws IOException,
                             ModuleException

  Retrieves the value for a given trailer. This should not be invoked until all response data has been read. If invoked before it will call `getData()` to force the data to be read.

  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.
    `ModuleException` - if any module encounters an exception.
  See Also:
    `getData()`

### getTrailerAsInt

    public int getTrailerAsInt(String trailer)
                        throws IOException,
                               ModuleException,
                               NumberFormatException

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

  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.
    `ModuleException` - if any module encounters an exception.

### getTrailerAsDate

    public Date getTrailerAsDate(String trailer)
                          throws IOException,
                                 IllegalArgumentException,
                                 ModuleException

  Retrieves the value 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().

  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.
    `ModuleException` - if any module encounters an exception.

### listTrailers

    public Enumeration listTrailers()
                             throws IOException,
                                    ModuleException

  Returns an enumeration of all the trailers available via getTrailer().

  Throws:
    `IOException` - If any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.

### getData

    public byte[] getData()
                   throws IOException,
                          ModuleException

  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 invoked then this method only returns any unread data remaining on the stream and then closes it.

  Note to the unwary: code like

           System.out.println("The data: " + resp.getData())

  will probably not do what you want - use

           System.out.println("The data: " + resp.getText())

  instead.

  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
    `ModuleException` - if any module encounters an exception.
  See Also:
    `getInputStream()`

### getText

    public String getText()
                   throws IOException,
                          ModuleException,
                          ParseException

  Reads all the response data into a buffer and turns it into a string using the appropriate character converter. Since this uses `getData()`, the caveats of that method apply here as well.

  Returns:
    the body as a String. If no data was returned then an empty string is returned.
  Throws:
    `IOException` - If any io exception occured while reading the data, or if the content is not text
    `ModuleException` - if any module encounters an exception.
    `ParseException` - if an error occured trying to parse the content-type header field
  See Also:
    `getData()`

### getInputStream

    public InputStream getInputStream()
                               throws IOException,
                                      ModuleException

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

  Returns:
    the InputStream.
  Throws:
    `IOException` - If any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.
  See Also:
    `getData()`

### retryRequest

    public boolean retryRequest()
                         throws IOException,
                                ModuleException

  Should the request be retried by the application? If the application used an HttpOutputStream in the request then various modules (such as the redirection and authorization modules) are not able to resend the request themselves. Instead, it becomes the application's responsibility. The application can check this flag, and if it's set, resend the exact same request. The modules such as the RedirectionModule or AuthorizationModule will then recognize the resend and fix up or redirect the request as required (i.e. they defer their normal action until the resend).

  If the application resends the request then it must use the same HttpOutputStream instance. This is because the modules use this to recognize the retried request and to perform the necessary work on the request before it's sent.

  Here is a skeleton example of usage:

           OutputStream out = new HttpOutputStream(1234);
           do
           {
               rsp = con.Post("/cgi-bin/my_cgi", out);
               out.write(...);
               out.close();
           } while (rsp.retryRequest());

           if (rsp.getStatusCode() >= 300)
               ...

  Note that for this to ever return true, the java system property HTTPClient.deferStreamed must be set to true at the beginning of the application (before the HTTPConnection class is loaded). This prevents unwary applications from causing inadvertent memory leaks. If an application does set this, then it must resend any request whose response returns true here in order to prevent memory leaks (a switch to JDK 1.2 will allow us to use weak references and eliminate this problem).

  Returns:
    true if the request should be retried.
  Throws:
    `IOException` - If any exception occurs on the socket.
    `ModuleException` - if any module encounters an exception.

### toString

    public String toString()

  produces a full list of headers and their values, one per line.

  Returns:
    a string containing the headers

### getModules

    HTTPClientModule[] getModules()

### handleResponse

    boolean handleResponse()
                     throws IOException,
                            ModuleException

  Processes a Response. This is done by calling the response handler in each module. When all is done, the various fields of this instance are intialized from the last Response.

  Returns:
    true if a new request was generated. This is used for internal subrequests only
  Throws:
    `IOException` - if any handler throws an IOException.
    `ModuleException` - if any module encounters an exception.

### init

    void init(Response resp)

  Copies the relevant fields from Response and marks this as initialized.

  Parameters:
    `resp` - the Response class to copy from

### invokeTrailerHandlers

    void invokeTrailerHandlers(boolean force)
                         throws IOException,
                                ModuleException

  This is invoked by the RespInputStream when it is close()'d. It just invokes the trailer handler in each module.

  Parameters:
    `force` - invoke the handlers even if not initialized yet?
  Throws:
    `IOException` - if thrown by any module
    `ModuleException` - if thrown by any module

### markAborted

    void markAborted()

  Mark this request as having been aborted. It's invoked by HTTPConnection.stop().

### getTimeout

    int getTimeout()