/*

 * Copyright (c) 1996, 2019, Oracle and/or its affiliates. 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.  Oracle designates this

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

 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.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>

 * <p>

 * <b>Security permissions</b>

 * <p>

 * If a security manager is installed, and if a method is called which results in an

 * attempt to open a connection, the caller must possess either:

 * <ul><li>a "connect" {@link SocketPermission} to the host/port combination of the

 * destination URL or</li>

 * <li>a {@link URLPermission} that permits this request.</li>

 * </ul><p>

 * If automatic redirection is enabled, and this request is redirected to another

 * destination, then the caller must also have permission to connect to the

 * redirected host/URL.

 *

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

 * @since 1.1

 */

public abstract 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} 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} 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;

    /**

     * Supplies an {@link java.net.Authenticator Authenticator} to be used

     * when authentication is requested through the HTTP protocol for

     * this {@code HttpURLConnection}.

     * If no authenticator is supplied, the

     * {@linkplain Authenticator#setDefault(java.net.Authenticator) default

     * authenticator} will be used.

     *

     * @implSpec The default behavior of this method is to unconditionally

     *           throw {@link UnsupportedOperationException}. Concrete

     *           implementations of {@code HttpURLConnection}

     *           which support supplying an {@code Authenticator} for a

     *           specific {@code HttpURLConnection} instance should

     *           override this method to implement a different behavior.

     *

     * @implNote Depending on authentication schemes, an implementation

     *           may or may not need to use the provided authenticator

     *           to obtain a password. For instance, an implementation that

     *           relies on third-party security libraries may still invoke the

     *           default authenticator if these libraries are configured

     *           to do so.

     *           Likewise, an implementation that supports transparent

     *           NTLM authentication may let the system attempt

     *           to connect using the system user credentials first,

     *           before invoking the provided authenticator.

     *           <br>

     *           However, if an authenticator is specifically provided,

     *           then the underlying connection may only be reused for

     *           {@code HttpURLConnection} instances which share the same

     *           {@code Authenticator} instance, and authentication information,

     *           if cached, may only be reused for an {@code HttpURLConnection}

     *           sharing that same {@code Authenticator}.

     *

     * @param auth The {@code Authenticator} that should be used by this

     *           {@code HttpURLConnection}.

     *

     * @throws  UnsupportedOperationException if setting an Authenticator is

     *          not supported by the underlying implementation.

     * @throws  IllegalStateException if URLConnection is already connected.

     * @throws  NullPointerException if the supplied {@code auth} is {@code null}.

     * @since 9

     */

    public void setAuthenticator(Authenticator auth) {

        throw new UnsupportedOperationException("Supplying an authenticator"

                    + " is not supported by " + this.getClass());

    }

    /**

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

     * Some implementations may treat the {@code 0}<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)} returns null.

     *

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

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

     *          or {@code null} 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}<sup>th</sup> header field.

     * Some implementations may treat the {@code 0}<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 {@code n>=0}.

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

     *          or {@code null} if the value does not exist.

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

     */

    public String getHeaderField(int n) {

        return null;

    }

    /**

     * An {@code int} 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}, the protocol will automatically follow redirects.

     * If {@code false}, the protocol will not automatically follow

     * redirects.

     * <p>

     * This field is set by the {@code setInstanceFollowRedirects}

     * method. Its value is returned by the {@code getInstanceFollowRedirects}

     * 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} method

     * to ensure the operation is allowed.

     * This could result in a SecurityException.

     *

     * @param set a {@code boolean} indicating whether or not

     * to follow HTTP redirects.

     * @throws     SecurityException  if a security manager exists and its

     *             {@code checkSetFactory} 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} indicating

     * whether or not HTTP redirects (3xx) should

     * be automatically followed.

     *

     * @return {@code true} if HTTP redirects should

     * be automatically followed, {@code false} 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}

     * instance.

     * <p>

     * The default value comes from followRedirects, which defaults to

     * true.

     *

     * @param followRedirects a {@code boolean} 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}'s

     * {@code instanceFollowRedirects} field.

     *

     * @return  the value of this {@code HttpURLConnection}'s

     *          {@code instanceFollowRedirects} 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

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

     *              the requested method isn't valid for HTTP.

     * @throws    SecurityException if a security manager is set and the

     *              method is "TRACE", but the "allowHttpTrace"

     *              NetPermission is not granted.

     * @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)) {

                if (method.equals("TRACE")) {

                    SecurityManager s = System.getSecurityManager();

                    if (s != null) {

                        s.checkPermission(new NetPermission("allowHttpTrace"));

                    }

                }

                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 {