1 /*
2 * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java,v 1.23.2.3 2003/08/12 02:39:41 mbecke Exp $
3 * $Revision: 1.23.2.3 $
4 * $Date: 2003/08/12 02:39:41 $
5 *
6 * ====================================================================
7 *
8 * The Apache Software License, Version 1.1
9 *
10 * Copyright (c) 1999-2003 The Apache Software Foundation. All rights
11 * reserved.
12 *
13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that the following conditions
15 * are met:
16 *
17 * 1. Redistributions of source code must retain the above copyright
18 * notice, this list of conditions and the following disclaimer.
19 *
20 * 2. Redistributions in binary form must reproduce the above copyright
21 * notice, this list of conditions and the following disclaimer in
22 * the documentation and/or other materials provided with the
23 * distribution.
24 *
25 * 3. The end-user documentation included with the redistribution, if
26 * any, must include the following acknowlegement:
27 * "This product includes software developed by the
28 * Apache Software Foundation (http://www.apache.org/)."
29 * Alternately, this acknowlegement may appear in the software itself,
30 * if and wherever such third-party acknowlegements normally appear.
31 *
32 * 4. The names "The Jakarta Project", "Commons", and "Apache Software
33 * Foundation" must not be used to endorse or promote products derived
34 * from this software without prior written permission. For written
35 * permission, please contact apache@apache.org.
36 *
37 * 5. Products derived from this software may not be called "Apache"
38 * nor may "Apache" appear in their names without prior written
39 * permission of the Apache Group.
40 *
41 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
42 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
43 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
44 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
45 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
47 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
48 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
49 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
50 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
51 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
52 * SUCH DAMAGE.
53 * ====================================================================
54 *
55 * This software consists of voluntary contributions made by many
56 * individuals on behalf of the Apache Software Foundation. For more
57 * information on the Apache Software Foundation, please see
58 * <http://www.apache.org/>.
59 *
60 * [Additional notices, if required by prior licensing conditions]
61 *
62 */
63
64 package org.apache.commons.httpclient;
65
66 import java.io.IOException;
67 import java.io.InputStream;
68
69 /***
70 * <p>
71 * HttpMethod interface represents a request to be sent via a
72 * {@link HttpConnection HTTP connection} and a corresponding response.
73 * </p>
74 * @author <a href="mailto:remm@apache.org">Remy Maucherat</a>
75 * @author Rod Waldhoff
76 * @author <a href="jsdever@apache.org">Jeff Dever</a>
77 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
78 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
79 *
80 * @version $Revision: 1.23.2.3 $ $Date: 2003/08/12 02:39:41 $
81 *
82 * @since 1.0
83 */
84 public interface HttpMethod {
85
86 // ------------------------------------------- Property Setters and Getters
87
88 /***
89 * Obtains the name of the HTTP method as used in the HTTP request line,
90 * for example <tt>"GET"</tt> or <tt>"POST"</tt>.
91 *
92 * @return the name of this method
93 */
94 String getName();
95
96 /***
97 * Gets the host configuration for this method. The configuration specifies
98 * the server, port, protocol, and proxy server via which this method will
99 * send its HTTP request.
100 *
101 * @return the HostConfiguration or <code>null</code> if none is set
102 */
103 HostConfiguration getHostConfiguration();
104
105 /***
106 * Sets the path of the HTTP method.
107 * It is responsibility of the caller to ensure that the path is
108 * properly encoded (URL safe).
109 *
110 * @param path The path of the HTTP method. The path is expected
111 * to be URL encoded.
112 */
113 void setPath(String path);
114
115 /***
116 * Returns the path of the HTTP method.
117 *
118 * Calling this method <em>after</em> the request has been executed will
119 * return the <em>actual</em> path, following any redirects automatically
120 * handled by this HTTP method.
121 *
122 * @return the path of the HTTP method, in URL encoded form
123 */
124 String getPath();
125
126 /***
127 * Returns the URI for this method. The URI will be absolute if the host
128 * configuration has been set and relative otherwise.
129 *
130 * @return the URI for this method
131 *
132 * @throws URIException if a URI cannot be constructed
133 */
134 URI getURI() throws URIException;
135
136 /***
137 * Defines how strictly the method follows the HTTP protocol specification.
138 * (See RFC 2616 and other relevant RFCs.) In the strict mode the method precisely
139 * implements the requirements of the specification, whereas in non-strict mode
140 * it attempts to mimic the exact behaviour of commonly used HTTP agents,
141 * which many HTTP servers expect.
142 *
143 * @param strictMode <tt>true</tt> for strict mode, <tt>false</tt> otherwise
144 *
145 * @see #isStrictMode()
146 */
147 void setStrictMode(boolean strictMode);
148
149 /***
150 * Returns the value of the strict mode flag.
151 *
152 * @return <tt>true</tt> if strict mode is enabled, <tt>false</tt> otherwise
153 *
154 * @see #setStrictMode(boolean)
155 */
156 boolean isStrictMode();
157
158 /***
159 * Sets the specified request header, overwriting any previous value.
160 * Note that header-name matching is case insensitive.
161 *
162 * @param headerName the header's name
163 * @param headerValue the header's value
164 *
165 * @see #setRequestHeader(Header)
166 * @see #getRequestHeader(String)
167 * @see #removeRequestHeader(String)
168 */
169 void setRequestHeader(String headerName, String headerValue);
170
171 /***
172 * Sets the specified request header, overwriting any previous value.
173 * Note that header-name matching is case insensitive.
174 *
175 * @param header the header to be set
176 *
177 * @see #setRequestHeader(String,String)
178 * @see #getRequestHeader(String)
179 * @see #removeRequestHeader(String)
180 */
181 void setRequestHeader(Header header);
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 *
189 * @param headerName the header's name
190 * @param headerValue the header's value
191 *
192 * @see #addRequestHeader(Header)
193 * @see #getRequestHeader(String)
194 * @see #removeRequestHeader(String)
195 */
196 void addRequestHeader(String headerName, String headerValue);
197
198 /***
199 * Adds the specified request header, <em>not</em> overwriting any previous value.
200 * If the same header is added multiple times, perhaps with different values,
201 * multiple instances of that header will be sent in the HTTP request.
202 * Note that header-name matching is case insensitive.
203 *
204 * @param header the header
205 *
206 * @see #addRequestHeader(String,String)
207 * @see #getRequestHeader(String)
208 * @see #removeRequestHeader(String)
209 */
210 void addRequestHeader(Header header);
211
212 /***
213 * Gets the request header with the given name.
214 * If there are multiple headers with the same name,
215 * there values will be combined with the ',' separator as specified by RFC2616.
216 * Note that header-name matching is case insensitive.
217 *
218 * @param headerName the header name
219 * @return the header
220 */
221 Header getRequestHeader(String headerName);
222
223 /***
224 * Removes all request headers with the given name.
225 * Note that header-name matching is case insensitive.
226 *
227 * @param headerName the header name
228 */
229 void removeRequestHeader(String headerName);
230
231 /***
232 * Returns <tt>true</tt> if the HTTP method should automatically follow HTTP redirects
233 * (status code 302, etc.), <tt>false</tt> otherwise.
234 *
235 * @return <tt>true</tt> if the method will automatically follow HTTP redirects,
236 * <tt>false</tt> otherwise
237 */
238 boolean getFollowRedirects();
239
240 /***
241 * Sets whether or not the HTTP method should automatically follow HTTP redirects
242 * (status code 302, etc.)
243 *
244 * @param followRedirects <tt>true</tt> if the method will automatically follow redirects,
245 * <tt>false</tt> otherwise
246 */
247 void setFollowRedirects(boolean followRedirects);
248
249 /***
250 * Sets the query string of the HTTP method.
251 * It is responsibility of the caller to ensure that the path is
252 * properly encoded (URL safe). The string must not include an initial '?' character.
253 *
254 * @param queryString the query to be used in the request, with no leading '?' character
255 *
256 * @see #getQueryString()
257 * @see #setQueryString(NameValuePair[])
258 */
259 void setQueryString(String queryString);
260
261 /***
262 * Sets the query string of this HTTP method. The pairs are encoded as UTF-8 characters.
263 * To use a different charset the parameters can be encoded manually using EncodingUtil
264 * and set as a single String.
265 *
266 * @param params An array of <code>NameValuePair</code>s to use as the query string.
267 * The name/value pairs will be automatically URL encoded and should not
268 * have been encoded previously.
269 *
270 * @see #getQueryString()
271 * @see #setQueryString(String)
272 * @see org.apache.commons.httpclient.util.EncodingUtil#formUrlEncode(NameValuePair[], String)
273 */
274 void setQueryString(NameValuePair[] params);
275
276 /***
277 * Returns the query string of this HTTP method.
278 *
279 * @return the query string in URL encoded form, without a leading '?'.
280 *
281 * @see #setQueryString(NameValuePair[])
282 * @see #setQueryString(String)
283 */
284 String getQueryString();
285
286 /***
287 * Returns the current request headers for this HTTP method. The returned headers
288 * will be in the same order that they were added with <code>addRequestHeader</code>.
289 * If there are multiple request headers with the same name (e.g. <code>Cookie</code>),
290 * they will be returned as multiple entries in the array.
291 *
292 * @return an array containing all of the request headers
293 *
294 * @see #addRequestHeader(Header)
295 * @see #addRequestHeader(String,String)
296 */
297 Header[] getRequestHeaders();
298
299 // ---------------------------------------------------------------- Queries
300
301 /***
302 * Returns <tt>true</tt> the method is ready to execute, <tt>false</tt> otherwise.
303 *
304 * @return <tt>true</tt> if the method is ready to execute, <tt>false</tt> otherwise.
305 */
306 boolean validate();
307
308 /***
309 * Returns the status code associated with the latest response.
310 *
311 * @return The status code from the most recent execution of this method.
312 * If the method has not yet been executed, the result is undefined.
313 */
314 int getStatusCode();
315
316 /***
317 * Returns the status text (or "reason phrase") associated with the latest
318 * response.
319 *
320 * @return The status text from the most recent execution of this method.
321 * If the method has not yet been executed, the result is undefined.
322 */
323 String getStatusText();
324
325 /***
326 * Returns the response headers from the most recent execution of this request.
327 *
328 * @return A newly-created array containing all of the response headers,
329 * in the order in which they appeared in the response.
330 */
331 Header[] getResponseHeaders();
332
333 /***
334 * Returns the specified response header. Note that header-name matching is
335 * case insensitive.
336 *
337 * @param headerName The name of the header to be returned.
338 *
339 * @return The specified response header. If the repsonse contained multiple
340 * instances of the header, its values will be combined using the ','
341 * separator as specified by RFC2616.
342 */
343 Header getResponseHeader(String headerName);
344
345 /***
346 * Returns the response footers from the most recent execution of this request.
347 *
348 * @return an array containing the response footers in the order that they
349 * appeared in the response. If the response had no footers,
350 * an empty array will be returned.
351 */
352 Header[] getResponseFooters();
353
354 /***
355 * Return the specified response footer. Note that footer-name matching is
356 * case insensitive.
357 *
358 * @param footerName The name of the footer.
359 * @return The response footer.
360 */
361 Header getResponseFooter(String footerName);
362
363 /***
364 * Returns the response body of the HTTP method, if any, as an array of bytes.
365 * If the method has not yet been executed or the response has no body, <code>null</code>
366 * is returned. Note that this method does not propagate I/O exceptions.
367 * If an error occurs while reading the body, <code>null</code> will be returned.
368 *
369 * @return The response body, or <code>null</code> if the
370 * body is not available.
371 */
372 byte[] getResponseBody();
373
374 /***
375 * Returns the response body of the HTTP method, if any, as a {@link String}.
376 * If response body is not available or cannot be read, <tt>null</tt> is returned.
377 * The raw bytes in the body are converted to a <code>String</code> using the
378 * character encoding specified in the response's <tt>Content-Type</tt> header, or
379 * ISO-8859-1 if the response did not specify a character set.
380 * <p>
381 * Note that this method does not propagate I/O exceptions.
382 * If an error occurs while reading the body, <code>null</code> will be returned.
383 *
384 * @return The response body converted to a <code>String</code>, or <code>null</code>
385 * if the body is not available.
386 */
387 String getResponseBodyAsString();
388
389 /***
390 * Returns the response body of the HTTP method, if any, as an InputStream.
391 * If the response had no body or the method has not yet been executed,
392 * <code>null</code> is returned. Additionally, <code>null</code> may be returned
393 * if {@link #releaseConnection} has been called or
394 * if this method was called previously and the resulting stream was closed.
395 *
396 * @return The response body, or <code>null</code> if it is not available
397 *
398 * @throws IOException if an I/O (transport) problem occurs
399 */
400 InputStream getResponseBodyAsStream() throws IOException;
401
402 /***
403 * Returns <tt>true</tt> if the HTTP method has been already {@link #execute executed},
404 * but not {@link #recycle recycled}.
405 *
406 * @return <tt>true</tt> if the method has been executed, <tt>false</tt> otherwise
407 */
408 boolean hasBeenUsed();
409
410 // --------------------------------------------------------- Action Methods
411
412 /***
413 * Executes this method using the specified <code>HttpConnection</code> and
414 * <code>HttpState</code>.
415 *
416 * @param state the {@link HttpState state} information to associate with this method
417 * @param connection the {@link HttpConnection connection} used to execute
418 * this HTTP method
419 *
420 * @throws IOException If an I/O (transport) error occurs. Some transport exceptions
421 * can be recovered from.
422 * @throws HttpException If a protocol exception occurs. Usually protocol exceptions
423 * cannot be recovered from.
424 *
425 * @return the integer status code if one was obtained, or <tt>-1</tt>
426 */
427 int execute(HttpState state, HttpConnection connection)
428 throws HttpException, IOException;
429
430 /***
431 * Recycles the HTTP method so that it can be used again.
432 * Note that all of the instance variables will be reset
433 * once this method has been called. This method will also
434 * release the connection being used by this HTTP method.
435 *
436 * @see #releaseConnection()
437 */
438 void recycle();
439
440 /***
441 * Releases the connection being used by this HTTP method. In particular the
442 * connection is used to read the response (if there is one) and will be held
443 * until the response has been read. If the connection can be reused by other
444 * HTTP methods it is NOT closed at this point.
445 * <p>
446 * After this method is called, {@link #getResponseBodyAsStream} will return
447 * <code>null</code>, and {@link #getResponseBody} and {@link #getResponseBodyAsString}
448 * <em>may</em> return <code>null</code>.
449 */
450 void releaseConnection();
451
452 /***
453 * Add a footer to this method's response.
454 * <p>
455 * <b>Note:</b> This method is for
456 * internal use only and should not be called by external clients.
457 *
458 * @param footer the footer to add
459 *
460 * @since 2.0
461 */
462 void addResponseFooter(Header footer);
463
464 /***
465 * Returns the Status-Line from the most recent response for this method,
466 * or <code>null</code> if the method has not been executed.
467 *
468 * @return the status line, or <code>null</code> if the method has not been executed
469 *
470 * @since 2.0
471 */
472 StatusLine getStatusLine();
473
474 /***
475 * Returns <tt>true</tt> if the HTTP method should automatically handle HTTP
476 * authentication challenges (status code 401, etc.), <tt>false</tt> otherwise
477 *
478 * @return <tt>true</tt> if authentication challenges will be processed
479 * automatically, <tt>false</tt> otherwise.
480 *
481 * @since 2.0
482 *
483 * @see #setDoAuthentication(boolean)
484 */
485 boolean getDoAuthentication();
486
487 /***
488 * Sets whether or not the HTTP method should automatically handle HTTP
489 * authentication challenges (status code 401, etc.)
490 *
491 * @param doAuthentication <tt>true</tt> to process authentication challenges
492 * automatically, <tt>false</tt> otherwise.
493 *
494 * @since 2.0
495 *
496 * @see #getDoAuthentication()
497 */
498 void setDoAuthentication(boolean doAuthentication);
499
500 }
This page was automatically generated by Maven