/*

 * Copyright (c) 1995, 2013, 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.IOException;

import java.io.InputStream;

import java.net.spi.URLStreamHandlerProvider;

import java.security.AccessController;

import java.security.PrivilegedAction;

import java.util.Hashtable;

import java.util.Iterator;

import java.util.NoSuchElementException;

import java.util.ServiceConfigurationError;

import java.util.ServiceLoader;

import sun.security.util.SecurityConstants;

/**

 * Class {@code URL} represents a Uniform Resource

 * Locator, a pointer to a "resource" on the World

 * Wide Web. A resource can be something as simple as a file or a

 * directory, or it can be a reference to a more complicated object,

 * such as a query to a database or to a search engine. More

 * information on the types of URLs and their formats can be found at:

 * <a href=

 * "http://web.archive.org/web/20051219043731/http://archive.ncsa.uiuc.edu/SDG/Software/Mosaic/Demo/url-primer.html">

 * <i>Types of URL</i></a>

 * <p>

 * In general, a URL can be broken into several parts. Consider the

 * following example:

 * <blockquote><pre>

 *     http://www.example.com/docs/resource1.html

 * </pre></blockquote>

 * <p>

 * The URL above indicates that the protocol to use is

 * {@code http} (HyperText Transfer Protocol) and that the

 * information resides on a host machine named

 * {@code www.example.com}. The information on that host

 * machine is named {@code /docs/resource1.html}. The exact

 * meaning of this name on the host machine is both protocol

 * dependent and host dependent. The information normally resides in

 * a file, but it could be generated on the fly. This component of

 * the URL is called the <i>path</i> component.

 * <p>

 * A URL can optionally specify a "port", which is the

 * port number to which the TCP connection is made on the remote host

 * machine. If the port is not specified, the default port for

 * the protocol is used instead. For example, the default port for

 * {@code http} is {@code 80}. An alternative port could be

 * specified as:

 * <blockquote><pre>

 *     http://www.example.com:1080/docs/resource1.html

 * </pre></blockquote>

 * <p>

 * The syntax of {@code URL} is defined by  <a

 * href="http://www.ietf.org/rfc/rfc2396.txt"><i>RFC&nbsp;2396: Uniform

 * Resource Identifiers (URI): Generic Syntax</i></a>, amended by <a

 * href="http://www.ietf.org/rfc/rfc2732.txt"><i>RFC&nbsp;2732: Format for

 * Literal IPv6 Addresses in URLs</i></a>. The Literal IPv6 address format

 * also supports scope_ids. The syntax and usage of scope_ids is described

 * <a href="Inet6Address.html#scoped">here</a>.

 * <p>

 * A URL may have appended to it a "fragment", also known

 * as a "ref" or a "reference". The fragment is indicated by the sharp

 * sign character "#" followed by more characters. For example,

 * <blockquote><pre>

 *     http://java.sun.com/index.html#chapter1

 * </pre></blockquote>

 * <p>

 * This fragment is not technically part of the URL. Rather, it

 * indicates that after the specified resource is retrieved, the

 * application is specifically interested in that part of the

 * document that has the tag {@code chapter1} attached to it. The

 * meaning of a tag is resource specific.

 * <p>

 * An application can also specify a "relative URL",

 * which contains only enough information to reach the resource

 * relative to another URL. Relative URLs are frequently used within

 * HTML pages. For example, if the contents of the URL:

 * <blockquote><pre>

 *     http://java.sun.com/index.html

 * </pre></blockquote>

 * contained within it the relative URL:

 * <blockquote><pre>

 *     FAQ.html

 * </pre></blockquote>

 * it would be a shorthand for:

 * <blockquote><pre>

 *     http://java.sun.com/FAQ.html

 * </pre></blockquote>

 * <p>

 * The relative URL need not specify all the components of a URL. If

 * the protocol, host name, or port number is missing, the value is

 * inherited from the fully specified URL. The file component must be

 * specified. The optional fragment is not inherited.

 * <p>

 * The URL class does not itself encode or decode any URL components

 * according to the escaping mechanism defined in RFC2396. It is the

 * responsibility of the caller to encode any fields, which need to be

 * escaped prior to calling URL, and also to decode any escaped fields,

 * that are returned from URL. Furthermore, because URL has no knowledge

 * of URL escaping, it does not recognise equivalence between the encoded

 * or decoded form of the same URL. For example, the two URLs:<br>

 * <pre>    http://foo.com/hello world/ and http://foo.com/hello%20world</pre>

 * would be considered not equal to each other.

 * <p>

 * Note, the {@link java.net.URI} class does perform escaping of its

 * component fields in certain circumstances. The recommended way

 * to manage the encoding and decoding of URLs is to use {@link java.net.URI},

 * and to convert between these two classes using {@link #toURI()} and

 * {@link URI#toURL()}.

 * <p>

 * The {@link URLEncoder} and {@link URLDecoder} classes can also be

 * used, but only for HTML form encoding, which is not the same

 * as the encoding scheme defined in RFC2396.

 *

 * @author  James Gosling

 * @since 1.0

 */

