/*

 * Copyright 1996-2008 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.net;

import java.io.InputStream;

import java.io.IOException;

import java.security.Permission;

import java.util.Date;

/**

 * A URLConnection with support for HTTP-specific features. See

 * <A HREF="http://www.w3.org/pub/WWW/Protocols/"> the spec </A> for

 * details.

 * <p>

 *

 * Each HttpURLConnection instance is used to make a single request

 * but the underlying network connection to the HTTP server may be

 * transparently shared by other instances. Calling the close() methods

 * on the InputStream or OutputStream of an HttpURLConnection

 * after a request may free network resources associated with this

 * instance but has no effect on any shared persistent connection.

 * Calling the disconnect() method may close the underlying socket

 * if a persistent connection is otherwise idle at that time.

 *

 * <P>The HTTP protocol handler has a few settings that can be accessed through

 * System Properties. This covers

 * <a href="doc-files/net-properties.html#Proxies">Proxy settings</a> as well as

 * <a href="doc-files/net-properties.html#MiscHTTP"> various other settings</a>.

 * </P>

 *

 * @see     java.net.HttpURLConnection#disconnect()

 * @since JDK1.1

 */

abstract public class HttpURLConnection extends URLConnection {

    /* instance variables */

    /**

     * The HTTP method (GET,POST,PUT,etc.).

     */

    protected String method = "GET";

    /**

     * The chunk-length when using chunked encoding streaming mode for output.

     * A value of <code>-1</code> means chunked encoding is disabled for output.

     * @since 1.5

     */

    protected int chunkLength = -1;

    /**

     * The fixed content-length when using fixed-length streaming mode.

     * A value of <code>-1</code> means fixed-length streaming mode is disabled

     * for output.

     *

     * <P> <B>NOTE:</B> {@link #fixedContentLengthLong} is recommended instead

     * of this field, as it allows larger content lengths to be set.

     *

     * @since 1.5

     */

    protected int fixedContentLength = -1;

    /**

     * The fixed content-length when using fixed-length streaming mode.

     * A value of {@code -1} means fixed-length streaming mode is disabled

     * for output.

     *

     * @since 1.7

     */

    protected long fixedContentLengthLong = -1;

    /**

     * Returns the key for the <code>n</code><sup>th</sup> header field.

     * Some implementations may treat the <code>0</code><sup>th</sup>

     * header field as special, i.e. as the status line returned by the HTTP

     * server. In this case, {@link #getHeaderField(int) getHeaderField(0)} returns the status

     * line, but <code>getHeaderFieldKey(0)</code> returns null.

     *

     * @param   n   an index, where n >=0.

     * @return  the key for the <code>n</code><sup>th</sup> header field,

     *          or <code>null</code> if the key does not exist.

     */

    public String getHeaderFieldKey (int n) {

        return null;

    }

    /**

     * This method is used to enable streaming of a HTTP request body

     * without internal buffering, when the content length is known in

     * advance.

     * <p>

     * An exception will be thrown if the application

     * attempts to write more data than the indicated

     * content-length, or if the application closes the OutputStream

     * before writing the indicated amount.

     * <p>

     * When output streaming is enabled, authentication

     * and redirection cannot be handled automatically.

     * A HttpRetryException will be thrown when reading

     * the response if authentication or redirection are required.

     * This exception can be queried for the details of the error.

     * <p>

     * This method must be called before the URLConnection is connected.

     * <p>

     * <B>NOTE:</B> {@link #setFixedLengthStreamingMode(long)} is recommended

     * instead of this method as it allows larger content lengths to be set.

     *

     * @param   contentLength The number of bytes which will be written

     *          to the OutputStream.

     *

     * @throws  IllegalStateException if URLConnection is already connected

     *          or if a different streaming mode is already enabled.

     *

     * @throws  IllegalArgumentException if a content length less than

     *          zero is specified.

     *

     * @see     #setChunkedStreamingMode(int)

     * @since 1.5

     */

