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