1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32 package org.apache.commons.httpclient;
33
34 import java.io.IOException;
35 import java.io.InputStream;
36
37 /***
38 * <p>
39 * HttpMethod interface represents a request to be sent via a
40 * {@link HttpConnection HTTP connection} and a corresponding response.
41 * </p>
42 * @author <a href="mailto:remm@apache.org">Remy Maucherat</a>
43 * @author Rod Waldhoff
44 * @author <a href="jsdever@apache.org">Jeff Dever</a>
45 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
46 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
47 *
48 * @version $Revision: 1.23.2.5 $ $Date: 2004/06/13 20:24:48 $
49 *
50 * @since 1.0
51 */
52 public interface HttpMethod {
53
54
55
56 /***
57 * Obtains the name of the HTTP method as used in the HTTP request line,
58 * for example <tt>"GET"</tt> or <tt>"POST"</tt>.
59 *
60 * @return the name of this method
61 */
62 String getName();
63
64 /***
65 * Gets the host configuration for this method. The configuration specifies
66 * the server, port, protocol, and proxy server via which this method will
67 * send its HTTP request.
68 *
69 * @return the HostConfiguration or <code>null</code> if none is set
70 */
71 HostConfiguration getHostConfiguration();
72
73 /***
74 * Sets the path of the HTTP method.
75 * It is responsibility of the caller to ensure that the path is
76 * properly encoded (URL safe).
77 *
78 * @param path The path of the HTTP method. The path is expected
79 * to be URL encoded.
80 */
81 void setPath(String path);
82
83 /***
84 * Returns the path of the HTTP method.
85 *
86 * Calling this method <em>after</em> the request has been executed will
87 * return the <em>actual</em> path, following any redirects automatically
88 * handled by this HTTP method.
89 *
90 * @return the path of the HTTP method, in URL encoded form
91 */
92 String getPath();
93
94 /***
95 * Returns the URI for this method. The URI will be absolute if the host
96 * configuration has been set and relative otherwise.
97 *
98 * @return the URI for this method
99 *
100 * @throws URIException if a URI cannot be constructed
101 */
102 URI getURI() throws URIException;
103
104 /***
105 * Defines how strictly the method follows the HTTP protocol specification.
106 * (See RFC 2616 and other relevant RFCs.) In the strict mode the method precisely
107 * implements the requirements of the specification, whereas in non-strict mode
108 * it attempts to mimic the exact behaviour of commonly used HTTP agents,
109 * which many HTTP servers expect.
110 *
111 * @param strictMode <tt>true</tt> for strict mode, <tt>false</tt> otherwise
112 *
113 * @see #isStrictMode()
114 */
115 void setStrictMode(boolean strictMode);
116
117 /***
118 * Returns the value of the strict mode flag.
119 *
120 * @return <tt>true</tt> if strict mode is enabled, <tt>false</tt> otherwise
121 *
122 * @see #setStrictMode(boolean)
123 */
124 boolean isStrictMode();
125
126 /***
127 * Sets the specified request header, overwriting any previous value.
128 * Note that header-name matching is case insensitive.
129 *
130 * @param headerName the header's name
131 * @param headerValue the header's value
132 *
133 * @see #setRequestHeader(Header)
134 * @see #getRequestHeader(String)
135 * @see #removeRequestHeader(String)
136 */
137 void setRequestHeader(String headerName, String headerValue);
138
139 /***
140 * Sets the specified request header, overwriting any previous value.
141 * Note that header-name matching is case insensitive.
142 *
143 * @param header the header to be set
144 *
145 * @see #setRequestHeader(String,String)
146 * @see #getRequestHeader(String)
147 * @see #removeRequestHeader(String)
148 */
149 void setRequestHeader(Header header);
150
151 /***
152 * Adds the specified request header, <em>not</em> overwriting any previous value.
153 * If the same header is added multiple times, perhaps with different values,
154 * multiple instances of that header will be sent in the HTTP request.
155 * Note that header-name matching is case insensitive.
156 *
157 * @param headerName the header's name
158 * @param headerValue the header's value
159 *
160 * @see #addRequestHeader(Header)
161 * @see #getRequestHeader(String)
162 * @see #removeRequestHeader(String)
163 */
164 void addRequestHeader(String headerName, String headerValue);
165
166 /***
167 * Adds the specified request header, <em>not</em> overwriting any previous value.
168 * If the same header is added multiple times, perhaps with different values,
169 * multiple instances of that header will be sent in the HTTP request.
170 * Note that header-name matching is case insensitive.
171 *
172 * @param header the header
173 *
174 * @see #addRequestHeader(String,String)
175 * @see #getRequestHeader(String)
176 * @see #removeRequestHeader(String)
177 */
178 void addRequestHeader(Header header);
179
180 /***
181 * Gets the request header with the given name.
182 * If there are multiple headers with the same name,
183 * there values will be combined with the ',' separator as specified by RFC2616.
184 * Note that header-name matching is case insensitive.
185 *
186 * @param headerName the header name
187 * @return the header
188 */
189 Header getRequestHeader(String headerName);
190
191 /***
192 * Removes all request headers with the given name.
193 * Note that header-name matching is case insensitive.
194 *
195 * @param headerName the header name
196 */
197 void removeRequestHeader(String headerName);
198
199 /***
200 * Returns <tt>true</tt> if the HTTP method should automatically follow HTTP redirects
201 * (status code 302, etc.), <tt>false</tt> otherwise.
202 *
203 * @return <tt>true</tt> if the method will automatically follow HTTP redirects,
204 * <tt>false</tt> otherwise
205 */
206 boolean getFollowRedirects();
207
208 /***
209 * Sets whether or not the HTTP method should automatically follow HTTP redirects
210 * (status code 302, etc.)
211 *
212 * @param followRedirects <tt>true</tt> if the method will automatically follow redirects,
213 * <tt>false</tt> otherwise
214 */
215 void setFollowRedirects(boolean followRedirects);
216
217 /***
218 * Sets the query string of the HTTP method.
219 * It is responsibility of the caller to ensure that the path is
220 * properly encoded (URL safe). The string must not include an initial '?' character.
221 *
222 * @param queryString the query to be used in the request, with no leading '?' character
223 *
224 * @see #getQueryString()
225 * @see #setQueryString(NameValuePair[])
226 */
227 void setQueryString(String queryString);
228
229 /***
230 * Sets the query string of this HTTP method. The pairs are encoded as UTF-8 characters.
231 * To use a different charset the parameters can be encoded manually using EncodingUtil
232 * and set as a single String.
233 *
234 * @param params An array of <code>NameValuePair</code>s to use as the query string.
235 * The name/value pairs will be automatically URL encoded and should not
236 * have been encoded previously.
237 *
238 * @see #getQueryString()
239 * @see #setQueryString(String)
240 * @see org.apache.commons.httpclient.util.EncodingUtil#formUrlEncode(NameValuePair[], String)
241 */
242 void setQueryString(NameValuePair[] params);
243
244 /***
245 * Returns the query string of this HTTP method.
246 *
247 * @return the query string in URL encoded form, without a leading '?'.
248 *
249 * @see #setQueryString(NameValuePair[])
250 * @see #setQueryString(String)
251 */
252 String getQueryString();
253
254 /***
255 * Returns the current request headers for this HTTP method. The returned headers
256 * will be in the same order that they were added with <code>addRequestHeader</code>.
257 * If there are multiple request headers with the same name (e.g. <code>Cookie</code>),
258 * they will be returned as multiple entries in the array.
259 *
260 * @return an array containing all of the request headers
261 *
262 * @see #addRequestHeader(Header)
263 * @see #addRequestHeader(String,String)
264 */
265 Header[] getRequestHeaders();
266
267
268
269 /***
270 * Returns <tt>true</tt> the method is ready to execute, <tt>false</tt> otherwise.
271 *
272 * @return <tt>true</tt> if the method is ready to execute, <tt>false</tt> otherwise.
273 */
274 boolean validate();
275
276 /***
277 * Returns the status code associated with the latest response.
278 *
279 * @return The status code from the most recent execution of this method.
280 * If the method has not yet been executed, the result is undefined.
281 */
282 int getStatusCode();
283
284 /***
285 * Returns the status text (or "reason phrase") associated with the latest
286 * response.
287 *
288 * @return The status text from the most recent execution of this method.
289 * If the method has not yet been executed, the result is undefined.
290 */
291 String getStatusText();
292
293 /***
294 * Returns the response headers from the most recent execution of this request.
295 *
296 * @return A newly-created array containing all of the response headers,
297 * in the order in which they appeared in the response.
298 */
299 Header[] getResponseHeaders();
300
301 /***
302 * Returns the specified response header. Note that header-name matching is
303 * case insensitive.
304 *
305 * @param headerName The name of the header to be returned.
306 *
307 * @return The specified response header. If the repsonse contained multiple
308 * instances of the header, its values will be combined using the ','
309 * separator as specified by RFC2616.
310 */
311 Header getResponseHeader(String headerName);
312
313 /***
314 * Returns the response footers from the most recent execution of this request.
315 *
316 * @return an array containing the response footers in the order that they
317 * appeared in the response. If the response had no footers,
318 * an empty array will be returned.
319 */
320 Header[] getResponseFooters();
321
322 /***
323 * Return the specified response footer. Note that footer-name matching is
324 * case insensitive.
325 *
326 * @param footerName The name of the footer.
327 * @return The response footer.
328 */
329 Header getResponseFooter(String footerName);
330
331 /***
332 * Returns the response body of the HTTP method, if any, as an array of bytes.
333 * If the method has not yet been executed or the response has no body, <code>null</code>
334 * is returned. Note that this method does not propagate I/O exceptions.
335 * If an error occurs while reading the body, <code>null</code> will be returned.
336 *
337 * @return The response body, or <code>null</code> if the
338 * body is not available.
339 */
340 byte[] getResponseBody();
341
342 /***
343 * Returns the response body of the HTTP method, if any, as a {@link String}.
344 * If response body is not available or cannot be read, <tt>null</tt> is returned.
345 * The raw bytes in the body are converted to a <code>String</code> using the
346 * character encoding specified in the response's <tt>Content-Type</tt> header, or
347 * ISO-8859-1 if the response did not specify a character set.
348 * <p>
349 * Note that this method does not propagate I/O exceptions.
350 * If an error occurs while reading the body, <code>null</code> will be returned.
351 *
352 * @return The response body converted to a <code>String</code>, or <code>null</code>
353 * if the body is not available.
354 */
355 String getResponseBodyAsString();
356
357 /***
358 * Returns the response body of the HTTP method, if any, as an InputStream.
359 * If the response had no body or the method has not yet been executed,
360 * <code>null</code> is returned. Additionally, <code>null</code> may be returned
361 * if {@link #releaseConnection} has been called or
362 * if this method was called previously and the resulting stream was closed.
363 *
364 * @return The response body, or <code>null</code> if it is not available
365 *
366 * @throws IOException if an I/O (transport) problem occurs
367 */
368 InputStream getResponseBodyAsStream() throws IOException;
369
370 /***
371 * Returns <tt>true</tt> if the HTTP method has been already {@link #execute executed},
372 * but not {@link #recycle recycled}.
373 *
374 * @return <tt>true</tt> if the method has been executed, <tt>false</tt> otherwise
375 */
376 boolean hasBeenUsed();
377
378
379
380 /***
381 * Executes this method using the specified <code>HttpConnection</code> and
382 * <code>HttpState</code>.
383 *
384 * @param state the {@link HttpState state} information to associate with this method
385 * @param connection the {@link HttpConnection connection} used to execute
386 * this HTTP method
387 *
388 * @throws IOException If an I/O (transport) error occurs. Some transport exceptions
389 * can be recovered from.
390 * @throws HttpException If a protocol exception occurs. Usually protocol exceptions
391 * cannot be recovered from.
392 *
393 * @return the integer status code if one was obtained, or <tt>-1</tt>
394 */
395 int execute(HttpState state, HttpConnection connection)
396 throws HttpException, IOException;
397
398 /***
399 * Recycles the HTTP method so that it can be used again.
400 * Note that all of the instance variables will be reset
401 * once this method has been called. This method will also
402 * release the connection being used by this HTTP method.
403 *
404 * @see #releaseConnection()
405 *
406 * @deprecated no longer supported and will be removed in the future
407 * version of HttpClient
408 */
409 void recycle();
410
411 /***
412 * Releases the connection being used by this HTTP method. In particular the
413 * connection is used to read the response (if there is one) and will be held
414 * until the response has been read. If the connection can be reused by other
415 * HTTP methods it is NOT closed at this point.
416 * <p>
417 * After this method is called, {@link #getResponseBodyAsStream} will return
418 * <code>null</code>, and {@link #getResponseBody} and {@link #getResponseBodyAsString}
419 * <em>may</em> return <code>null</code>.
420 */
421 void releaseConnection();
422
423 /***
424 * Add a footer to this method's response.
425 * <p>
426 * <b>Note:</b> This method is for
427 * internal use only and should not be called by external clients.
428 *
429 * @param footer the footer to add
430 *
431 * @since 2.0
432 */
433 void addResponseFooter(Header footer);
434
435 /***
436 * Returns the Status-Line from the most recent response for this method,
437 * or <code>null</code> if the method has not been executed.
438 *
439 * @return the status line, or <code>null</code> if the method has not been executed
440 *
441 * @since 2.0
442 */
443 StatusLine getStatusLine();
444
445 /***
446 * Returns <tt>true</tt> if the HTTP method should automatically handle HTTP
447 * authentication challenges (status code 401, etc.), <tt>false</tt> otherwise
448 *
449 * @return <tt>true</tt> if authentication challenges will be processed
450 * automatically, <tt>false</tt> otherwise.
451 *
452 * @since 2.0
453 *
454 * @see #setDoAuthentication(boolean)
455 */
456 boolean getDoAuthentication();
457
458 /***
459 * Sets whether or not the HTTP method should automatically handle HTTP
460 * authentication challenges (status code 401, etc.)
461 *
462 * @param doAuthentication <tt>true</tt> to process authentication challenges
463 * automatically, <tt>false</tt> otherwise.
464 *
465 * @since 2.0
466 *
467 * @see #getDoAuthentication()
468 */
469 void setDoAuthentication(boolean doAuthentication);
470
471 }