## HTTPClient
Interface HTTPClientModule

All Superinterfaces:
  HTTPClientModuleConstants

All Known Implementing Classes:
  AuthorizationModule, ContentEncodingModule, ContentMD5Module, CookieModule, DefaultModule, RedirectionModule, RetryModule, TransferEncodingModule

public interface HTTPClientModule
extends HTTPClientModuleConstants

This is the interface that a module must implement. There are two parts during a request: the construction of the request, and the handling of the response. A request may cycle through these parts multiple times when a module generates additional subrequests (such as a redirection status handling module might do).

In the first step the request handler is invoked; here the headers, the request-uri, etc. can be modified, or a complete response can be generated. Then, if no response was generated, the request is sent over the wire. In the second step the response handlers are invoked. These may modify the response or, in phase 2, may generate a new request; the returned status from the phase 2 handler specifies how the processing of the request or response should further proceed.

The response handling is split into three phases. In the first phase the response handling cannot be modified; this is so that all modules get a chance to see the returned response. Modules will typically make notes of responses and do certain header processing here (for example the cookie module does it's work in this phase). In the second phase modules may generate new subrequests or otherwise control the further handling of the response. This is typically used for response status handling (such as for redirections and authentication). Finally, if no new subrequest was generated, the phase 3 response handlers are invoked so that modules can perform any necessary cleanups and final processing (no additional subrequests can be made anymore). It is recommended that any response processing which needn't be done if the request is not returned to the user is deferred until this phase. For example, the Content-MD5, Content-Encoding and Transfer-Encoding modules do their work in this phase as the response body is usually discarded if a new subrequest is generated.

When the user invokes any request method (such as `Get(...)`) a list of of modules to be used is built. Then, for each module in the list, an instance is created using the `Class.newInstance()` method. This means that each module must have a constructor which takes no arguments. This instance is then used to handle the request, its response, and any additional subrequests and their responses. In this way a module can easily keep state between related subrequests. For example, a redirection module might want to keep track of the number of redirections made to detect redirect loops; it could do this by defining an instance variable and incrementing it each time the request handler is invoked.

Since:
  V0.3

Field Summary

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`

Method Summary
`int` `requestHandler(Request request, Response[] response)` This is invoked before the request is sent.
`void` `responsePhase1Handler(Response response, RoRequest request)` The phase 1 response handler.
`int` `responsePhase2Handler(Response response, Request request)` The phase 2 response handler.
`void` `responsePhase3Handler(Response response, RoRequest request)` The phase 3 response handler.
`void` `trailerHandler(Response response, RoRequest request)` The chunked transfer-encoding (and in future maybe others) can contain trailer fields at the end of the body.

Method Detail

### requestHandler

    public int requestHandler(Request request,
                              Response[] response)
                       throws IOException,
                              ModuleException

  This is invoked before the request is sent. A module will typically use this to make a note of headers, to modify headers and/or data, or even generate and return a response (e.g. for a cache module). If a response is generated the module must return the appropriate return code (REQ_RESPONSE or REQ_RETURN).

  Return codes for phase 1 (defined in HTTPClientModuleConstants.java)

  REQ_CONTINUE <DI>continue processing
  REQ_RESTART <DI>restart processing with first module
  REQ_SHORTCIRC <DI>stop processing and send
  REQ_RESPONSE <DI>go to phase 2
  REQ_RETURN <DI>return response immediately (no processing)
  REQ_NEWCON_RST <DI>use a new HTTPConnection, restart processing
  REQ_NEWCON_SND <DI>use a new HTTPConnection, send immediately

  Parameters:
    `request` - the request - may be modified as needed
    `response` - the response if the status is REQ_RESPONSE or REQ_RETURN
  Returns:
    status code REQ_XXX specifying further action
  Throws:
    `IOException` - if an IOException occurs on the socket
    `ModuleException` - if an exception occurs during the handling of the request

### responsePhase1Handler

    public void responsePhase1Handler(Response response,
                                      RoRequest request)
                               throws IOException,
                                      ModuleException

  The phase 1 response handler. This will be invoked for every response. Modules will typically make notes of the response and do any header processing which must always be performed.

  Parameters:
    `response` - the response - may be modified
    `request` - the original request
  Throws:
    `IOException` - if an IOException occurs on the socket
    `ModuleException` - if an exception occurs during the handling of the response

### responsePhase2Handler

    public int responsePhase2Handler(Response response,
                                     Request request)
                              throws IOException,
                                     ModuleException

  The phase 2 response handler. A module may modify the response or generate a new request (e.g. for redirection). This handler will only be invoked for a given module if all previous modules returned RSP_CONTINUE. If the request is modified the handler must return an appropriate return code (RSP_REQUEST, RSP_SEND, RSP_NEWCON_REQ or RSP_NEWCON_SND). If any other code is return the request must not be modified.

  Return codes for phase 2 (defined in HTTPClientModuleConstants.java)

  RSP_CONTINUE <DI>continue processing
  RSP_RESTART <DI>restart processing with first module (phase 1)
  RSP_SHORTCIRC <DI>stop processing and return
  RSP_REQUEST <DI>go to phase 1
  RSP_SEND <DI>send request immediately (no processing)
  RSP_NEWCON_REQ <DI>go to phase 1 using a new HTTPConnection
  RSP_NEWCON_SND <DI>send request using a new HTTPConnection

  Parameters:
    `response` - the response - may be modified
    `request` - the request; if the status is RSP_REQUEST then this must contain the new request; however do not modify this if you don't return a RSP_REQUEST status.
  Returns:
    status code RSP_XXX specifying further action
  Throws:
    `IOException` - if an IOException occurs on the socket
    `ModuleException` - if an exception occurs during the handling of the response

### responsePhase3Handler

    public void responsePhase3Handler(Response response,
                                      RoRequest request)
                               throws IOException,
                                      ModuleException

  The phase 3 response handler. This will only be invoked if no new subrequest was generated in phase 2. Modules should defer any repsonse handling which need only be done if the response is returned to the user to this phase.

  Parameters:
    `response` - the response - may be modified
    `request` - the original request
  Throws:
    `IOException` - if an IOException occurs on the socket
    `ModuleException` - if an exception occurs during the handling of the response

### trailerHandler

    public void trailerHandler(Response response,
                               RoRequest request)
                        throws IOException,
                               ModuleException

  The chunked transfer-encoding (and in future maybe others) can contain trailer fields at the end of the body. Since the `responsePhaseXHandler()`'s are invoked before the body is read and therefore do not have access to the trailers (unless they force the complete body to be read) this method will be invoked when the trailers have been read and parsed (sort of a post-response handling).

  Note: This method must not modify any part of the response other than the trailers.

  Parameters:
    `response` - the response
    `request` - the request
  Throws:
    `IOException` - if an IOException occurs on the socket
    `ModuleException` - if an exception occurs during the handling of the trailers