public final class URL implements java.io.Serializable {

    static final long serialVersionUID = -7627629688361524110L;

    /**

     * The property which specifies the package prefix list to be scanned

     * for protocol handlers.  The value of this property (if any) should

     * be a vertical bar delimited list of package names to search through

     * for a protocol handler to load.  The policy of this class is that

     * all protocol handlers will be in a class called <protocolname>.Handler,

     * and each package in the list is examined in turn for a matching

     * handler.  If none are found (or the property is not specified), the

     * default package prefix, sun.net.www.protocol, is used.  The search

     * proceeds from the first package in the list to the last and stops

     * when a match is found.

     */

    private static final String protocolPathProp = "java.protocol.handler.pkgs";

    /**

     * The protocol to use (ftp, http, nntp, ... etc.) .

     * @serial

     */

    private String protocol;

    /**

     * The host name to connect to.

     * @serial

     */

    private String host;

    /**

     * The protocol port to connect to.

     * @serial

     */

    private int port = -1;

    /**

     * The specified file name on that host. {@code file} is

     * defined as {@code path[?query]}

     * @serial

     */

    private String file;

    /**

     * The query part of this URL.

     */

    private transient String query;

    /**

     * The authority part of this URL.

     * @serial

     */

    private String authority;

    /**

     * The path part of this URL.

     */

    private transient String path;

    /**

     * The userinfo part of this URL.

     */

    private transient String userInfo;

    /**

     * # reference.

     * @serial

     */

    private String ref;

    /**

     * The host's IP address, used in equals and hashCode.

     * Computed on demand. An uninitialized or unknown hostAddress is null.

     */

    transient InetAddress hostAddress;

    /**

     * The URLStreamHandler for this URL.

     */

    transient URLStreamHandler handler;

    /* Our hash code.

     * @serial

     */

    private int hashCode = -1;

    /**

     * Creates a {@code URL} object from the specified

     * {@code protocol}, {@code host}, {@code port}

     * number, and {@code file}.<p>

     *

     * {@code host} can be expressed as a host name or a literal

     * IP address. If IPv6 literal address is used, it should be

     * enclosed in square brackets ({@code '['} and {@code ']'}), as

     * specified by <a

     * href="http://www.ietf.org/rfc/rfc2732.txt">RFC&nbsp;2732</a>;

     * However, the literal IPv6 address format defined in <a

     * href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC&nbsp;2373: IP

     * Version 6 Addressing Architecture</i></a> is also accepted.<p>

     *

     * Specifying a {@code port} number of {@code -1}

     * indicates that the URL should use the default port for the

     * protocol.<p>

     *

     * If this is the first URL object being created with the specified

     * protocol, a <i>stream protocol handler</i> object, an instance of

     * class {@code URLStreamHandler}, is created for that protocol:

     * <ol>

     * <li>If the application has previously set up an instance of

     *     {@code URLStreamHandlerFactory} as the stream handler factory,

     *     then the {@code createURLStreamHandler} method of that instance

     *     is called with the protocol string as an argument to create the

     *     stream protocol handler.

     * <li>If no {@code URLStreamHandlerFactory} has yet been set up,

     *     or if the factory's {@code createURLStreamHandler} method

     *     returns {@code null}, then the {@linkplain java.util.ServiceLoader

     *     ServiceLoader} mechanism is used to locate {@linkplain

     *     java.net.spi.URLStreamHandlerProvider URLStreamHandlerProvider}

     *     implementations using the system class

     *     loader. The order that providers are located is implementation

     *     specific, and an implementation is free to cache the located

     *     providers. A {@linkplain java.util.ServiceConfigurationError

     *     ServiceConfigurationError}, {@code Error} or {@code RuntimeException}

     *     thrown from the {@code createURLStreamHandler}, if encountered, will

     *     be propagated to the calling thread. The {@code

     *     createURLStreamHandler} method of each provider, if instantiated, is

     *     invoked, with the protocol string, until a provider returns non-null,

     *     or all providers have been exhausted.

     * <li>If the previous step fails to find a protocol handler, the

     *     constructor reads the value of the system property:

     *     <blockquote>{@code

     *         java.protocol.handler.pkgs

     *     }</blockquote>

     *     If the value of that system property is not {@code null},

     *     it is interpreted as a list of packages separated by a vertical

     *     slash character '{@code |}'. The constructor tries to load

     *     the class named:

     *     <blockquote>{@code

     *         <package>.<protocol>.Handler

     *     }</blockquote>

     *     where {@code <package>} is replaced by the name of the package

     *     and {@code <protocol>} is replaced by the name of the protocol.

     *     If this class does not exist, or if the class exists but it is not

     *     a subclass of {@code URLStreamHandler}, then the next package

     *     in the list is tried.

     * <li>If the previous step fails to find a protocol handler, then the

     *     constructor tries to load a built-in protocol handler.

     *     If this class does not exist, or if the class exists but it is not a

     *     subclass of {@code URLStreamHandler}, then a

     *     {@code MalformedURLException} is thrown.

     * </ol>

     *

     * <p>Protocol handlers for the following protocols are guaranteed

     * to exist on the search path :-

     * <blockquote><pre>

     *     http, https, file, and jar

     * </pre></blockquote>

     * Protocol handlers for additional protocols may also be  available.

     * Some protocol handlers, for example those used for loading platform

     * classes or classes on the class path, may not be overridden. The details

     * of such restrictions, and when those restrictions apply (during

     * initialization of the runtime for example), are implementation specific

     * and therefore not specified

     *

     * <p>No validation of the inputs is performed by this constructor.

     *

     * @param      protocol   the name of the protocol to use.

     * @param      host       the name of the host.

     * @param      port       the port number on the host.

     * @param      file       the file on the host

     * @exception  MalformedURLException  if an unknown protocol is specified.

     * @see        java.lang.System#getProperty(java.lang.String)

     * @see        java.net.URL#setURLStreamHandlerFactory(

     *                  java.net.URLStreamHandlerFactory)

     * @see        java.net.URLStreamHandler

     * @see        java.net.URLStreamHandlerFactory#createURLStreamHandler(

     *                  java.lang.String)

     */

