1 /*
2 * @(#)HTTPClientModule.java 0.3-3 06/05/2001
3 *
4 * This file is part of the HTTPClient package
5 * Copyright (C) 1996-2001 Ronald Tschalär
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free
19 * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
20 * MA 02111-1307, USA
21 *
22 * For questions, suggestions, bug-reports, enhancement-requests etc.
23 * I may be contacted at:
24 *
25 * ronald@innovation.ch
26 *
27 * The HTTPClient's home page is located at:
28 *
29 * http://www.innovation.ch/java/HTTPClient/
30 *
31 */
32
33 package HTTPClient;
34
35 import java.io.IOException;
36
37 /**
38 * This is the interface that a module must implement. There are two parts
39 * during a request: the construction of the request, and the handling of
40 * the response. A request may cycle through these parts multiple times
41 * when a module generates additional subrequests (such as a redirection
42 * status handling module might do).
43 *
44 * <P>In the first step the request handler is invoked; here the headers,
45 * the request-uri, etc. can be modified, or a complete response can be
46 * generated. Then, if no response was generated, the request is sent over
47 * the wire. In the second step the response handlers are invoked. These
48 * may modify the response or, in phase 2, may generate a new request; the
49 * returned status from the phase 2 handler specifies how the processing of
50 * the request or response should further proceed.
51 *
52 * <P>The response handling is split into three phases. In the first phase
53 * the response handling cannot be modified; this is so that all modules
54 * get a chance to see the returned response. Modules will typically make
55 * notes of responses and do certain header processing here (for example the
56 * cookie module does it's work in this phase). In the second phase modules
57 * may generate new subrequests or otherwise control the further handling of
58 * the response. This is typically used for response status handling (such
59 * as for redirections and authentication). Finally, if no new subrequest
60 * was generated, the phase 3 response handlers are invoked so that modules
61 * can perform any necessary cleanups and final processing (no additional
62 * subrequests can be made anymore). It is recommended that any response
63 * processing which needn't be done if the request is not returned to the
64 * user is deferred until this phase. For example, the Content-MD5,
65 * Content-Encoding and Transfer-Encoding modules do their work in this
66 * phase as the response body is usually discarded if a new subrequest is
67 * generated.
68 *
69 * <P>When the user invokes any request method (such as <code>Get(...)</code>)
70 * a list of of modules to be used is built. Then, for each module in the
71 * list, an instance is created using the <code>Class.newInstance()</code>
72 * method. This means that each module must have a constructor which takes
73 * no arguments. This instance is then used to handle the request, its
74 * response, and any additional subrequests and their responses. In this way
75 * a module can easily keep state between related subrequests. For example, a
76 * redirection module might want to keep track of the number of redirections
77 * made to detect redirect loops; it could do this by defining an instance
78 * variable and incrementing it each time the request handler is invoked.
79 *
80 * @version 0.3-3 06/05/2001
81 * @author Ronald Tschalär
82 * @since V0.3
83 */
84 public interface HTTPClientModule extends HTTPClientModuleConstants
85 {
86 /**
87 * This is invoked before the request is sent. A module will typically
88 * use this to make a note of headers, to modify headers and/or data,
89 * or even generate and return a response (e.g. for a cache module).
90 * If a response is generated the module must return the appropriate
91 * return code (<var>REQ_RESPONSE</var> or <var>REQ_RETURN</var>).
92 *
93 * <P>Return codes for phase 1 (defined in HTTPClientModuleConstants.java)
94 * <DL>
95 * <DT>REQ_CONTINUE <DI>continue processing
96 * <DT>REQ_RESTART <DI>restart processing with first module
97 * <DT>REQ_SHORTCIRC <DI>stop processing and send
98 * <DT>REQ_RESPONSE <DI>go to phase 2
99 * <DT>REQ_RETURN <DI>return response immediately (no processing)
100 * <DT>REQ_NEWCON_RST <DI>use a new HTTPConnection, restart processing
101 * <DT>REQ_NEWCON_SND <DI>use a new HTTPConnection, send immediately
102 * </DL>
103 *
104 * @param request the request - may be modified as needed
105 * @param response the response if the status is REQ_RESPONSE or REQ_RETURN
106 * @return status code REQ_XXX specifying further action
107 * @exception IOException if an IOException occurs on the socket
108 * @exception ModuleException if an exception occurs during the handling
109 * of the request
110 */
111 public int requestHandler(Request request, Response[] response)
112 throws IOException, ModuleException;
113
114
115 /**
116 * The phase 1 response handler. This will be invoked for every response.
117 * Modules will typically make notes of the response and do any header
118 * processing which must always be performed.
119 *
120 * @param response the response - may be modified
121 * @param request the original request
122 * @exception IOException if an IOException occurs on the socket
123 * @exception ModuleException if an exception occurs during the handling
124 * of the response
125 */
126 public void responsePhase1Handler(Response response, RoRequest request)
127 throws IOException, ModuleException;
128
129 /**
130 * The phase 2 response handler. A module may modify the response or
131 * generate a new request (e.g. for redirection). This handler will
132 * only be invoked for a given module if all previous modules returned
133 * <var>RSP_CONTINUE</var>. If the request is modified the handler must
134 * return an appropriate return code (<var>RSP_REQUEST</var>,
135 * <var>RSP_SEND</var>, <var>RSP_NEWCON_REQ</var> or
136 * <var>RSP_NEWCON_SND</var>). If any other code is return the request
137 * must not be modified.
138 *
139 * <P>Return codes for phase 2 (defined in HTTPClientModuleConstants.java)
140 * <DL>
141 * <DT>RSP_CONTINUE <DI>continue processing
142 * <DT>RSP_RESTART <DI>restart processing with first module (phase 1)
143 * <DT>RSP_SHORTCIRC <DI>stop processing and return
144 * <DT>RSP_REQUEST <DI>go to phase 1
145 * <DT>RSP_SEND <DI>send request immediately (no processing)
146 * <DT>RSP_NEWCON_REQ <DI>go to phase 1 using a new HTTPConnection
147 * <DT>RSP_NEWCON_SND <DI>send request using a new HTTPConnection
148 * </DL>
149 *
150 * @param response the response - may be modified
151 * @param request the request; if the status is RSP_REQUEST then this
152 * must contain the new request; however do not modify
153 * this if you don't return a RSP_REQUEST status.
154 * @return status code RSP_XXX specifying further action
155 * @exception IOException if an IOException occurs on the socket
156 * @exception ModuleException if an exception occurs during the handling
157 * of the response
158 */
159 public int responsePhase2Handler(Response response, Request request)
160 throws IOException, ModuleException;
161
162
163 /**
164 * The phase 3 response handler. This will only be invoked if no new
165 * subrequest was generated in phase 2. Modules should defer any repsonse
166 * handling which need only be done if the response is returned to the
167 * user to this phase.
168 *
169 * @param response the response - may be modified
170 * @param request the original request
171 * @exception IOException if an IOException occurs on the socket
172 * @exception ModuleException if an exception occurs during the handling
173 * of the response
174 */
175 public void responsePhase3Handler(Response response, RoRequest request)
176 throws IOException, ModuleException;
177
178
179 /**
180 * The chunked transfer-encoding (and in future maybe others) can contain
181 * trailer fields at the end of the body. Since the
182 * <code>responsePhaseXHandler()</code>'s are invoked before the body is
183 * read and therefore do not have access to the trailers (unless they
184 * force the complete body to be read) this method will be invoked when
185 * the trailers have been read and parsed (sort of a post-response
186 * handling).
187 *
188 * <P>Note: This method <strong>must not</strong> modify any part of the
189 * response other than the trailers.
190 *
191 * @param response the response
192 * @param request the request
193 * @exception IOException if an IOException occurs on the socket
194 * @exception ModuleException if an exception occurs during the handling
195 * of the trailers
196 */
197 public void trailerHandler(Response response, RoRequest request)
198 throws IOException, ModuleException;
199 }