View Javadoc

1   /*
2    * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java,v 1.41 2004/07/05 22:46:58 olegk Exp $
3    * $Revision: 1.41 $
4    * $Date: 2004/07/05 22:46:58 $
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.41 $ $Date: 2004/07/05 22:46:58 $
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      * @deprecated no longer supported and will be removed in the future
463      *             version of HttpClient
464      */
465     void recycle();
466 
467     /***
468      * Releases the connection being used by this HTTP method. In particular the
469      * connection is used to read the response (if there is one) and will be held
470      * until the response has been read. If the connection can be reused by other 
471      * HTTP methods it is NOT closed at this point.
472      * <p>
473      * After this method is called, {@link #getResponseBodyAsStream} will return
474      * <code>null</code>, and {@link #getResponseBody} and {@link #getResponseBodyAsString}
475      * <em>may</em> return <code>null</code>. 
476      */
477     void releaseConnection();
478 
479     /***
480      * Add a footer to this method's response.
481      * <p>
482      * <b>Note:</b> This method is for
483      * internal use only and should not be called by external clients.
484      * 
485      * @param footer the footer to add
486      * 
487      * @since 2.0
488      */
489     void addResponseFooter(Header footer);
490 
491     /*** 
492      * Returns the Status-Line from the most recent response for this method,
493      * or <code>null</code> if the method has not been executed.
494      * 
495      * @return the status line, or <code>null</code> if the method has not been executed
496      * 
497      * @since 2.0
498      */
499     StatusLine getStatusLine();
500 
501     /***
502      * Returns <tt>true</tt> if the HTTP method should automatically handle HTTP 
503      * authentication challenges (status code 401, etc.), <tt>false</tt> otherwise
504      *
505      * @return <tt>true</tt> if authentication challenges will be processed 
506      * automatically, <tt>false</tt> otherwise.
507      * 
508      * @since 2.0
509      * 
510      * @see #setDoAuthentication(boolean)
511      */
512     boolean getDoAuthentication();
513 
514     /***
515      * Sets whether or not the HTTP method should automatically handle HTTP 
516      * authentication challenges (status code 401, etc.)
517      *
518      * @param doAuthentication <tt>true</tt> to process authentication challenges
519      * automatically, <tt>false</tt> otherwise.
520      * 
521      * @since 2.0
522      * 
523      * @see #getDoAuthentication()
524      */
525     void setDoAuthentication(boolean doAuthentication);
526 
527 
528     /***
529      * Returns {@link HttpMethodParams HTTP protocol parameters} associated with this method.
530      * 
531      * @since 3.0
532      * 
533      * @see HttpMethodParams
534      */
535     public HttpMethodParams getParams();
536 
537     /***
538      * Assigns {@link HttpMethodParams HTTP protocol parameters} for this method.
539      * 
540      * @since 3.0
541      * 
542      * @see HttpMethodParams
543      */
544     public void setParams(final HttpMethodParams params);
545 
546     /***
547      * Returns the target host {@link AuthState authentication state}
548      * 
549      * @return host authentication state
550      * 
551      * @since 3.0
552      */
553     public AuthState getHostAuthState();
554 
555     /***
556      * Returns the proxy {@link AuthState authentication state}
557      * 
558      * @return host authentication state
559      * 
560      * @since 3.0
561      */
562     public AuthState getProxyAuthState();
563 
564     /***
565      * Returns <tt>true</tt> if the HTTP has been transmitted to the target
566      * server in its entirety, <tt>false</tt> otherwise. This flag can be useful 
567      * for recovery logic. If the request has not been transmitted in its entirety,
568      * it is safe to retry the failed method.
569      * 
570      * @return <tt>true</tt> if the request has been sent, <tt>false</tt> otherwise
571      */
572     boolean isRequestSent();
573 
574 }