View Javadoc

1   /*
2    * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java,v 1.39 2004/05/17 21:46:03 olegk Exp $
3    * $Revision: 1.39 $
4    * $Date: 2004/05/17 21:46:03 $
5    *
6    * ====================================================================
7    *
8    *  Copyright 1999-2004 The Apache Software Foundation
9    *
10   *  Licensed under the Apache License, Version 2.0 (the "License");
11   *  you may not use this file except in compliance with the License.
12   *  You may obtain a copy of the License at
13   *
14   *      http://www.apache.org/licenses/LICENSE-2.0
15   *
16   *  Unless required by applicable law or agreed to in writing, software
17   *  distributed under the License is distributed on an "AS IS" BASIS,
18   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19   *  See the License for the specific language governing permissions and
20   *  limitations under the License.
21   * ====================================================================
22   *
23   * This software consists of voluntary contributions made by many
24   * individuals on behalf of the Apache Software Foundation.  For more
25   * information on the Apache Software Foundation, please see
26   * <http://www.apache.org/>.
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      // ------------------------------------------- Property Setters and Getters
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     // ---------------------------------------------------------------- Queries
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     // --------------------------------------------------------- Action Methods
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 }