HTTPClient.HTTPClientModule Maven / Gradle / Ivy
Show all versions of grinder-httpclient Show documentation
/*
* @(#)HTTPClientModule.java 0.3-3 06/05/2001
*
* This file is part of the HTTPClient package
* Copyright (C) 1996-2001 Ronald Tschalär
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free
* Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
* MA 02111-1307, USA
*
* For questions, suggestions, bug-reports, enhancement-requests etc.
* I may be contacted at:
*
* [email protected]
*
* The HTTPClient's home page is located at:
*
* http://www.innovation.ch/java/HTTPClient/
*
*/
package HTTPClient;
import java.io.IOException;
/**
* 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.
*
* @version 0.3-3 06/05/2001
* @author Ronald Tschalär
* @since V0.3
*/
public interface HTTPClientModule extends HTTPClientModuleConstants
{
/**
* 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
continue processing
* - REQ_RESTART
restart processing with first module
* - REQ_SHORTCIRC
stop processing and send
* - REQ_RESPONSE
go to phase 2
* - REQ_RETURN
return response immediately (no processing)
* - REQ_NEWCON_RST
use a new HTTPConnection, restart processing
* - REQ_NEWCON_SND
use a new HTTPConnection, send immediately
*
*
* @param request the request - may be modified as needed
* @param response the response if the status is REQ_RESPONSE or REQ_RETURN
* @return status code REQ_XXX specifying further action
* @exception IOException if an IOException occurs on the socket
* @exception ModuleException if an exception occurs during the handling
* of the request
*/
public int requestHandler(Request request, Response[] response)
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.
*
* @param response the response - may be modified
* @param request the original request
* @exception IOException if an IOException occurs on the socket
* @exception ModuleException if an exception occurs during the handling
* of the response
*/
public void responsePhase1Handler(Response response, RoRequest 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
continue processing
* - RSP_RESTART
restart processing with first module (phase 1)
* - RSP_SHORTCIRC
stop processing and return
* - RSP_REQUEST
go to phase 1
* - RSP_SEND
send request immediately (no processing)
* - RSP_NEWCON_REQ
go to phase 1 using a new HTTPConnection
* - RSP_NEWCON_SND
send request using a new HTTPConnection
*
*
* @param response the response - may be modified
* @param 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.
* @return status code RSP_XXX specifying further action
* @exception IOException if an IOException occurs on the socket
* @exception ModuleException if an exception occurs during the handling
* of the response
*/
public int responsePhase2Handler(Response response, Request 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.
*
* @param response the response - may be modified
* @param request the original request
* @exception IOException if an IOException occurs on the socket
* @exception ModuleException if an exception occurs during the handling
* of the response
*/
public void responsePhase3Handler(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.
*
* @param response the response
* @param request the request
* @exception IOException if an IOException occurs on the socket
* @exception ModuleException if an exception occurs during the handling
* of the trailers
*/
public void trailerHandler(Response response, RoRequest request)
throws IOException, ModuleException;
}