HttpMethod


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