/*

 * Copyright 1995-2007 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.IOException;

import java.io.InputStream;

import java.io.OutputStream;

import java.util.Hashtable;

import java.util.StringTokenizer;

import sun.security.util.SecurityConstants;

/**

 * Class <code>URL</code> 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:

 * <blockquote>

 *     <a href="http://www.socs.uts.edu.au/MosaicDocs-old/url-primer.html">

 *    <i>http://www.socs.uts.edu.au/MosaicDocs-old/url-primer.html</i></a>

 * </blockquote>

 * <p>

 * In general, a URL can be broken into several parts. The previous

 * example of a URL indicates that the protocol to use is

 * <code>http</code> (HyperText Transfer Protocol) and that the

 * information resides on a host machine named

 * <code>www.socs.uts.edu.au</code>. The information on that host

 * machine is named <code>/MosaicDocs-old/url-primer.html</code>. 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</code> is <code>80</code>. An alternative port could be

 * specified as:

 * <blockquote><pre>

 *     http://www.socs.uts.edu.au:80/MosaicDocs-old/url-primer.html

 * </pre></blockquote>

 * <p>

 * The syntax of <code>URL</code> 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</code> 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 JDK1.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</code> is

     * defined as <code>path[?query]</code>

     * @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</code> object from the specified

     * <code>protocol</code>, <code>host</code>, <code>port</code>

     * number, and <code>file</code>.<p>

     *

     * <code>host</code> 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 (<tt>'['</tt> and <tt>']'</tt>), 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</code> number of <code>-1</code>

     * 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</code>, is created for that protocol:

     * <ol>

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

     *     <code>URLStreamHandlerFactory</code> as the stream handler factory,

     *     then the <code>createURLStreamHandler</code> method of that instance

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

     *     stream protocol handler.

     * <li>If no <code>URLStreamHandlerFactory</code> has yet been set up,

     *     or if the factory's <code>createURLStreamHandler</code> method

     *     returns <code>null</code>, then the constructor finds the

     *     value of the system property:

     *     <blockquote><pre>

     *         java.protocol.handler.pkgs

     *     </pre></blockquote>

     *     If the value of that system property is not <code>null</code>,

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

     *     slash character '<code>|</code>'. The constructor tries to load

     *     the class named:

     *     <blockquote><pre>

     *         &lt;<i>package</i>&gt;.&lt;<i>protocol</i>&gt;.Handler

     *     </pre></blockquote>

     *     where &lt;<i>package</i>&gt; is replaced by the name of the package

     *     and &lt;<i>protocol</i>&gt; 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</code>, 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 from a system default package.

     *     <blockquote><pre>

     *         &lt;<i>system default package</i>&gt;.&lt;<i>protocol</i>&gt;.Handler

     *     </pre></blockquote>

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

     *     subclass of <code>URLStreamHandler</code>, then a

     *     <code>MalformedURLException</code> is thrown.

     * </ol>

     *

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

     * to exist on the search path :-

     * <blockquote><pre>

     *     http, https, ftp, file, and jar

     * </pre></blockquote>

     * Protocol handlers for additional protocols may also be

     * available.

     *

     * <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</code>

     * name, <code>host</code> name, and <code>file</code> 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>,

     * <code>host</code>, <code>-1</code>, and <code>file</code>.

     *

     * 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</code> object from the specified

     * <code>protocol</code>, <code>host</code>, <code>port</code>

     * number, <code>file</code>, and <code>handler</code>. Specifying

     * a <code>port</code> number of <code>-1</code> indicates that

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

     * a <code>handler</code> of <code>null</code> 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</code>

     * method is called with a

     * <code>NetPermission("specifyStreamHandler")</code> 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</code> 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</code> object from the <code>String</code>

     * representation.

     * <p>

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

     * constructor with a <code>null</code> first argument.

     *

     * @param      spec   the <code>String</code> to parse as a URL.

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

     *               unknown protocol is found, or <tt>spec</tt> is <tt>null</tt>.

     * @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 occurences 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</code> to parse as a URL.

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

     *               unknown protocol is found, or <tt>spec</tt> is <tt>null</tt>.

     * @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</code> to parse as a URL.

     * @param      handler   the stream handler for the URL.

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

     *               unknown protocol is found, or <tt>spec</tt> is <tt>null</tt>.

     * @exception  SecurityException

     *        if a security manager exists and its

     *        <code>checkPermission</code> method doesn't allow

     *        specifying a stream handler.

     * @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, URLStreamHandler handler)

        throws MalformedURLException

    {

        String original = spec;

        int i, limit, c;

        int start = 0;

        String newProtocol = null;

        boolean aRef=false;

        boolean isRelative = false;

        // Check for permission to specify a handler

        if (handler != null) {

            SecurityManager sm = System.getSecurityManager();

            if (sm != null) {

                checkSpecifyHandler(sm);

            }

        }

        try {

            limit = spec.length();

            while ((limit > 0) && (spec.charAt(limit - 1) <= ' ')) {

                limit--;        //eliminate trailing whitespace

            }

            while ((start < limit) && (spec.charAt(start) <= ' ')) {

                start++;        // eliminate leading whitespace

            }