HttpMethod.java
1 /* 2 * $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 $ 3 * $Revision: 480424 $ 4 * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $ 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: 480424 $ $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $ 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 }