    public URL(String protocol, String host, int port, String file)

        throws MalformedURLException

    {

        this(protocol, host, port, file, null);

    }

    /**

     * Creates a URL from the specified {@code protocol}

     * name, {@code host} name, and {@code file} name. The

     * default port for the specified protocol is used.

     * <p>

     * This method is equivalent to calling the four-argument

     * constructor with the arguments being {@code protocol},

     * {@code host}, {@code -1}, and {@code file}.

     *

     * No validation of the inputs is performed by this constructor.

     *

     * @param      protocol   the name of the protocol to use.

     * @param      host       the name of the host.

     * @param      file       the file on the host.

     * @exception  MalformedURLException  if an unknown protocol is specified.

     * @see        java.net.URL#URL(java.lang.String, java.lang.String,

     *                  int, java.lang.String)

     */

    public URL(String protocol, String host, String file)

            throws MalformedURLException {

        this(protocol, host, -1, file);

    }

    /**

     * Creates a {@code URL} object from the specified

     * {@code protocol}, {@code host}, {@code port}

     * number, {@code file}, and {@code handler}. Specifying

     * a {@code port} number of {@code -1} indicates that

     * the URL should use the default port for the protocol. Specifying

     * a {@code handler} of {@code null} indicates that the URL

     * should use a default stream handler for the protocol, as outlined

     * for:

     *     java.net.URL#URL(java.lang.String, java.lang.String, int,

     *                      java.lang.String)

     *

     * <p>If the handler is not null and there is a security manager,

     * the security manager's {@code checkPermission}

     * method is called with a

     * {@code NetPermission("specifyStreamHandler")} permission.

     * This may result in a SecurityException.

     *

     * No validation of the inputs is performed by this constructor.

     *

     * @param      protocol   the name of the protocol to use.

     * @param      host       the name of the host.

     * @param      port       the port number on the host.

     * @param      file       the file on the host

     * @param      handler    the stream handler for the URL.

     * @exception  MalformedURLException  if an unknown protocol is specified.

     * @exception  SecurityException

     *        if a security manager exists and its

     *        {@code checkPermission} method doesn't allow

     *        specifying a stream handler explicitly.

     * @see        java.lang.System#getProperty(java.lang.String)

     * @see        java.net.URL#setURLStreamHandlerFactory(

     *                  java.net.URLStreamHandlerFactory)

     * @see        java.net.URLStreamHandler

     * @see        java.net.URLStreamHandlerFactory#createURLStreamHandler(

     *                  java.lang.String)

     * @see        SecurityManager#checkPermission

     * @see        java.net.NetPermission

     */

