KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > HTTPClient > HTTPClientModule


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