    public void setFixedLengthStreamingMode (int contentLength) {

        if (connected) {

            throw new IllegalStateException ("Already connected");

        }

        if (chunkLength != -1) {

            throw new IllegalStateException ("Chunked encoding streaming mode set");

        }

        if (contentLength < 0) {

            throw new IllegalArgumentException ("invalid content length");

        }

        fixedContentLength = contentLength;

    }

    /**

     * This method is used to enable streaming of a HTTP request body

     * without internal buffering, when the content length is known in

     * advance.

     *

     * <P> An exception will be thrown if the application attempts to write

     * more data than the indicated content-length, or if the application

     * closes the OutputStream before writing the indicated amount.

     *

     * <P> When output streaming is enabled, authentication and redirection

     * cannot be handled automatically. A {@linkplain HttpRetryException} will

     * be thrown when reading the response if authentication or redirection

     * are required. This exception can be queried for the details of the

     * error.

     *

     * <P> This method must be called before the URLConnection is connected.

     *

     * <P> The content length set by invoking this method takes precedence

     * over any value set by {@link #setFixedLengthStreamingMode(int)}.

     *

     * @param  contentLength

     *         The number of bytes which will be written to the OutputStream.

     *

     * @throws  IllegalStateException

     *          if URLConnection is already connected or if a different

     *          streaming mode is already enabled.

     *

     * @throws  IllegalArgumentException

     *          if a content length less than zero is specified.

     *

     * @since 1.7

     */

    public void setFixedLengthStreamingMode(long contentLength) {

        if (connected) {

            throw new IllegalStateException("Already connected");

        }

        if (chunkLength != -1) {

            throw new IllegalStateException(

                "Chunked encoding streaming mode set");

        }

        if (contentLength < 0) {

            throw new IllegalArgumentException("invalid content length");

        }

        fixedContentLengthLong = contentLength;

    }

    /* Default chunk size (including chunk header) if not specified;

     * we want to keep this in sync with the one defined in

     * sun.net.www.http.ChunkedOutputStream

     */

    private static final int DEFAULT_CHUNK_SIZE = 4096;

    /**

     * This method is used to enable streaming of a HTTP request body

     * without internal buffering, when the content length is <b>not</b>

     * known in advance. In this mode, chunked transfer encoding

     * is used to send the request body. Note, not all HTTP servers

     * support this mode.

     * <p>

     * When output streaming is enabled, authentication

     * and redirection cannot be handled automatically.

     * A HttpRetryException will be thrown when reading

     * the response if authentication or redirection are required.

     * This exception can be queried for the details of the error.

     * <p>

     * This method must be called before the URLConnection is connected.

     *

     * @param   chunklen The number of bytes to write in each chunk.

     *          If chunklen is less than or equal to zero, a default

     *          value will be used.

     *

     * @throws  IllegalStateException if URLConnection is already connected

     *          or if a different streaming mode is already enabled.

     *

     * @see     #setFixedLengthStreamingMode(int)

     * @since 1.5

     */

    public void setChunkedStreamingMode (int chunklen) {

        if (connected) {

            throw new IllegalStateException ("Can't set streaming mode: already connected");

        }

        if (fixedContentLength != -1 || fixedContentLengthLong != -1) {

            throw new IllegalStateException ("Fixed length streaming mode set");

        }

        chunkLength = chunklen <=0? DEFAULT_CHUNK_SIZE : chunklen;

    }

    /**

     * Returns the value for the <code>n</code><sup>th</sup> header field.

     * Some implementations may treat the <code>0</code><sup>th</sup>

     * header field as special, i.e. as the status line returned by the HTTP

     * server.

     * <p>

     * This method can be used in conjunction with the

     * {@link #getHeaderFieldKey getHeaderFieldKey} method to iterate through all

     * the headers in the message.

     *

     * @param   n   an index, where n>=0.

     * @return  the value of the <code>n</code><sup>th</sup> header field,

     *          or <code>null</code> if the value does not exist.

     * @see     java.net.HttpURLConnection#getHeaderFieldKey(int)

     */

