Home | History | Annotate | Download | only in net
      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