    public URL(String protocol, String host, int port, String file,

               URLStreamHandler handler) throws MalformedURLException {

        if (handler != null) {

            SecurityManager sm = System.getSecurityManager();

            if (sm != null) {

                // check for permission to specify a handler

                checkSpecifyHandler(sm);

            }

        }

        protocol = protocol.toLowerCase();

        this.protocol = protocol;

        if (host != null) {

            /**

             * if host is a literal IPv6 address,

             * we will make it conform to RFC 2732

             */

            if (host.indexOf(':') >= 0 && !host.startsWith("[")) {

                host = "["+host+"]";

            }

            this.host = host;

            if (port < -1) {

                throw new MalformedURLException("Invalid port number :" +

                                                    port);

            }

            this.port = port;

            authority = (port == -1) ? host : host + ":" + port;

        }

        Parts parts = new Parts(file);

        path = parts.getPath();

        query = parts.getQuery();

        if (query != null) {

            this.file = path + "?" + query;

        } else {

            this.file = path;

        }

        ref = parts.getRef();

        // Note: we don't do validation of the URL here. Too risky to change

        // right now, but worth considering for future reference. -br

        if (handler == null &&

            (handler = getURLStreamHandler(protocol)) == null) {

            throw new MalformedURLException("unknown protocol: " + protocol);

        }

        this.handler = handler;

    }

    /**

     * Creates a {@code URL} object from the {@code String}

     * representation.

     * <p>

     * This constructor is equivalent to a call to the two-argument

     * constructor with a {@code null} first argument.

     *

     * @param      spec   the {@code String} to parse as a URL.

     * @exception  MalformedURLException  if no protocol is specified, or an

     *               unknown protocol is found, or {@code spec} is {@code null}.

     * @see        java.net.URL#URL(java.net.URL, java.lang.String)

     */

    public URL(String spec) throws MalformedURLException {

        this(null, spec);

    }

    /**

     * Creates a URL by parsing the given spec within a specified context.

     *

     * The new URL is created from the given context URL and the spec

     * argument as described in

     * RFC2396 "Uniform Resource Identifiers : Generic * Syntax" :

     * <blockquote><pre>

     *          <scheme>://<authority><path>?<query>#<fragment>

     * </pre></blockquote>

     * The reference is parsed into the scheme, authority, path, query and

     * fragment parts. If the path component is empty and the scheme,

     * authority, and query components are undefined, then the new URL is a

     * reference to the current document. Otherwise, the fragment and query

     * parts present in the spec are used in the new URL.

     * <p>

     * If the scheme component is defined in the given spec and does not match

     * the scheme of the context, then the new URL is created as an absolute

     * URL based on the spec alone. Otherwise the scheme component is inherited

     * from the context URL.

     * <p>

     * If the authority component is present in the spec then the spec is

     * treated as absolute and the spec authority and path will replace the

     * context authority and path. If the authority component is absent in the

     * spec then the authority of the new URL will be inherited from the

     * context.

     * <p>

     * If the spec's path component begins with a slash character

     * "/" then the

     * path is treated as absolute and the spec path replaces the context path.

     * <p>

     * Otherwise, the path is treated as a relative path and is appended to the

     * context path, as described in RFC2396. Also, in this case,

     * the path is canonicalized through the removal of directory

     * changes made by occurrences of ".." and ".".

     * <p>

     * For a more detailed description of URL parsing, refer to RFC2396.

     *

     * @param      context   the context in which to parse the specification.

     * @param      spec      the {@code String} to parse as a URL.

     * @exception  MalformedURLException  if no protocol is specified, or an

     *               unknown protocol is found, or {@code spec} is {@code null}.

     * @see        java.net.URL#URL(java.lang.String, java.lang.String,

     *                  int, java.lang.String)

     * @see        java.net.URLStreamHandler

     * @see        java.net.URLStreamHandler#parseURL(java.net.URL,

     *                  java.lang.String, int, int)

     */

    public URL(URL context, String spec) throws MalformedURLException {

        this(context, spec, null);

    }

    /**

     * Creates a URL by parsing the given spec with the specified handler

     * within a specified context. If the handler is null, the parsing

     * occurs as with the two argument constructor.

     *

     * @param      context   the context in which to parse the specification.

     * @param      spec      the {@code String} to parse as a URL.

     * @param      handler   the stream handler for the URL.

     * @exception  MalformedURLException  if no protocol is specified, or an