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