View Javadoc
1 /* 2 * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java,v 1.23 2003/01/28 04:40:20 jsdever Exp $ 3 * $Revision: 1.23 $ 4 * $Date: 2003/01/28 04:40:20 $ 5 * 6 * ==================================================================== 7 * 8 * The Apache Software License, Version 1.1 9 * 10 * Copyright (c) 1999-2003 The Apache Software Foundation. All rights 11 * reserved. 12 * 13 * Redistribution and use in source and binary forms, with or without 14 * modification, are permitted provided that the following conditions 15 * are met: 16 * 17 * 1. Redistributions of source code must retain the above copyright 18 * notice, this list of conditions and the following disclaimer. 19 * 20 * 2. Redistributions in binary form must reproduce the above copyright 21 * notice, this list of conditions and the following disclaimer in 22 * the documentation and/or other materials provided with the 23 * distribution. 24 * 25 * 3. The end-user documentation included with the redistribution, if 26 * any, must include the following acknowlegement: 27 * "This product includes software developed by the 28 * Apache Software Foundation (http://www.apache.org/)." 29 * Alternately, this acknowlegement may appear in the software itself, 30 * if and wherever such third-party acknowlegements normally appear. 31 * 32 * 4. The names "The Jakarta Project", "Commons", and "Apache Software 33 * Foundation" must not be used to endorse or promote products derived 34 * from this software without prior written permission. For written 35 * permission, please contact apache@apache.org. 36 * 37 * 5. Products derived from this software may not be called "Apache" 38 * nor may "Apache" appear in their names without prior written 39 * permission of the Apache Group. 40 * 41 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED 42 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 43 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 44 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR 45 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 46 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 47 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 48 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 49 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 50 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 51 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 52 * SUCH DAMAGE. 53 * ==================================================================== 54 * 55 * This software consists of voluntary contributions made by many 56 * individuals on behalf of the Apache Software Foundation. For more 57 * information on the Apache Software Foundation, please see 58 * <http://www.apache.org/>;. 59 * 60 * [Additional notices, if required by prior licensing conditions] 61 * 62 */ 63 64 package org.apache.commons.httpclient; 65 66 import java.io.IOException; 67 import java.io.InputStream; 68 69 /*** 70 * <p> 71 * A request to be applied to an {@link HttpConnection}, and a container for the 72 * associated response. 73 * </p> 74 * @author <a href="mailto:remm@apache.org">Remy Maucherat</a> 75 * @author Rod Waldhoff 76 * @author <a href="jsdever@apache.org">Jeff Dever</a> 77 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a> 78 * 79 * @version $Revision: 1.23 $ $Date: 2003/01/28 04:40:20 $ 80 * @since 1.0 81 */ 82 public interface HttpMethod { 83 84 // ------------------------------------------- Property Setters and Getters 85 86 /*** 87 * Obtain the name of this method, suitable for use in the "request line", 88 * for example <tt>"GET"</tt> or <tt>"POST"</tt>. 89 * @return the name of this method 90 */ 91 String getName(); 92 93 /*** 94 * Gets the host configuration for this method. 95 * 96 * @return the HostConfiguration or <code>null</code> if none is set 97 */ 98 HostConfiguration getHostConfiguration(); 99 100 /*** 101 * Set the path part of my request. 102 * @param path the path to request 103 */ 104 void setPath(String path); 105 106 /*** 107 * Get the path part of my request. 108 * 109 * Calling this method AFTER the request 110 * has been executed will return the ACTUAL path, following any 301 or 302 111 * redirects (except for redirects off the initial server, which are not 112 * supported, or when HttpClient is set to not follow redirects; in either 113 * case, HttpClient returns the 301 or 302 status code). 114 * @return the path to request 115 */ 116 String getPath(); 117 118 /*** 119 * Gets the URI for this method. The URI will be absolute if the host 120 * configuration has been set or relative otherwise. 121 * 122 * @return URI 123 * 124 * @throws URIException if a URI cannot be constructed 125 */ 126 URI getURI() throws URIException; 127 128 /*** 129 * <p>Turns strict mode on or off. In strict mode (the default) we 130 * following the letter of RFC 2616, the Http 1.1 specification. If strict 131 * mode is turned off we attempt to violate the specification in the same 132 * way that most Http user agent's do (and many HTTP servers expect.</p> 133 * 134 * <p>NOTE: StrictMode is currently experimental and its functionaity may 135 * change in the future.</p> 136 * 137 * @param strictMode True to enable strict mode. 138 */ 139 void setStrictMode(boolean strictMode); 140 141 /*** 142 * Returns the value of strictMode. 143 * 144 * NOTE: StrictMode is currently experimental and its functionlaity may change in the future. 145 * 146 * @return true if strict mode is enabled. 147 */ 148 boolean isStrictMode(); 149 150 /*** 151 * Set the specified request header, overwriting any 152 * previous value. 153 * Note that header-name matching is case insensitive. 154 * @param headerName the header's name 155 * @param headerValue the header's value 156 */ 157 void setRequestHeader(String headerName, String headerValue); 158 159 /*** 160 * Set the specified request header, overwriting any 161 * previous value. 162 * Note that header-name matching is case insensitive. 163 * @param header the header 164 */ 165 void setRequestHeader(Header header); 166 167 /*** 168 * Adds the specified request header, NOT overwriting any 169 * previous value. 170 * Note that header-name matching is case insensitive. 171 * @param headerName the header's name 172 * @param headerValue the header's value 173 */ 174 void addRequestHeader(String headerName, String headerValue); 175 176 /*** 177 * Adds the specified request header, NOT overwriting any 178 * previous value. 179 * Note that header-name matching is case insensitive. 180 * @param header the header 181 */ 182 void addRequestHeader(Header header); 183 184 /*** 185 * Get the request header associated with the given name. 186 * Note that header-name matching is case insensitive. 187 * @param headerName the header name 188 * @return the header 189 */ 190 Header getRequestHeader(String headerName); 191 192 /*** 193 * Remove all request headers associated with the given name. 194 * Note that header-name matching is case insensitive. 195 * @param headerName the header name 196 */ 197 void removeRequestHeader(String headerName); 198 199 /*** 200 * Whether or not I should automatically follow 201 * HTTP redirects (status code 302, etc.) 202 * @return <tt>true</tt> if I will automatically follow HTTP redirects 203 */ 204 boolean getFollowRedirects(); 205 206 /*** 207 * Set whether or not I should automatically follow HTTP redirects (status 208 * code 302, etc.) 209 * @param followRedirects True if I should automatically follow redirects. 210 */ 211 void setFollowRedirects(boolean followRedirects); 212 213 /*** 214 * Set my query string. 215 * @param queryString the query string 216 */ 217 void setQueryString(String queryString); 218 219 /*** 220 * Set my query string. 221 * @param params an array of {@link NameValuePair}s 222 * to add as query string parameterss 223 */ 224 void setQueryString(NameValuePair[] params); 225 226 /*** 227 * Get my query string. 228 * @return my query string 229 */ 230 String getQueryString(); 231 232 /*** 233 * Return an array of my request headers. 234 * @return an array of request headers. 235 */ 236 Header[] getRequestHeaders(); 237 238 // ---------------------------------------------------------------- Queries 239 240 /*** 241 * Confirm that I am ready to execute. 242 * @return True if I am ready to execute. 243 */ 244 boolean validate(); 245 246 /*** 247 * Return the status code associated with the latest response. 248 * @return the status code. 249 */ 250 int getStatusCode(); 251 252 /*** 253 * Return the status text (or "reason phrase") associated with the latest 254 * response. 255 * @return The status text. 256 */ 257 String getStatusText(); 258 259 /*** 260 * Return an array of my response headers. 261 * @return An array of all the response headers. 262 */ 263 Header[] getResponseHeaders(); 264 265 /*** 266 * Return the specified response header. Note that header-name matching is 267 * case insensitive. 268 * @param headerName The name of the header to be returned. 269 * @return The specified response header. 270 */ 271 Header getResponseHeader(String headerName); 272 273 /*** 274 * Return an array of my response footers 275 * @return <tt>null</tt> if no footers are available 276 */ 277 Header[] getResponseFooters(); 278 279 /*** 280 * Return the specified response footer. Note that footer-name matching is 281 * case insensitive. 282 * @param footerName The name of the footer. 283 * @return The response footer. 284 */ 285 Header getResponseFooter(String footerName); 286 287 /*** 288 * Return my response body, if any, as a byte array. Otherwise return 289 * <tt>null</tt>. 290 * @return The response body. 291 */ 292 byte[] getResponseBody(); 293 294 /*** 295 * Return my response body, if any, as a {@link String}. Otherwise return 296 * <tt>null</tt>. 297 * @return response body. 298 */ 299 String getResponseBodyAsString(); 300 301 /*** 302 * Return my response body, if any, as an {@link InputStream}. Otherwise 303 * return <tt>null</tt>. 304 * @return As above. 305 * @throws IOException If an IO problem occurs. 306 */ 307 InputStream getResponseBodyAsStream() throws IOException; 308 309 /*** 310 * Return <tt>true</tt> if I have been {@link #execute executed} 311 * but not recycled. 312 * @return true if this has been used. 313 */ 314 boolean hasBeenUsed(); 315 316 // --------------------------------------------------------- Action Methods 317 318 /*** 319 * Execute this method. 320 * 321 * @param state state information to associate with this request 322 * @param connection the {@link HttpConnection} to write to/read from 323 * 324 * @throws IOException if an I/O error occurs 325 * @throws HttpException if an protocol exception occurs 326 * 327 * @return the integer status code if one was obtained, or <tt>-1</tt> 328 */ 329 int execute(HttpState state, HttpConnection connection) 330 throws HttpException, IOException; 331 332 /*** 333 * Recycle this method so that it can be used again. 334 * Note that all of my instance variables will be reset 335 * once this method has been called. 336 */ 337 void recycle(); 338 339 /*** 340 * Releases the connection being used by this method. In particular the 341 * connection is used to read the response(if there is one) and will be held 342 * until the response has been read. 343 */ 344 void releaseConnection(); 345 346 /*** 347 * Use this method internally to add footers. 348 * @param footer The footer to add. 349 * @since 2.0 350 */ 351 void addResponseFooter(Header footer); 352 353 /*** 354 * Return the Status-Line from the response. 355 * @return The status line 356 * @since 2.0 357 */ 358 StatusLine getStatusLine(); 359 360 /*** 361 * Whether or not I should automatically process responses where 362 * authentication is required (status code 401, etc.) 363 * 364 * @return <tt>true</tt> if authentications will be processed automatically 365 * @since 2.0 366 */ 367 boolean getDoAuthentication(); 368 369 /*** 370 * Set whether or not I should automatically process responses where 371 * authentication is required (status code 401, etc.) 372 * 373 * @param doAuthentication <tt>true</tt> to process authentications 374 * @since 2.0 375 */ 376 void setDoAuthentication(boolean doAuthentication); 377 378 }

This page was automatically generated by Maven