    public String getHeaderField(int n) {

        return null;

    }

    /**

     * An <code>int</code> representing the three digit HTTP Status-Code.

     * <ul>

     * <li> 1xx: Informational

     * <li> 2xx: Success

     * <li> 3xx: Redirection

     * <li> 4xx: Client Error

     * <li> 5xx: Server Error

     * </ul>

     */

    protected int responseCode = -1;

    /**

     * The HTTP response message.

     */

    protected String responseMessage = null;

    /* static variables */

    /* do we automatically follow redirects? The default is true. */

    private static boolean followRedirects = true;

    /**

     * If <code>true</code>, the protocol will automatically follow redirects.

     * If <code>false</code>, the protocol will not automatically follow

     * redirects.

     * <p>

     * This field is set by the <code>setInstanceFollowRedirects</code>

     * method. Its value is returned by the <code>getInstanceFollowRedirects</code>

     * method.

     * <p>

     * Its default value is based on the value of the static followRedirects

     * at HttpURLConnection construction time.

     *

     * @see     java.net.HttpURLConnection#setInstanceFollowRedirects(boolean)

     * @see     java.net.HttpURLConnection#getInstanceFollowRedirects()

     * @see     java.net.HttpURLConnection#setFollowRedirects(boolean)

     */

    protected boolean instanceFollowRedirects = followRedirects;

    /* valid HTTP methods */

    private static final String[] methods = {

        "GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE"

    };

    /**

     * Constructor for the HttpURLConnection.

     * @param u the URL

     */

    protected HttpURLConnection (URL u) {

        super(u);

    }

    /**

     * Sets whether HTTP redirects  (requests with response code 3xx) should

     * be automatically followed by this class.  True by default.  Applets

     * cannot change this variable.

     * <p>

     * If there is a security manager, this method first calls

     * the security manager's <code>checkSetFactory</code> method

     * to ensure the operation is allowed.

     * This could result in a SecurityException.

     *

     * @param set a <code>boolean</code> indicating whether or not

     * to follow HTTP redirects.

     * @exception  SecurityException  if a security manager exists and its

     *             <code>checkSetFactory</code> method doesn't

     *             allow the operation.

     * @see        SecurityManager#checkSetFactory

     * @see #getFollowRedirects()

     */

    public static void setFollowRedirects(boolean set) {

        SecurityManager sec = System.getSecurityManager();

        if (sec != null) {

            // seems to be the best check here...

            sec.checkSetFactory();

        }

        followRedirects = set;

    }

    /**

     * Returns a <code>boolean</code> indicating

     * whether or not HTTP redirects (3xx) should

     * be automatically followed.

     *

     * @return <code>true</code> if HTTP redirects should

     * be automatically followed, <tt>false</tt> if not.

     * @see #setFollowRedirects(boolean)

     */

    public static boolean getFollowRedirects() {

        return followRedirects;

    }

    /**

     * Sets whether HTTP redirects (requests with response code 3xx) should

     * be automatically followed by this <code>HttpURLConnection</code>

     * instance.

     * <p>

     * The default value comes from followRedirects, which defaults to

     * true.

     *

     * @param followRedirects a <code>boolean</code> indicating

     * whether or not to follow HTTP redirects.

     *

     * @see    java.net.HttpURLConnection#instanceFollowRedirects

     * @see #getInstanceFollowRedirects

     * @since 1.3

     */

     public void setInstanceFollowRedirects(boolean followRedirects) {

        instanceFollowRedirects = followRedirects;

     }

     /**

     * Returns the value of this <code>HttpURLConnection</code>'s

     * <code>instanceFollowRedirects</code> field.

     *

     * @return  the value of this <code>HttpURLConnection</code>'s

     *          <code>instanceFollowRedirects</code> field.

     * @see     java.net.HttpURLConnection#instanceFollowRedirects

     * @see #setInstanceFollowRedirects(boolean)

     * @since 1.3

     */

