public interface HTTPClientModule extends HTTPClientModuleConstants
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.
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| Modifier and Type | Method and Description |
|---|---|
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.
|
int requestHandler(Request request, Response[] response) throws java.io.IOException, ModuleException
Return codes for phase 1 (defined in HTTPClientModuleConstants.java)
request - the request - may be modified as neededresponse - the response if the status is REQ_RESPONSE or REQ_RETURNjava.io.IOException - if an IOException occurs on the socketModuleException - if an exception occurs during the handling
of the requestvoid responsePhase1Handler(Response response, RoRequest request) throws java.io.IOException, ModuleException
response - the response - may be modifiedrequest - the original requestjava.io.IOException - if an IOException occurs on the socketModuleException - if an exception occurs during the handling
of the responseint responsePhase2Handler(Response response, Request request) throws java.io.IOException, ModuleException
Return codes for phase 2 (defined in HTTPClientModuleConstants.java)
response - the response - may be modifiedrequest - 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.java.io.IOException - if an IOException occurs on the socketModuleException - if an exception occurs during the handling
of the responsevoid responsePhase3Handler(Response response, RoRequest request) throws java.io.IOException, ModuleException
response - the response - may be modifiedrequest - the original requestjava.io.IOException - if an IOException occurs on the socketModuleException - if an exception occurs during the handling
of the responsevoid trailerHandler(Response response, RoRequest request) throws java.io.IOException, ModuleException
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.
response - the responserequest - the requestjava.io.IOException - if an IOException occurs on the socketModuleException - if an exception occurs during the handling
of the trailers