001: /*
002: * @(#)HTTPClientModule.java 0.3-2 18/06/1999
003: *
004: * This file is part of the HTTPClient package
005: * Copyright (C) 1996-1999 Ronald Tschalär
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation; either
010: * version 2 of the License, or (at your option) any later version.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this library; if not, write to the Free
019: * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
020: * MA 02111-1307, USA
021: *
022: * For questions, suggestions, bug-reports, enhancement-requests etc.
023: * I may be contacted at:
024: *
025: * ronald@innovation.ch
026: *
027: */
028:
029: package HTTPClient;
030:
031: import java.io.IOException;
032:
033: /**
034: * This is the interface that a module must implement. There are two parts
035: * during a request: the construction of the request, and the handling of
036: * the response. A request may cycle through these parts multiple times
037: * when a module generates additional subrequests (such as a redirection
038: * status handling module might do).
039: *
040: * <P>In the first step the request handler is invoked; here the headers,
041: * the request-uri, etc. can be modified, or a complete response can be
042: * generated. Then, if no response was generated, the request is sent over
043: * the wire. In the second step the response handlers are invoked. These
044: * may modify the response or, in phase 2, may generate a new request; the
045: * returned status from the phase 2 handler specifies how the processing of
046: * the request or response should further proceed.
047: *
048: * <P>The response handling is split into three phases. In the first phase
049: * the response handling cannot be modified; this is so that all modules
050: * get a chance to see the returned response. Modules will typically make
051: * notes of responses and do certain header processing here (for example the
052: * cookie module does it's work in this phase). In the second phase modules
053: * may generate new subrequests or otherwise control the further handling of
054: * the response. This is typically used for response status handling (such
055: * as for redirections and authentication). Finally, if no new subrequest
056: * was generated, the phase 3 response handlers are invoked so that modules
057: * can perform any necessary cleanups and final processing (no additional
058: * subrequests can be made anymore). It is recommended that any response
059: * processing which needn't be done if the request is not returned to the
060: * user is deferred until this phase. For example, the Content-MD5,
061: * Content-Encoding and Transfer-Encoding modules do their work in this
062: * phase as the body is usually discarded if a new subrequest is generated.
063: *
064: * <P>When the user invokes any request method (such as <code>Get(...)</code>)
065: * a list of of modules to be used is built. Then, for each module in the
066: * list, an instance is created using the <code>Class.newInstance()</code>
067: * method. This means that each module must have a constructor which takes
068: * no arguments. This instance is then used to handle the request, its
069: * response, and any additional subrequests and their responses. In this way
070: * a module can easily keep state between related subrequests. For example, a
071: * redirection module might want to keep track of the number of redirections
072: * made to detect redirect loops; it could do this by defining an instance
073: * variable and incrementing it each time the request handler is invoked.
074: *
075: * @version 0.3-2 18/06/1999
076: * @author Ronald Tschalär
077: * @since V0.3
078: */
079:
080: public interface HTTPClientModule extends HTTPClientModuleConstants {
081: /**
082: * This is invoked before the request is sent. A module will typically
083: * use this to make a note of headers, to modify headers and/or data,
084: * or even generate and return a response (e.g. for a cache module).
085: * If a response is generated the module must return the appropriate
086: * return code (<var>REQ_RESPONSE</var> or <var>REQ_RETURN</var>).
087: *
088: * <P>Return codes for phase 1 (defined in HTTPClientModuleConstants.java)
089: * <DL>
090: * <DT>REQ_CONTINUE <DI>continue processing
091: * <DT>REQ_RESTART <DI>restart processing with first module
092: * <DT>REQ_SHORTCIRC <DI>stop processing and send
093: * <DT>REQ_RESPONSE <DI>go to phase 2
094: * <DT>REQ_RETURN <DI>return response immediately (no processing)
095: * <DT>REQ_NEWCON_RST <DI>use a new HTTPConnection, restart processing
096: * <DT>REQ_NEWCON_SND <DI>use a new HTTPConnection, send immediately
097: * </DL>
098: *
099: * @param request the request - may be modified as needed
100: * @param response the response if the status is REQ_RESPONSE or REQ_RETURN
101: * @return status code REQ_XXX specifying further action
102: * @exception IOException if an IOException occurs on the socket
103: * @exception ModuleException if an exception occurs during the handling
104: * of the request
105: */
106: public int requestHandler(Request request, Response[] response)
107: throws IOException, ModuleException;
108:
109: /**
110: * The phase 1 response handler. This will be invoked for every response.
111: * Modules will typically make notes of the response and do any header
112: * processing which must always be performed.
113: *
114: * @param response the response - may be modified
115: * @param request the original request
116: * @exception IOException if an IOException occurs on the socket
117: * @exception ModuleException if an exception occurs during the handling
118: * of the response
119: */
120: public void responsePhase1Handler(Response response,
121: RoRequest request) throws IOException, ModuleException;
122:
123: /**
124: * The phase 2 response handler. A module may modify the response or
125: * generate a new request (e.g. for redirection). This handler will
126: * only be invoked for a given module if all previous modules returned
127: * <var>RSP_CONTINUE</var>. If the request is modified the handler must
128: * return an appropriate return code (<var>RSP_REQUEST</var>,
129: * <var>RSP_SEND</var>, <var>RSP_NEWCON_REQ</var> or
130: * <var>RSP_NEWCON_SND</var>). If any other code is return the request
131: * must not be modified.
132: *
133: * <P>Return codes for phase 2 (defined in HTTPClientModuleConstants.java)
134: * <DL>
135: * <DT>RSP_CONTINUE <DI>continue processing
136: * <DT>RSP_RESTART <DI>restart processing with first module (phase 1)
137: * <DT>RSP_SHORTCIRC <DI>stop processing and return
138: * <DT>RSP_REQUEST <DI>go to phase 1
139: * <DT>RSP_SEND <DI>send request immediately (no processing)
140: * <DT>RSP_NEWCON_REQ <DI>go to phase 1 using a new HTTPConnection
141: * <DT>RSP_NEWCON_SND <DI>send request using a new HTTPConnection
142: * </DL>
143: *
144: * @param response the response - may be modified
145: * @param request the request; if the status is RSP_REQUEST then this
146: * must contain the new request; however do not modify
147: * this if you don't return a RSP_REQUEST status.
148: * @return status code RSP_XXX specifying further action
149: * @exception IOException if an IOException occurs on the socket
150: * @exception ModuleException if an exception occurs during the handling
151: * of the response
152: */
153: public int responsePhase2Handler(Response response, Request request)
154: throws IOException, ModuleException;
155:
156: /**
157: * The phase 3 response handler. This will only be invoked if no new
158: * subrequest was generated in phase 2. Modules should defer any repsonse
159: * handling which need only be done if the response is returned to the
160: * user to this phase.
161: *
162: * @param response the response - may be modified
163: * @param request the original request
164: * @exception IOException if an IOException occurs on the socket
165: * @exception ModuleException if an exception occurs during the handling
166: * of the response
167: */
168: public void responsePhase3Handler(Response response,
169: RoRequest request) throws IOException, ModuleException;
170:
171: /**
172: * The chunked transfer-encoding (and in future maybe others) can contain
173: * trailer fields at the end of the body. Since the
174: * <code>responsePhaseXHandler()</code>'s are invoked before the body is
175: * read and therefore do not have access to the trailers (unless they
176: * force the complete body to be read) this method will be invoked when
177: * the trailers have been read and parsed (sort of a post-response
178: * handling).
179: *
180: * <P>Note: This method <strong>must not</strong> modify any part of the
181: * response other than the trailers.
182: *
183: * @param response the response
184: * @param request the request
185: * @exception IOException if an IOException occurs on the socket
186: * @exception ModuleException if an exception occurs during the handling
187: * of the trailers
188: */
189: public void trailerHandler(Response response, RoRequest request)
190: throws IOException, ModuleException;
191: }
|