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