     public boolean getInstanceFollowRedirects() {

         return instanceFollowRedirects;

     }

    /**

     * Set the method for the URL request, one of:

     * <UL>

     *  <LI>GET

     *  <LI>POST

     *  <LI>HEAD

     *  <LI>OPTIONS

     *  <LI>PUT

     *  <LI>DELETE

     *  <LI>TRACE

     * </UL> are legal, subject to protocol restrictions.  The default

     * method is GET.

     *

     * @param method the HTTP method

     * @exception ProtocolException if the method cannot be reset or if

     *              the requested method isn't valid for HTTP.

     * @see #getRequestMethod()

     */

    public void setRequestMethod(String method) throws ProtocolException {

        if (connected) {

            throw new ProtocolException("Can't reset method: already connected");

        }

        // This restriction will prevent people from using this class to

        // experiment w/ new HTTP methods using java.  But it should

        // be placed for security - the request String could be

        // arbitrarily long.

        for (int i = 0; i < methods.length; i++) {

            if (methods[i].equals(method)) {

                this.method = method;

                return;

            }

        }

        throw new ProtocolException("Invalid HTTP method: " + method);

    }

    /**

     * Get the request method.

     * @return the HTTP request method

     * @see #setRequestMethod(java.lang.String)

     */

    public String getRequestMethod() {

        return method;

    }

    /**

     * Gets the status code from an HTTP response message.

     * For example, in the case of the following status lines:

     * <PRE>

     * HTTP/1.0 200 OK

     * HTTP/1.0 401 Unauthorized

     * </PRE>

     * It will return 200 and 401 respectively.

     * Returns -1 if no code can be discerned

     * from the response (i.e., the response is not valid HTTP).

     * @throws IOException if an error occurred connecting to the server.

     * @return the HTTP Status-Code, or -1

     */

    public int getResponseCode() throws IOException {

        /*

         * We're got the response code already

         */

        if (responseCode != -1) {

            return responseCode;

        }

        /*

         * Ensure that we have connected to the server. Record

         * exception as we need to re-throw it if there isn't

         * a status line.

         */

        Exception exc = null;

        try {

            getInputStream();

        } catch (Exception e) {

            exc = e;

        }

        /*

         * If we can't a status-line then re-throw any exception

         * that getInputStream threw.

         */

        String statusLine = getHeaderField(0);

        if (statusLine == null) {

            if (exc != null) {

                if (exc instanceof RuntimeException)

                    throw (RuntimeException)exc;

                else

                    throw (IOException)exc;

            }

            return -1;

        }

        /*

         * Examine the status-line - should be formatted as per

         * section 6.1 of RFC 2616 :-

         *

         * Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase

         *

         * If status line can't be parsed return -1.

         */

        if (statusLine.startsWith("HTTP/1.")) {

            int codePos = statusLine.indexOf(' ');

            if (codePos > 0) {

                int phrasePos = statusLine.indexOf(' ', codePos+1);

                if (phrasePos > 0 && phrasePos < statusLine.length()) {

                    responseMessage = statusLine.substring(phrasePos+1);

                }

                // deviation from RFC 2616 - don't reject status line

                // if SP Reason-Phrase is not included.

                if (phrasePos < 0)

                    phrasePos = statusLine.length();

                try {

                    responseCode = Integer.parseInt

                            (statusLine.substring(codePos+1, phrasePos));

                    return responseCode;

                } catch (NumberFormatException e) { }

            }

        }

        return -1;

    }

    /**

     * Gets the HTTP response message, if any, returned along with the

     * response code from a server.  From responses like:

     * <PRE>

     * HTTP/1.0 200 OK

     * HTTP/1.0 404 Not Found

     * </PRE>

     * Extracts the Strings "OK" and "Not Found" respectively.

     * Returns null if none could be discerned from the responses

     * (the result was not valid HTTP).

     * @throws IOException if an error occurred connecting to the server.

     * @return the HTTP response message, or <code>null</code>

     */