View Javadoc

1   /*
2    * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/oac.hc3x/trunk/src/java/org/apache/commons/httpclient/HttpMethod.java $
3    * $Revision$
4    * $Date$
5    *
6    * ====================================================================
7    *
8    *  Licensed to the Apache Software Foundation (ASF) under one or more
9    *  contributor license agreements.  See the NOTICE file distributed with
10   *  this work for additional information regarding copyright ownership.
11   *  The ASF licenses this file to You under the Apache License, Version 2.0
12   *  (the "License"); you may not use this file except in compliance with
13   *  the License.  You may obtain a copy of the License at
14   *
15   *      http://www.apache.org/licenses/LICENSE-2.0
16   *
17   *  Unless required by applicable law or agreed to in writing, software
18   *  distributed under the License is distributed on an "AS IS" BASIS,
19   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20   *  See the License for the specific language governing permissions and
21   *  limitations under the License.
22   * ====================================================================
23   *
24   * This software consists of voluntary contributions made by many
25   * individuals on behalf of the Apache Software Foundation.  For more
26   * information on the Apache Software Foundation, please see
27   * <http://www.apache.org/>.
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$ $Date$
51   * 
52   * @since 1.0
53   */
54  public interface HttpMethod {
55  
56      // ------------------------------------------- Property Setters and Getters
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     // ---------------------------------------------------------------- Queries
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     // --------------------------------------------------------- Action Methods
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 }