1 /* 2 * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.net; 27 28 import java.io.InputStream; 29 import java.io.IOException; 30 import java.security.Permission; 31 import java.util.Date; 32 33 /** 34 * A URLConnection with support for HTTP-specific features. See 35 * <A HREF="http://www.w3.org/pub/WWW/Protocols/"> the spec </A> for 36 * details. 37 * <p> 38 * 39 * <p>Uses of this class follow a pattern: 40 * <ol> 41 * <li>Obtain a new {@code HttpURLConnection} by calling {@link 42 * URL#openConnection() URL.openConnection()} and casting the result to 43 * {@code HttpURLConnection}. 44 * <li>Prepare the request. The primary property of a request is its URI. 45 * Request headers may also include metadata such as credentials, preferred 46 * content types, and session cookies. 47 * <li>Optionally upload a request body. Instances must be configured with 48 * {@link #setDoOutput(boolean) setDoOutput(true)} if they include a 49 * request body. Transmit data by writing to the stream returned by {@link 50 * #getOutputStream()}. 51 * <li>Read the response. Response headers typically include metadata such as 52 * the response body's content type and length, modified dates and session 53 * cookies. The response body may be read from the stream returned by {@link 54 * #getInputStream()}. If the response has no body, that method returns an 55 * empty stream. 56 * <li>Disconnect. Once the response body has been read, the {@code 57 * HttpURLConnection} should be closed by calling {@link #disconnect()}. 58 * Disconnecting releases the resources held by a connection so they may 59 * be closed or reused. 60 * </ol> 61 * 62 * <p>For example, to retrieve the webpage at {@code http://www.android.com/}: 63 * <pre> {@code 64 * URL url = new URL("http://www.android.com/"); 65 * HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection(); 66 * try { 67 * InputStream in = new BufferedInputStream(urlConnection.getInputStream()); 68 * readStream(in); 69 * } finally { 70 * urlConnection.disconnect(); 71 * } 72 * }</pre> 73 * 74 * <h3>Secure Communication with HTTPS</h3> 75 * Calling {@link URL#openConnection()} on a URL with the "https" 76 * scheme will return an {@code HttpsURLConnection}, which allows for 77 * overriding the default {@link javax.net.ssl.HostnameVerifier 78 * HostnameVerifier} and {@link javax.net.ssl.SSLSocketFactory 79 * SSLSocketFactory}. An application-supplied {@code SSLSocketFactory} 80 * created from an {@link javax.net.ssl.SSLContext SSLContext} can 81 * provide a custom {@link javax.net.ssl.X509TrustManager 82 * X509TrustManager} for verifying certificate chains and a custom 83 * {@link javax.net.ssl.X509KeyManager X509KeyManager} for supplying 84 * client certificates. See {@link javax.net.ssl.HttpsURLConnection 85 * HttpsURLConnection} for more details. 86 * 87 * <h3>Response Handling</h3> 88 * {@code HttpURLConnection} will follow up to five HTTP redirects. It will 89 * follow redirects from one origin server to another. This implementation 90 * doesn't follow redirects from HTTPS to HTTP or vice versa. 91 * 92 * <p>If the HTTP response indicates that an error occurred, {@link 93 * #getInputStream()} will throw an {@link IOException}. Use {@link 94 * #getErrorStream()} to read the error response. The headers can be read in 95 * the normal way using {@link #getHeaderFields()}, 96 * 97 * <h3>Posting Content</h3> 98 * To upload data to a web server, configure the connection for output using 99 * {@link #setDoOutput(boolean) setDoOutput(true)}. 100 * 101 * <p>For best performance, you should call either {@link 102 * #setFixedLengthStreamingMode(int)} when the body length is known in advance, 103 * or {@link #setChunkedStreamingMode(int)} when it is not. Otherwise {@code 104 * HttpURLConnection} will be forced to buffer the complete request body in 105 * memory before it is transmitted, wasting (and possibly exhausting) heap and 106 * increasing latency. 107 * 108 * <p>For example, to perform an upload: <pre> {@code 109 * HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection(); 110 * try { 111 * urlConnection.setDoOutput(true); 112 * urlConnection.setChunkedStreamingMode(0); 113 * 114 * OutputStream out = new BufferedOutputStream(urlConnection.getOutputStream()); 115 * writeStream(out); 116 * 117 * InputStream in = new BufferedInputStream(urlConnection.getInputStream()); 118 * readStream(in); 119 * } finally { 120 * urlConnection.disconnect(); 121 * } 122 * }</pre> 123 * 124 * <h3>Performance</h3> 125 * The input and output streams returned by this class are <strong>not 126 * buffered</strong>. Most callers should wrap the returned streams with {@link 127 * java.io.BufferedInputStream BufferedInputStream} or {@link 128 * java.io.BufferedOutputStream BufferedOutputStream}. Callers that do only bulk 129 * reads or writes may omit buffering. 130 * 131 * <p>When transferring large amounts of data to or from a server, use streams 132 * to limit how much data is in memory at once. Unless you need the entire 133 * body to be in memory at once, process it as a stream (rather than storing 134 * the complete body as a single byte array or string). 135 * 136 * <p>To reduce latency, this class may reuse the same underlying {@code Socket} 137 * for multiple request/response pairs. As a result, HTTP connections may be 138 * held open longer than necessary. Calls to {@link #disconnect()} may return 139 * the socket to a pool of connected sockets. This behavior can be disabled by 140 * setting the {@code http.keepAlive} system property to {@code false} before 141 * issuing any HTTP requests. The {@code http.maxConnections} property may be 142 * used to control how many idle connections to each server will be held. 143 * 144 * <p>By default, this implementation of {@code HttpURLConnection} requests that 145 * servers use gzip compression and it automatically decompresses the data for 146 * callers of {@link #getInputStream()}. The Content-Encoding and Content-Length 147 * response headers are cleared in this case. Gzip compression can be disabled by 148 * setting the acceptable encodings in the request header: <pre> {@code 149 * urlConnection.setRequestProperty("Accept-Encoding", "identity"); 150 * }</pre> 151 * 152 * <p>Setting the Accept-Encoding request header explicitly disables automatic 153 * decompression and leaves the response headers intact; callers must handle 154 * decompression as needed, according to the Content-Encoding header of the 155 * response. 156 * 157 * <p>{@link #getContentLength()} returns the number of bytes transmitted and 158 * cannot be used to predict how many bytes can be read from 159 * {@link #getInputStream()} for compressed streams. Instead, read that stream 160 * until it is exhausted, i.e. when {@link InputStream#read} returns -1. 161 * 162 * <h3>Handling Network Sign-On</h3> 163 * Some Wi-Fi networks block Internet access until the user clicks through a 164 * sign-on page. Such sign-on pages are typically presented by using HTTP 165 * redirects. You can use {@link #getURL()} to test if your connection has been 166 * unexpectedly redirected. This check is not valid until <strong>after</strong> 167 * the response headers have been received, which you can trigger by calling 168 * {@link #getHeaderFields()} or {@link #getInputStream()}. For example, to 169 * check that a response was not redirected to an unexpected host: 170 * <pre> {@code 171 * HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection(); 172 * try { 173 * InputStream in = new BufferedInputStream(urlConnection.getInputStream()); 174 * if (!url.getHost().equals(urlConnection.getURL().getHost())) { 175 * // we were redirected! Kick the user out to the browser to sign on? 176 * } 177 * ... 178 * } finally { 179 * urlConnection.disconnect(); 180 * } 181 * }</pre> 182 * 183 * <h3>HTTP Authentication</h3> 184 * {@code HttpURLConnection} supports <a 185 * href="http://www.ietf.org/rfc/rfc2617">HTTP basic authentication</a>. Use 186 * {@link Authenticator} to set the VM-wide authentication handler: 187 * <pre> {@code 188 * Authenticator.setDefault(new Authenticator() { 189 * protected PasswordAuthentication getPasswordAuthentication() { 190 * return new PasswordAuthentication(username, password.toCharArray()); 191 * } 192 * }); 193 * }</pre> 194 * Unless paired with HTTPS, this is <strong>not</strong> a secure mechanism for 195 * user authentication. In particular, the username, password, request and 196 * response are all transmitted over the network without encryption. 197 * 198 * <h3>Sessions with Cookies</h3> 199 * To establish and maintain a potentially long-lived session between client 200 * and server, {@code HttpURLConnection} includes an extensible cookie manager. 201 * Enable VM-wide cookie management using {@link CookieHandler} and {@link 202 * CookieManager}: <pre> {@code 203 * CookieManager cookieManager = new CookieManager(); 204 * CookieHandler.setDefault(cookieManager); 205 * }</pre> 206 * By default, {@code CookieManager} accepts cookies from the <a 207 * href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec1.html">origin 208 * server</a> only. Two other policies are included: {@link 209 * CookiePolicy#ACCEPT_ALL} and {@link CookiePolicy#ACCEPT_NONE}. Implement 210 * {@link CookiePolicy} to define a custom policy. 211 * 212 * <p>The default {@code CookieManager} keeps all accepted cookies in memory. It 213 * will forget these cookies when the VM exits. Implement {@link CookieStore} to 214 * define a custom cookie store. 215 * 216 * <p>In addition to the cookies set by HTTP responses, you may set cookies 217 * programmatically. To be included in HTTP request headers, cookies must have 218 * the domain and path properties set. 219 * 220 * <p>By default, new instances of {@code HttpCookie} work only with servers 221 * that support <a href="http://www.ietf.org/rfc/rfc2965.txt">RFC 2965</a> 222 * cookies. Many web servers support only the older specification, <a 223 * href="http://www.ietf.org/rfc/rfc2109.txt">RFC 2109</a>. For compatibility 224 * with the most web servers, set the cookie version to 0. 225 * 226 * <p>For example, to receive {@code www.twitter.com} in French: <pre> {@code 227 * HttpCookie cookie = new HttpCookie("lang", "fr"); 228 * cookie.setDomain("twitter.com"); 229 * cookie.setPath("/"); 230 * cookie.setVersion(0); 231 * cookieManager.getCookieStore().add(new URI("http://twitter.com/"), cookie); 232 * }</pre> 233 * 234 * <h3>HTTP Methods</h3> 235 * <p>{@code HttpURLConnection} uses the {@code GET} method by default. It will 236 * use {@code POST} if {@link #setDoOutput setDoOutput(true)} has been called. 237 * Other HTTP methods ({@code OPTIONS}, {@code HEAD}, {@code PUT}, {@code 238 * DELETE} and {@code TRACE}) can be used with {@link #setRequestMethod}. 239 * 240 * <h3>Proxies</h3> 241 * By default, this class will connect directly to the <a 242 * href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec1.html">origin 243 * server</a>. It can also connect via an {@link Proxy.Type#HTTP HTTP} or {@link 244 * Proxy.Type#SOCKS SOCKS} proxy. To use a proxy, use {@link 245 * URL#openConnection(Proxy) URL.openConnection(Proxy)} when creating the 246 * connection. 247 * 248 * <h3>IPv6 Support</h3> 249 * <p>This class includes transparent support for IPv6. For hosts with both IPv4 250 * and IPv6 addresses, it will attempt to connect to each of a host's addresses 251 * until a connection is established. 252 * 253 * <h3>Response Caching</h3> 254 * Android 4.0 (Ice Cream Sandwich, API level 15) includes a response cache. See 255 * {@code android.net.http.HttpResponseCache} for instructions on enabling HTTP 256 * caching in your application. 257 * 258 * <h3>Avoiding Bugs In Earlier Releases</h3> 259 * Prior to Android 2.2 (Froyo), this class had some frustrating bugs. In 260 * particular, calling {@code close()} on a readable {@code InputStream} could 261 * <a href="http://code.google.com/p/android/issues/detail?id=2939">poison the 262 * connection pool</a>. Work around this by disabling connection pooling: 263 * <pre> {@code 264 * private void disableConnectionReuseIfNecessary() { 265 * // Work around pre-Froyo bugs in HTTP connection reuse. 266 * if (Integer.parseInt(Build.VERSION.SDK) < Build.VERSION_CODES.FROYO) { 267 * System.setProperty("http.keepAlive", "false"); 268 * } 269 * }}</pre> 270 * 271 * <p>Each instance of {@code HttpURLConnection} may be used for one 272 * request/response pair. Instances of this class are not thread safe. 273 * 274 * @since JDK1.1 275 */ 276 abstract public class HttpURLConnection extends URLConnection { 277 /* instance variables */ 278 279 /** 280 * The HTTP method (GET,POST,PUT,etc.). 281 */ 282 protected String method = "GET"; 283 284 /** 285 * The chunk-length when using chunked encoding streaming mode for output. 286 * A value of <code>-1</code> means chunked encoding is disabled for output. 287 * @since 1.5 288 */ 289 protected int chunkLength = -1; 290 291 /** 292 * The fixed content-length when using fixed-length streaming mode. 293 * A value of <code>-1</code> means fixed-length streaming mode is disabled 294 * for output. 295 * 296 * <P> <B>NOTE:</B> {@link #fixedContentLengthLong} is recommended instead 297 * of this field, as it allows larger content lengths to be set. 298 * 299 * @since 1.5 300 */ 301 protected int fixedContentLength = -1; 302 303 /** 304 * The fixed content-length when using fixed-length streaming mode. 305 * A value of {@code -1} means fixed-length streaming mode is disabled 306 * for output. 307 * 308 * @since 1.7 309 */ 310 protected long fixedContentLengthLong = -1; 311 312 /** 313 * Returns the key for the <code>n</code><sup>th</sup> header field. 314 * Some implementations may treat the <code>0</code><sup>th</sup> 315 * header field as special, i.e. as the status line returned by the HTTP 316 * server. In this case, {@link #getHeaderField(int) getHeaderField(0)} returns the status 317 * line, but <code>getHeaderFieldKey(0)</code> returns null. 318 * 319 * @param n an index, where n >=0. 320 * @return the key for the <code>n</code><sup>th</sup> header field, 321 * or <code>null</code> if the key does not exist. 322 */ 323 public String getHeaderFieldKey (int n) { 324 return null; 325 } 326 327 /** 328 * This method is used to enable streaming of a HTTP request body 329 * without internal buffering, when the content length is known in 330 * advance. 331 * <p> 332 * An exception will be thrown if the application 333 * attempts to write more data than the indicated 334 * content-length, or if the application closes the OutputStream 335 * before writing the indicated amount. 336 * <p> 337 * When output streaming is enabled, authentication 338 * and redirection cannot be handled automatically. 339 * A HttpRetryException will be thrown when reading 340 * the response if authentication or redirection are required. 341 * This exception can be queried for the details of the error. 342 * <p> 343 * This method must be called before the URLConnection is connected. 344 * <p> 345 * <B>NOTE:</B> {@link #setFixedLengthStreamingMode(long)} is recommended 346 * instead of this method as it allows larger content lengths to be set. 347 * 348 * @param contentLength The number of bytes which will be written 349 * to the OutputStream. 350 * 351 * @throws IllegalStateException if URLConnection is already connected 352 * or if a different streaming mode is already enabled. 353 * 354 * @throws IllegalArgumentException if a content length less than 355 * zero is specified. 356 * 357 * @see #setChunkedStreamingMode(int) 358 * @since 1.5 359 */ 360 public void setFixedLengthStreamingMode (int contentLength) { 361 if (connected) { 362 throw new IllegalStateException ("Already connected"); 363 } 364 if (chunkLength != -1) { 365 throw new IllegalStateException ("Chunked encoding streaming mode set"); 366 } 367 if (contentLength < 0) { 368 throw new IllegalArgumentException ("invalid content length"); 369 } 370 fixedContentLength = contentLength; 371 } 372 373 /** 374 * This method is used to enable streaming of a HTTP request body 375 * without internal buffering, when the content length is known in 376 * advance. 377 * 378 * <P> An exception will be thrown if the application attempts to write 379 * more data than the indicated content-length, or if the application 380 * closes the OutputStream before writing the indicated amount. 381 * 382 * <P> When output streaming is enabled, authentication and redirection 383 * cannot be handled automatically. A {@linkplain HttpRetryException} will 384 * be thrown when reading the response if authentication or redirection 385 * are required. This exception can be queried for the details of the 386 * error. 387 * 388 * <P> This method must be called before the URLConnection is connected. 389 * 390 * <P> The content length set by invoking this method takes precedence 391 * over any value set by {@link #setFixedLengthStreamingMode(int)}. 392 * 393 * @param contentLength 394 * The number of bytes which will be written to the OutputStream. 395 * 396 * @throws IllegalStateException 397 * if URLConnection is already connected or if a different 398 * streaming mode is already enabled. 399 * 400 * @throws IllegalArgumentException 401 * if a content length less than zero is specified. 402 * 403 * @since 1.7 404 */ 405 public void setFixedLengthStreamingMode(long contentLength) { 406 if (connected) { 407 throw new IllegalStateException("Already connected"); 408 } 409 if (chunkLength != -1) { 410 throw new IllegalStateException( 411 "Chunked encoding streaming mode set"); 412 } 413 if (contentLength < 0) { 414 throw new IllegalArgumentException("invalid content length"); 415 } 416 fixedContentLengthLong = contentLength; 417 } 418 419 /* Default chunk size (including chunk header) if not specified; 420 * we want to keep this in sync with the one defined in 421 * sun.net.www.http.ChunkedOutputStream 422 */ 423 private static final int DEFAULT_CHUNK_SIZE = 4096; 424 425 /** 426 * This method is used to enable streaming of a HTTP request body 427 * without internal buffering, when the content length is <b>not</b> 428 * known in advance. In this mode, chunked transfer encoding 429 * is used to send the request body. Note, not all HTTP servers 430 * support this mode. 431 * <p> 432 * When output streaming is enabled, authentication 433 * and redirection cannot be handled automatically. 434 * A HttpRetryException will be thrown when reading 435 * the response if authentication or redirection are required. 436 * This exception can be queried for the details of the error. 437 * <p> 438 * This method must be called before the URLConnection is connected. 439 * 440 * @param chunklen The number of bytes to write in each chunk. 441 * If chunklen is less than or equal to zero, a default 442 * value will be used. 443 * 444 * @throws IllegalStateException if URLConnection is already connected 445 * or if a different streaming mode is already enabled. 446 * 447 * @see #setFixedLengthStreamingMode(int) 448 * @since 1.5 449 */ 450 public void setChunkedStreamingMode (int chunklen) { 451 if (connected) { 452 throw new IllegalStateException ("Can't set streaming mode: already connected"); 453 } 454 if (fixedContentLength != -1 || fixedContentLengthLong != -1) { 455 throw new IllegalStateException ("Fixed length streaming mode set"); 456 } 457 chunkLength = chunklen <=0? DEFAULT_CHUNK_SIZE : chunklen; 458 } 459 460 /** 461 * Returns the value for the <code>n</code><sup>th</sup> header field. 462 * Some implementations may treat the <code>0</code><sup>th</sup> 463 * header field as special, i.e. as the status line returned by the HTTP 464 * server. 465 * <p> 466 * This method can be used in conjunction with the 467 * {@link #getHeaderFieldKey getHeaderFieldKey} method to iterate through all 468 * the headers in the message. 469 * 470 * @param n an index, where n>=0. 471 * @return the value of the <code>n</code><sup>th</sup> header field, 472 * or <code>null</code> if the value does not exist. 473 * @see java.net.HttpURLConnection#getHeaderFieldKey(int) 474 */ 475 public String getHeaderField(int n) { 476 return null; 477 } 478 479 /** 480 * An <code>int</code> representing the three digit HTTP Status-Code. 481 * <ul> 482 * <li> 1xx: Informational 483 * <li> 2xx: Success 484 * <li> 3xx: Redirection 485 * <li> 4xx: Client Error 486 * <li> 5xx: Server Error 487 * </ul> 488 */ 489 protected int responseCode = -1; 490 491 /** 492 * The HTTP response message. 493 */ 494 protected String responseMessage = null; 495 496 /* static variables */ 497 498 /* do we automatically follow redirects? The default is true. */ 499 private static boolean followRedirects = true; 500 501 /** 502 * If <code>true</code>, the protocol will automatically follow redirects. 503 * If <code>false</code>, the protocol will not automatically follow 504 * redirects. 505 * <p> 506 * This field is set by the <code>setInstanceFollowRedirects</code> 507 * method. Its value is returned by the <code>getInstanceFollowRedirects</code> 508 * method. 509 * <p> 510 * Its default value is based on the value of the static followRedirects 511 * at HttpURLConnection construction time. 512 * 513 * @see java.net.HttpURLConnection#setInstanceFollowRedirects(boolean) 514 * @see java.net.HttpURLConnection#getInstanceFollowRedirects() 515 * @see java.net.HttpURLConnection#setFollowRedirects(boolean) 516 */ 517 protected boolean instanceFollowRedirects = followRedirects; 518 519 /* valid HTTP methods */ 520 private static final String[] methods = { 521 "GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE" 522 }; 523 524 /** 525 * Constructor for the HttpURLConnection. 526 * @param u the URL 527 */ 528 protected HttpURLConnection (URL u) { 529 super(u); 530 } 531 532 /** 533 * Sets whether HTTP redirects (requests with response code 3xx) should 534 * be automatically followed by this class. True by default. Applets 535 * cannot change this variable. 536 * <p> 537 * If there is a security manager, this method first calls 538 * the security manager's <code>checkSetFactory</code> method 539 * to ensure the operation is allowed. 540 * This could result in a SecurityException. 541 * 542 * @param set a <code>boolean</code> indicating whether or not 543 * to follow HTTP redirects. 544 * @exception SecurityException if a security manager exists and its 545 * <code>checkSetFactory</code> method doesn't 546 * allow the operation. 547 * @see SecurityManager#checkSetFactory 548 * @see #getFollowRedirects() 549 */ 550 public static void setFollowRedirects(boolean set) { 551 SecurityManager sec = System.getSecurityManager(); 552 if (sec != null) { 553 // seems to be the best check here... 554 sec.checkSetFactory(); 555 } 556 followRedirects = set; 557 } 558 559 /** 560 * Returns a <code>boolean</code> indicating 561 * whether or not HTTP redirects (3xx) should 562 * be automatically followed. 563 * 564 * @return <code>true</code> if HTTP redirects should 565 * be automatically followed, <tt>false</tt> if not. 566 * @see #setFollowRedirects(boolean) 567 */ 568 public static boolean getFollowRedirects() { 569 return followRedirects; 570 } 571 572 /** 573 * Sets whether HTTP redirects (requests with response code 3xx) should 574 * be automatically followed by this <code>HttpURLConnection</code> 575 * instance. 576 * <p> 577 * The default value comes from followRedirects, which defaults to 578 * true. 579 * 580 * @param followRedirects a <code>boolean</code> indicating 581 * whether or not to follow HTTP redirects. 582 * 583 * @see java.net.HttpURLConnection#instanceFollowRedirects 584 * @see #getInstanceFollowRedirects 585 * @since 1.3 586 */ 587 public void setInstanceFollowRedirects(boolean followRedirects) { 588 instanceFollowRedirects = followRedirects; 589 } 590 591 /** 592 * Returns the value of this <code>HttpURLConnection</code>'s 593 * <code>instanceFollowRedirects</code> field. 594 * 595 * @return the value of this <code>HttpURLConnection</code>'s 596 * <code>instanceFollowRedirects</code> field. 597 * @see java.net.HttpURLConnection#instanceFollowRedirects 598 * @see #setInstanceFollowRedirects(boolean) 599 * @since 1.3 600 */ 601 public boolean getInstanceFollowRedirects() { 602 return instanceFollowRedirects; 603 } 604 605 /** 606 * Set the method for the URL request, one of: 607 * <UL> 608 * <LI>GET 609 * <LI>POST 610 * <LI>HEAD 611 * <LI>OPTIONS 612 * <LI>PUT 613 * <LI>DELETE 614 * <LI>TRACE 615 * </UL> are legal, subject to protocol restrictions. The default 616 * method is GET. 617 * 618 * @param method the HTTP method 619 * @exception ProtocolException if the method cannot be reset or if 620 * the requested method isn't valid for HTTP. 621 * @exception SecurityException if a security manager is set and the 622 * method is "TRACE", but the "allowHttpTrace" 623 * NetPermission is not granted. 624 * @see #getRequestMethod() 625 */ 626 public void setRequestMethod(String method) throws ProtocolException { 627 if (connected) { 628 throw new ProtocolException("Can't reset method: already connected"); 629 } 630 // This restriction will prevent people from using this class to 631 // experiment w/ new HTTP methods using java. But it should 632 // be placed for security - the request String could be 633 // arbitrarily long. 634 635 for (int i = 0; i < methods.length; i++) { 636 if (methods[i].equals(method)) { 637 if (method.equals("TRACE")) { 638 SecurityManager s = System.getSecurityManager(); 639 if (s != null) { 640 s.checkPermission(new NetPermission("allowHttpTrace")); 641 } 642 } 643 this.method = method; 644 return; 645 } 646 } 647 throw new ProtocolException("Invalid HTTP method: " + method); 648 } 649 650 /** 651 * Get the request method. 652 * @return the HTTP request method 653 * @see #setRequestMethod(java.lang.String) 654 */ 655 public String getRequestMethod() { 656 return method; 657 } 658 659 /** 660 * Gets the status code from an HTTP response message. 661 * For example, in the case of the following status lines: 662 * <PRE> 663 * HTTP/1.0 200 OK 664 * HTTP/1.0 401 Unauthorized 665 * </PRE> 666 * It will return 200 and 401 respectively. 667 * Returns -1 if no code can be discerned 668 * from the response (i.e., the response is not valid HTTP). 669 * @throws IOException if an error occurred connecting to the server. 670 * @return the HTTP Status-Code, or -1 671 */ 672 public int getResponseCode() throws IOException { 673 /* 674 * We're got the response code already 675 */ 676 if (responseCode != -1) { 677 return responseCode; 678 } 679 680 /* 681 * Ensure that we have connected to the server. Record 682 * exception as we need to re-throw it if there isn't 683 * a status line. 684 */ 685 Exception exc = null; 686 try { 687 getInputStream(); 688 } catch (Exception e) { 689 exc = e; 690 } 691 692 /* 693 * If we can't a status-line then re-throw any exception 694 * that getInputStream threw. 695 */ 696 String statusLine = getHeaderField(0); 697 if (statusLine == null) { 698 if (exc != null) { 699 if (exc instanceof RuntimeException) 700 throw (RuntimeException)exc; 701 else 702 throw (IOException)exc; 703 } 704 return -1; 705 } 706 707 /* 708 * Examine the status-line - should be formatted as per 709 * section 6.1 of RFC 2616 :- 710 * 711 * Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase 712 * 713 * If status line can't be parsed return -1. 714 */ 715 if (statusLine.startsWith("HTTP/1.")) { 716 int codePos = statusLine.indexOf(' '); 717 if (codePos > 0) { 718 719 int phrasePos = statusLine.indexOf(' ', codePos+1); 720 if (phrasePos > 0 && phrasePos < statusLine.length()) { 721 responseMessage = statusLine.substring(phrasePos+1); 722 } 723 724 // deviation from RFC 2616 - don't reject status line 725 // if SP Reason-Phrase is not included. 726 if (phrasePos < 0) 727 phrasePos = statusLine.length(); 728 729 try { 730 responseCode = Integer.parseInt 731 (statusLine.substring(codePos+1, phrasePos)); 732 return responseCode; 733 } catch (NumberFormatException e) { } 734 } 735 } 736 return -1; 737 } 738 739 /** 740 * Gets the HTTP response message, if any, returned along with the 741 * response code from a server. From responses like: 742 * <PRE> 743 * HTTP/1.0 200 OK 744 * HTTP/1.0 404 Not Found 745 * </PRE> 746 * Extracts the Strings "OK" and "Not Found" respectively. 747 * Returns null if none could be discerned from the responses 748 * (the result was not valid HTTP). 749 * @throws IOException if an error occurred connecting to the server. 750 * @return the HTTP response message, or <code>null</code> 751 */ 752 public String getResponseMessage() throws IOException { 753 getResponseCode(); 754 return responseMessage; 755 } 756 757 public long getHeaderFieldDate(String name, long Default) { 758 String dateString = getHeaderField(name); 759 try { 760 if (dateString.indexOf("GMT") == -1) { 761 dateString = dateString+" GMT"; 762 } 763 return Date.parse(dateString); 764 } catch (Exception e) { 765 } 766 return Default; 767 } 768 769 770 /** 771 * Indicates that other requests to the server 772 * are unlikely in the near future. Calling disconnect() 773 * should not imply that this HttpURLConnection 774 * instance can be reused for other requests. 775 */ 776 public abstract void disconnect(); 777 778 /** 779 * Indicates if the connection is going through a proxy. 780 * @return a boolean indicating if the connection is 781 * using a proxy. 782 */ 783 public abstract boolean usingProxy(); 784 785 /** 786 * Returns a {@link SocketPermission} object representing the 787 * permission necessary to connect to the destination host and port. 788 * 789 * @exception IOException if an error occurs while computing 790 * the permission. 791 * 792 * @return a <code>SocketPermission</code> object representing the 793 * permission necessary to connect to the destination 794 * host and port. 795 */ 796 public Permission getPermission() throws IOException { 797 int port = url.getPort(); 798 port = port < 0 ? 80 : port; 799 String host = url.getHost() + ":" + port; 800 Permission permission = new SocketPermission(host, "connect"); 801 return permission; 802 } 803 804 /** 805 * Returns the error stream if the connection failed 806 * but the server sent useful data nonetheless. The 807 * typical example is when an HTTP server responds 808 * with a 404, which will cause a FileNotFoundException 809 * to be thrown in connect, but the server sent an HTML 810 * help page with suggestions as to what to do. 811 * 812 * <p>This method will not cause a connection to be initiated. If 813 * the connection was not connected, or if the server did not have 814 * an error while connecting or if the server had an error but 815 * no error data was sent, this method will return null. This is 816 * the default. 817 * 818 * @return an error stream if any, null if there have been no 819 * errors, the connection is not connected or the server sent no 820 * useful data. 821 */ 822 public InputStream getErrorStream() { 823 return null; 824 } 825 826 /** 827 * The response codes for HTTP, as of version 1.1. 828 */ 829 830 // REMIND: do we want all these?? 831 // Others not here that we do want?? 832 833 /* 2XX: generally "OK" */ 834 835 /** 836 * HTTP Status-Code 200: OK. 837 */ 838 public static final int HTTP_OK = 200; 839 840 /** 841 * HTTP Status-Code 201: Created. 842 */ 843 public static final int HTTP_CREATED = 201; 844 845 /** 846 * HTTP Status-Code 202: Accepted. 847 */ 848 public static final int HTTP_ACCEPTED = 202; 849 850 /** 851 * HTTP Status-Code 203: Non-Authoritative Information. 852 */ 853 public static final int HTTP_NOT_AUTHORITATIVE = 203; 854 855 /** 856 * HTTP Status-Code 204: No Content. 857 */ 858 public static final int HTTP_NO_CONTENT = 204; 859 860 /** 861 * HTTP Status-Code 205: Reset Content. 862 */ 863 public static final int HTTP_RESET = 205; 864 865 /** 866 * HTTP Status-Code 206: Partial Content. 867 */ 868 public static final int HTTP_PARTIAL = 206; 869 870 /* 3XX: relocation/redirect */ 871 872 /** 873 * HTTP Status-Code 300: Multiple Choices. 874 */ 875 public static final int HTTP_MULT_CHOICE = 300; 876 877 /** 878 * HTTP Status-Code 301: Moved Permanently. 879 */ 880 public static final int HTTP_MOVED_PERM = 301; 881 882 /** 883 * HTTP Status-Code 302: Temporary Redirect. 884 */ 885 public static final int HTTP_MOVED_TEMP = 302; 886 887 /** 888 * HTTP Status-Code 303: See Other. 889 */ 890 public static final int HTTP_SEE_OTHER = 303; 891 892 /** 893 * HTTP Status-Code 304: Not Modified. 894 */ 895 public static final int HTTP_NOT_MODIFIED = 304; 896 897 /** 898 * HTTP Status-Code 305: Use Proxy. 899 */ 900 public static final int HTTP_USE_PROXY = 305; 901 902 /* 4XX: client error */ 903 904 /** 905 * HTTP Status-Code 400: Bad Request. 906 */ 907 public static final int HTTP_BAD_REQUEST = 400; 908 909 /** 910 * HTTP Status-Code 401: Unauthorized. 911 */ 912 public static final int HTTP_UNAUTHORIZED = 401; 913 914 /** 915 * HTTP Status-Code 402: Payment Required. 916 */ 917 public static final int HTTP_PAYMENT_REQUIRED = 402; 918 919 /** 920 * HTTP Status-Code 403: Forbidden. 921 */ 922 public static final int HTTP_FORBIDDEN = 403; 923 924 /** 925 * HTTP Status-Code 404: Not Found. 926 */ 927 public static final int HTTP_NOT_FOUND = 404; 928 929 /** 930 * HTTP Status-Code 405: Method Not Allowed. 931 */ 932 public static final int HTTP_BAD_METHOD = 405; 933 934 /** 935 * HTTP Status-Code 406: Not Acceptable. 936 */ 937 public static final int HTTP_NOT_ACCEPTABLE = 406; 938 939 /** 940 * HTTP Status-Code 407: Proxy Authentication Required. 941 */ 942 public static final int HTTP_PROXY_AUTH = 407; 943 944 /** 945 * HTTP Status-Code 408: Request Time-Out. 946 */ 947 public static final int HTTP_CLIENT_TIMEOUT = 408; 948 949 /** 950 * HTTP Status-Code 409: Conflict. 951 */ 952 public static final int HTTP_CONFLICT = 409; 953 954 /** 955 * HTTP Status-Code 410: Gone. 956 */ 957 public static final int HTTP_GONE = 410; 958 959 /** 960 * HTTP Status-Code 411: Length Required. 961 */ 962 public static final int HTTP_LENGTH_REQUIRED = 411; 963 964 /** 965 * HTTP Status-Code 412: Precondition Failed. 966 */ 967 public static final int HTTP_PRECON_FAILED = 412; 968 969 /** 970 * HTTP Status-Code 413: Request Entity Too Large. 971 */ 972 public static final int HTTP_ENTITY_TOO_LARGE = 413; 973 974 /** 975 * HTTP Status-Code 414: Request-URI Too Large. 976 */ 977 public static final int HTTP_REQ_TOO_LONG = 414; 978 979 /** 980 * HTTP Status-Code 415: Unsupported Media Type. 981 */ 982 public static final int HTTP_UNSUPPORTED_TYPE = 415; 983 984 /* 5XX: server error */ 985 986 /** 987 * HTTP Status-Code 500: Internal Server Error. 988 * @deprecated it is misplaced and shouldn't have existed. 989 */ 990 @Deprecated 991 public static final int HTTP_SERVER_ERROR = 500; 992 993 /** 994 * HTTP Status-Code 500: Internal Server Error. 995 */ 996 public static final int HTTP_INTERNAL_ERROR = 500; 997 998 /** 999 * HTTP Status-Code 501: Not Implemented. 1000 */ 1001 public static final int HTTP_NOT_IMPLEMENTED = 501; 1002 1003 /** 1004 * HTTP Status-Code 502: Bad Gateway. 1005 */ 1006 public static final int HTTP_BAD_GATEWAY = 502; 1007 1008 /** 1009 * HTTP Status-Code 503: Service Unavailable. 1010 */ 1011 public static final int HTTP_UNAVAILABLE = 503; 1012 1013 /** 1014 * HTTP Status-Code 504: Gateway Timeout. 1015 */ 1016 public static final int HTTP_GATEWAY_TIMEOUT = 504; 1017 1018 /** 1019 * HTTP Status-Code 505: HTTP Version Not Supported. 1020 */ 1021 public static final int HTTP_VERSION = 505; 1022 1023 } 1024