001: /*
002: * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java,v 1.43 2004/10/07 16:14:15 olegk Exp $
003: * $Revision: 480424 $
004: * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
005: *
006: * ====================================================================
007: *
008: * Licensed to the Apache Software Foundation (ASF) under one or more
009: * contributor license agreements. See the NOTICE file distributed with
010: * this work for additional information regarding copyright ownership.
011: * The ASF licenses this file to You under the Apache License, Version 2.0
012: * (the "License"); you may not use this file except in compliance with
013: * the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing, software
018: * distributed under the License is distributed on an "AS IS" BASIS,
019: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
020: * See the License for the specific language governing permissions and
021: * limitations under the License.
022: * ====================================================================
023: *
024: * This software consists of voluntary contributions made by many
025: * individuals on behalf of the Apache Software Foundation. For more
026: * information on the Apache Software Foundation, please see
027: * <http://www.apache.org/>.
028: *
029: */
030:
031: package org.apache.commons.httpclient;
032:
033: import java.io.IOException;
034: import java.io.InputStream;
035:
036: import org.apache.commons.httpclient.auth.AuthState;
037: import org.apache.commons.httpclient.params.HttpMethodParams;
038:
039: /**
040: * <p>
041: * HttpMethod interface represents a request to be sent via a
042: * {@link HttpConnection HTTP connection} and a corresponding response.
043: * </p>
044: * @author <a href="mailto:remm@apache.org">Remy Maucherat</a>
045: * @author Rod Waldhoff
046: * @author <a href="jsdever@apache.org">Jeff Dever</a>
047: * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
048: * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
049: *
050: * @version $Revision: 480424 $ $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
051: *
052: * @since 1.0
053: */
054: public interface HttpMethod {
055:
056: // ------------------------------------------- Property Setters and Getters
057:
058: /**
059: * Obtains the name of the HTTP method as used in the HTTP request line,
060: * for example <tt>"GET"</tt> or <tt>"POST"</tt>.
061: *
062: * @return the name of this method
063: */
064: String getName();
065:
066: /**
067: * Gets the host configuration for this method. The configuration specifies
068: * the server, port, protocol, and proxy server via which this method will
069: * send its HTTP request.
070: *
071: * @deprecated no longer applicable
072: *
073: * @return the HostConfiguration or <code>null</code> if none is set
074: */
075: HostConfiguration getHostConfiguration();
076:
077: /**
078: * Sets the path of the HTTP method.
079: * It is responsibility of the caller to ensure that the path is
080: * properly encoded (URL safe).
081: *
082: * @param path The path of the HTTP method. The path is expected
083: * to be URL encoded.
084: */
085: void setPath(String path);
086:
087: /**
088: * Returns the path of the HTTP method.
089: *
090: * Calling this method <em>after</em> the request has been executed will
091: * return the <em>actual</em> path, following any redirects automatically
092: * handled by this HTTP method.
093: *
094: * @return the path of the HTTP method, in URL encoded form
095: */
096: String getPath();
097:
098: /**
099: * 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: * Returns {@link HttpMethodParams HTTP protocol parameters} associated with this method.
532: *
533: * @since 3.0
534: *
535: * @see HttpMethodParams
536: */
537: public HttpMethodParams getParams();
538:
539: /**
540: * Assigns {@link HttpMethodParams HTTP protocol parameters} for this method.
541: *
542: * @since 3.0
543: *
544: * @see HttpMethodParams
545: */
546: public void setParams(final HttpMethodParams params);
547:
548: /**
549: * Returns the target host {@link AuthState authentication state}
550: *
551: * @return host authentication state
552: *
553: * @since 3.0
554: */
555: public AuthState getHostAuthState();
556:
557: /**
558: * Returns the proxy {@link AuthState authentication state}
559: *
560: * @return host authentication state
561: *
562: * @since 3.0
563: */
564: public AuthState getProxyAuthState();
565:
566: /**
567: * Returns <tt>true</tt> if the HTTP has been transmitted to the target
568: * server in its entirety, <tt>false</tt> otherwise. This flag can be useful
569: * for recovery logic. If the request has not been transmitted in its entirety,
570: * it is safe to retry the failed method.
571: *
572: * @return <tt>true</tt> if the request has been sent, <tt>false</tt> otherwise
573: */
574: boolean isRequestSent();
575:
576: }
|