content: /*
   * Copyright (C) 2014 The Android Open Source Project
   * Copyright (c) 2000, 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.InvalidObjectException;
  import java.io.ObjectInputStream;
  import java.io.ObjectOutputStream;
  import java.io.Serializable;
  import java.nio.ByteBuffer;
  import java.nio.CharBuffer;
  import java.nio.charset.CharsetDecoder;
  import java.nio.charset.CoderResult;
  import java.nio.charset.CodingErrorAction;
  import java.nio.charset.CharacterCodingException;
  import java.text.Normalizer;
  import sun.nio.cs.ThreadLocalCoders;
  
  import java.lang.Character;             // for javadoc
  import java.lang.NullPointerException;  // for javadoc
  
  
  // Android-changed: Reformat @see links.
  
  /**
   * Represents a Uniform Resource Identifier (URI) reference.
   *
   * <p> Aside from some minor deviations noted below, an instance of this
   * class represents a URI reference as 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>.
   * This class provides constructors for creating URI instances from
   * their components or by parsing their string forms, methods for accessing the
   * various components of an instance, and methods for normalizing, resolving,
   * and relativizing URI instances.  Instances of this class are immutable.
   *
   *
   * <h3> URI syntax and components </h3>
   *
   * At the highest level a URI reference (hereinafter simply "URI") in string
   * form has the syntax
   *
   * <blockquote>
   * [<i>scheme</i><b>{@code :}</b>]<i>scheme-specific-part</i>[<b>{@code #}</b><i>fragment</i>]
   * </blockquote>
   *
   * where square brackets [...] delineate optional components and the characters
   * <b>{@code :}</b> and <b>{@code #}</b> stand for themselves.
   *
   * <p> An <i>absolute</i> URI specifies a scheme; a URI that is not absolute is
   * said to be <i>relative</i>.  URIs are also classified according to whether
   * they are <i>opaque</i> or <i>hierarchical</i>.
   *
   * <p> An <i>opaque</i> URI is an absolute URI whose scheme-specific part does
   * not begin with a slash character ({@code '/'}).  Opaque URIs are not
   * subject to further parsing.  Some examples of opaque URIs are:
   *
   * <blockquote><table cellpadding=0 cellspacing=0 summary="layout">
   * <tr><td>{@code mailto:java-net@java.sun.com}<td></tr>
   * <tr><td>{@code news:comp.lang.java}<td></tr>
   * <tr><td>{@code urn:isbn:096139210x}</td></tr>
   * </table></blockquote>
   *
   * <p> A <i>hierarchical</i> URI is either an absolute URI whose
   * scheme-specific part begins with a slash character, or a relative URI, that
   * is, a URI that does not specify a scheme.  Some examples of hierarchical
   * URIs are:
   *
   * <blockquote>
   * {@code http://java.sun.com/j2se/1.3/}<br>
   * {@code docs/guide/collections/designfaq.html#28}<br>
   * {@code ../../../demo/jfc/SwingSet2/src/SwingSet2.java}<br>
   * {@code file:///~/calendar}
   * </blockquote>
   *
   * <p> A hierarchical URI is subject to further parsing according to the syntax
   *
   * <blockquote>
   * [<i>scheme</i><b>{@code :}</b>][<b>{@code //}</b><i>authority</i>][<i>path</i>][<b>{@code ?}</b><i>query</i>][<b>{@code #}</b><i>fragment</i>]
   * </blockquote>
   *
   * where the characters <b>{@code :}</b>, <b>{@code /}</b>,
   * <b>{@code ?}</b>, and <b>{@code #}</b> stand for themselves.  The
   * scheme-specific part of a hierarchical URI consists of the characters
   * between the scheme and fragment components.
   *
   * <p> The authority component of a hierarchical URI is, if specified, either
   * <i>server-based</i> or <i>registry-based</i>.  A server-based authority
   * parses according to the familiar syntax
   *
   * <blockquote>
   * [<i>user-info</i><b>{@code @}</b>]<i>host</i>[<b>{@code :}</b><i>port</i>]
   * </blockquote>
   *
   * where the characters <b>{@code @}</b> and <b>{@code :}</b> stand for
   * themselves.  Nearly all URI schemes currently in use are server-based.  An
   * authority component that does not parse in this way is considered to be
   * registry-based.
   *
   * <p> The path component of a hierarchical URI is itself said to be absolute
   * if it begins with a slash character ({@code '/'}); otherwise it is
   * relative.  The path of a hierarchical URI that is either absolute or
   * specifies an authority is always absolute.
   *
   * <p> All told, then, a URI instance has the following nine components:
   *
   * <blockquote><table summary="Describes the components of a URI:scheme,scheme-specific-part,authority,user-info,host,port,path,query,fragment">
   * <tr><th><i>Component</i></th><th><i>Type</i></th></tr>
   * <tr><td>scheme</td><td>{@code String}</td></tr>
   * <tr><td>scheme-specific-part&nbsp;&nbsp;&nbsp;&nbsp;</td><td>{@code String}</td></tr>
   * <tr><td>authority</td><td>{@code String}</td></tr>
   * <tr><td>user-info</td><td>{@code String}</td></tr>
   * <tr><td>host</td><td>{@code String}</td></tr>
   * <tr><td>port</td><td>{@code int}</td></tr>
   * <tr><td>path</td><td>{@code String}</td></tr>
   * <tr><td>query</td><td>{@code String}</td></tr>
   * <tr><td>fragment</td><td>{@code String}</td></tr>
   * </table></blockquote>
   *
   * In a given instance any particular component is either <i>undefined</i> or
   * <i>defined</i> with a distinct value.  Undefined string components are
   * represented by {@code null}, while undefined integer components are
   * represented by {@code -1}.  A string component may be defined to have the
   * empty string as its value; this is not equivalent to that component being
   * undefined.
   *
   * <p> Whether a particular component is or is not defined in an instance
   * depends upon the type of the URI being represented.  An absolute URI has a
   * scheme component.  An opaque URI has a scheme, a scheme-specific part, and
   * possibly a fragment, but has no other components.  A hierarchical URI always
   * has a path (though it may be empty) and a scheme-specific-part (which at
   * least contains the path), and may have any of the other components.  If the
   * authority component is present and is server-based then the host component
   * will be defined and the user-information and port components may be defined.
   *
   *
   * <h4> Operations on URI instances </h4>
   *
   * The key operations supported by this class are those of
   * <i>normalization</i>, <i>resolution</i>, and <i>relativization</i>.
   *
   * <p> <i>Normalization</i> is the process of removing unnecessary {@code "."}
   * and {@code ".."} segments from the path component of a hierarchical URI.
   * Each {@code "."} segment is simply removed.  A {@code ".."} segment is
   * removed only if it is preceded by a non-{@code ".."} segment.
   * Normalization has no effect upon opaque URIs.
   *
   * <p> <i>Resolution</i> is the process of resolving one URI against another,
   * <i>base</i> URI.  The resulting URI is constructed from components of both
   * URIs in the manner specified by RFC&nbsp;2396, taking components from the
   * base URI for those not specified in the original.  For hierarchical URIs,
   * the path of the original is resolved against the path of the base and then
   * normalized.  The result, for example, of resolving
   *
   * <blockquote>
   * {@code docs/guide/collections/designfaq.html#28}
   * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
   * &nbsp;&nbsp;&nbsp;&nbsp;(1)
   * </blockquote>
   *
   * against the base URI {@code http://java.sun.com/j2se/1.3/} is the result
   * URI
   *
   * <blockquote>
   * {@code http://java.sun.com/j2se/1.3/docs/guide/collections/designfaq.html#28}
   * </blockquote>
   *
   * Resolving the relative URI
   *
   * <blockquote>
   * {@code ../../../demo/jfc/SwingSet2/src/SwingSet2.java}&nbsp;&nbsp;&nbsp;&nbsp;(2)
   * </blockquote>
   *
   * against this result yields, in turn,
   *
   * <blockquote>
   * {@code http://java.sun.com/j2se/1.3/demo/jfc/SwingSet2/src/SwingSet2.java}
   * </blockquote>
   *
   * Resolution of both absolute and relative URIs, and of both absolute and
   * relative paths in the case of hierarchical URIs, is supported.  Resolving
   * the URI {@code file:///~calendar} against any other URI simply yields the
   * original URI, since it is absolute.  Resolving the relative URI (2) above
   * against the relative base URI (1) yields the normalized, but still relative,
   * URI
   *
   * <blockquote>
   * {@code demo/jfc/SwingSet2/src/SwingSet2.java}
   * </blockquote>
   *
   * <p> <i>Relativization</i>, finally, is the inverse of resolution: For any
   * two normalized URIs <i>u</i> and&nbsp;<i>v</i>,
   *
   * <blockquote>
   *   <i>u</i>{@code .relativize(}<i>u</i>{@code .resolve(}<i>v</i>{@code )).equals(}<i>v</i>{@code )}&nbsp;&nbsp;and<br>
   *   <i>u</i>{@code .resolve(}<i>u</i>{@code .relativize(}<i>v</i>{@code )).equals(}<i>v</i>{@code )}&nbsp;&nbsp;.<br>
   * </blockquote>
   *
   * This operation is often useful when constructing a document containing URIs
   * that must be made relative to the base URI of the document wherever
   * possible.  For example, relativizing the URI
   *
   * <blockquote>
   * {@code http://java.sun.com/j2se/1.3/docs/guide/index.html}
   * </blockquote>
   *
   * against the base URI
   *
   * <blockquote>
   * {@code http://java.sun.com/j2se/1.3}
   * </blockquote>
   *
   * yields the relative URI {@code docs/guide/index.html}.
   *
   *
   * <h4> Character categories </h4>
   *
   * RFC&nbsp;2396 specifies precisely which characters are permitted in the
   * various components of a URI reference.  The following categories, most of
   * which are taken from that specification, are used below to describe these
   * constraints:
   *
   * <blockquote><table cellspacing=2 summary="Describes categories alpha,digit,alphanum,unreserved,punct,reserved,escaped,and other">
   *   <tr><th valign=top><i>alpha</i></th>
   *       <td>The US-ASCII alphabetic characters,
   *        {@code 'A'}&nbsp;through&nbsp;{@code 'Z'}
   *        and {@code 'a'}&nbsp;through&nbsp;{@code 'z'}</td></tr>
   *   <tr><th valign=top><i>digit</i></th>
   *       <td>The US-ASCII decimal digit characters,
   *       {@code '0'}&nbsp;through&nbsp;{@code '9'}</td></tr>
   *   <tr><th valign=top><i>alphanum</i></th>
   *       <td>All <i>alpha</i> and <i>digit</i> characters</td></tr>
   *   <tr><th valign=top><i>unreserved</i>&nbsp;&nbsp;&nbsp;&nbsp;</th>
   *       <td>All <i>alphanum</i> characters together with those in the string
   *        {@code "_-!.~'()*"}</td></tr>
   *   <tr><th valign=top><i>punct</i></th>
   *       <td>The characters in the string {@code ",;:$&+="}</td></tr>
   *   <tr><th valign=top><i>reserved</i></th>
   *       <td>All <i>punct</i> characters together with those in the string
   *        {@code "?/[]@"}</td></tr>
   *   <tr><th valign=top><i>escaped</i></th>
   *       <td>Escaped octets, that is, triplets consisting of the percent
   *           character ({@code '%'}) followed by two hexadecimal digits
   *           ({@code '0'}-{@code '9'}, {@code 'A'}-{@code 'F'}, and
   *           {@code 'a'}-{@code 'f'})</td></tr>
   *   <tr><th valign=top><i>other</i></th>
   *       <td>The Unicode characters that are not in the US-ASCII character set,
   *           are not control characters (according to the {@link
   *           Character#isISOControl(char) Character.isISOControl}
   *           method), and are not space characters (according to the {@link
   *           Character#isSpaceChar(char) Character.isSpaceChar}
   *           method)&nbsp;&nbsp;<i>(<b>Deviation from RFC 2396</b>, which is
   *           limited to US-ASCII)</i></td></tr>
   * </table></blockquote>
   *
   * <p><a name="legal-chars"></a> The set of all legal URI characters consists of
   * the <i>unreserved</i>, <i>reserved</i>, <i>escaped</i>, and <i>other</i>
   * characters.
   *
   *
   * <h4> Escaped octets, quotation, encoding, and decoding </h4>
   *
   * RFC 2396 allows escaped octets to appear in the user-info, path, query, and
   * fragment components.  Escaping serves two purposes in URIs:
   *
   * <ul>
   *
   *   <li><p> To <i>encode</i> non-US-ASCII characters when a URI is required to
   *   conform strictly to RFC&nbsp;2396 by not containing any <i>other</i>
   *   characters.  </p></li>
   *
   *   <li><p> To <i>quote</i> characters that are otherwise illegal in a
   *   component.  The user-info, path, query, and fragment components differ
   *   slightly in terms of which characters are considered legal and illegal.
   *   </p></li>
   *
   * </ul>
   *
   * These purposes are served in this class by three related operations:
   *
   * <ul>
   *
   *   <li><p><a name="encode"></a> A character is <i>encoded</i> by replacing it
   *   with the sequence of escaped octets that represent that character in the
   *   UTF-8 character set.  The Euro currency symbol ({@code '\u005Cu20AC'}),
   *   for example, is encoded as {@code "%E2%82%AC"}.  <i>(<b>Deviation from
   *   RFC&nbsp;2396</b>, which does not specify any particular character
   *   set.)</i> </p></li>
   *
   *   <li><p><a name="quote"></a> An illegal character is <i>quoted</i> simply by
   *   encoding it.  The space character, for example, is quoted by replacing it
   *   with {@code "%20"}.  UTF-8 contains US-ASCII, hence for US-ASCII
   *   characters this transformation has exactly the effect required by
   *   RFC&nbsp;2396. </p></li>
   *
   *   <li><p><a name="decode"></a>
   *   A sequence of escaped octets is <i>decoded</i> by
   *   replacing it with the sequence of characters that it represents in the
   *   UTF-8 character set.  UTF-8 contains US-ASCII, hence decoding has the
   *   effect of de-quoting any quoted US-ASCII characters as well as that of
   *   decoding any encoded non-US-ASCII characters.  If a <a
   *   href="../nio/charset/CharsetDecoder.html#ce">decoding error</a> occurs
   *   when decoding the escaped octets then the erroneous octets are replaced by
   *   {@code '\u005CuFFFD'}, the Unicode replacement character.  </p></li>
   *
   * </ul>
   *
   * These operations are exposed in the constructors and methods of this class
   * as follows:
   *
   * <ul>
   *
   *   <li><p> The {@linkplain #URI(String) single-argument
   *   constructor} requires any illegal characters in its argument to be
   *   quoted and preserves any escaped octets and <i>other</i> characters that
   *   are present.  </p></li>
   *
   *   <li><p> The {@linkplain
   *   #URI(String, String, String,int, String, String, String)
   *   multi-argument constructors} quote illegal characters as
   *   required by the components in which they appear.  The percent character
   *   ({@code '%'}) is always quoted by these constructors.  Any <i>other</i>
   *   characters are preserved.  </p></li>
   *
   *   <li><p> The {@link #getRawUserInfo() getRawUserInfo}, {@link #getRawPath()
   *   getRawPath}, {@link #getRawQuery() getRawQuery}, {@link #getRawFragment()
   *   getRawFragment}, {@link #getRawAuthority() getRawAuthority}, and {@link
   *   #getRawSchemeSpecificPart() getRawSchemeSpecificPart} methods return the
   *   values of their corresponding components in raw form, without interpreting
   *   any escaped octets.  The strings returned by these methods may contain
   *   both escaped octets and <i>other</i> characters, and will not contain any
   *   illegal characters.  </p></li>
   *
   *   <li><p> The {@link #getUserInfo() getUserInfo}, {@link #getPath()
   *   getPath}, {@link #getQuery() getQuery}, {@link #getFragment()
   *   getFragment}, {@link #getAuthority() getAuthority}, and {@link
   *   #getSchemeSpecificPart() getSchemeSpecificPart} methods decode any escaped
   *   octets in their corresponding components.  The strings returned by these
   *   methods may contain both <i>other</i> characters and illegal characters,
   *   and will not contain any escaped octets.  </p></li>
   *
   *   <li><p> The {@link #toString() toString} method returns a URI string with
   *   all necessary quotation but which may contain <i>other</i> characters.
   *   </p></li>
   *
   *   <li><p> The {@link #toASCIIString() toASCIIString} method returns a fully
   *   quoted and encoded URI string that does not contain any <i>other</i>
   *   characters.  </p></li>
   *
   * </ul>
   *
   *
   * <h4> Identities </h4>
   *
   * For any URI <i>u</i>, it is always the case that
   *
   * <blockquote>
   * {@code new URI(}<i>u</i>{@code .toString()).equals(}<i>u</i>{@code )}&nbsp;.
   * </blockquote>
   *
   * For any URI <i>u</i> that does not contain redundant syntax such as two
   * slashes before an empty authority (as in {@code file:///tmp/}&nbsp;) or a
   * colon following a host name but no port (as in
   * {@code http://java.sun.com:}&nbsp;), and that does not encode characters
   * except those that must be quoted, the following identities also hold:
   * <pre>
   *     new URI(<i>u</i>.getScheme(),
   *             <i>u</i>.getSchemeSpecificPart(),
   *             <i>u</i>.getFragment())
   *     .equals(<i>u</i>)</pre>
   * in all cases,
   * <pre>
   *     new URI(<i>u</i>.getScheme(),
   *             <i>u</i>.getUserInfo(), <i>u</i>.getAuthority(),
   *             <i>u</i>.getPath(), <i>u</i>.getQuery(),
   *             <i>u</i>.getFragment())
   *     .equals(<i>u</i>)</pre>
   * if <i>u</i> is hierarchical, and
   * <pre>
   *     new URI(<i>u</i>.getScheme(),
   *             <i>u</i>.getUserInfo(), <i>u</i>.getHost(), <i>u</i>.getPort(),
   *             <i>u</i>.getPath(), <i>u</i>.getQuery(),
   *             <i>u</i>.getFragment())
   *     .equals(<i>u</i>)</pre>
   * if <i>u</i> is hierarchical and has either no authority or a server-based
   * authority.
   *
   *
   * <h4> URIs, URLs, and URNs </h4>
   *
   * A URI is a uniform resource <i>identifier</i> while a URL is a uniform
   * resource <i>locator</i>.  Hence every URL is a URI, abstractly speaking, but
   * not every URI is a URL.  This is because there is another subcategory of
   * URIs, uniform resource <i>names</i> (URNs), which name resources but do not
   * specify how to locate them.  The {@code mailto}, {@code news}, and
   * {@code isbn} URIs shown above are examples of URNs.
   *
   * <p> The conceptual distinction between URIs and URLs is reflected in the
   * differences between this class and the {@link URL} class.
   *
   * <p> An instance of this class represents a URI reference in the syntactic
   * sense defined by RFC&nbsp;2396.  A URI may be either absolute or relative.
   * A URI string is parsed according to the generic syntax without regard to the
   * scheme, if any, that it specifies.  No lookup of the host, if any, is
   * performed, and no scheme-dependent stream handler is constructed.  Equality,
   * hashing, and comparison are defined strictly in terms of the character
   * content of the instance.  In other words, a URI instance is little more than
   * a structured string that supports the syntactic, scheme-independent
   * operations of comparison, normalization, resolution, and relativization.
   *
   * <p> An instance of the {@link URL} class, by contrast, represents the
   * syntactic components of a URL together with some of the information required
   * to access the resource that it describes.  A URL must be absolute, that is,
   * it must always specify a scheme.  A URL string is parsed according to its
   * scheme.  A stream handler is always established for a URL, and in fact it is
   * impossible to create a URL instance for a scheme for which no handler is
   * available.  Equality and hashing depend upon both the scheme and the
   * Internet address of the host, if any; comparison is not defined.  In other
   * words, a URL is a structured string that supports the syntactic operation of
   * resolution as well as the network I/O operations of looking up the host and
   * opening a connection to the specified resource.
   *
   *
   * @author Mark Reinhold
   * @since 1.4
   *
   * @see <a href="http://www.ietf.org/rfc/rfc2279.txt">RFC&nbsp;2279: UTF-8, a transformation format of ISO 10646</a>
   * @see <a href="http://www.ietf.org/rfc/rfc2373.txt">RFC&nbsp;2373: IPv6 Addressing Architecture</a>
   * @see <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396: Uniform Resource Identifiers (URI): Generic Syntax</a>
   * @see <a href="http://www.ietf.org/rfc/rfc2732.txt">RFC&nbsp;2732: Format for Literal IPv6 Addresses in URLs</a>
   */
  
  public final class URI
      implements Comparable<URI>, Serializable
  {
  
      // Note: Comments containing the word "ASSERT" indicate places where a
      // throw of an InternalError should be replaced by an appropriate assertion
      // statement once asserts are enabled in the build.
  
      static final long serialVersionUID = -6052424284110960213L;
  
  
      // -- Properties and components of this instance --
  
      // Components of all URIs: [<scheme>:]<scheme-specific-part>[#<fragment>]
      private transient String scheme;            // null ==> relative URI
      private transient String fragment;
  
      // Hierarchical URI components: [//<authority>]<path>[?<query>]
      private transient String authority;         // Registry or server
  
      // Server-based authority: [<userInfo>@]<host>[:<port>]
      private transient String userInfo;
      private transient String host;              // null ==> registry-based
      private transient int port = -1;            // -1 ==> undefined
  
      // Remaining components of hierarchical URIs
      private transient String path;              // null ==> opaque
      private transient String query;
  
      // The remaining fields may be computed on demand
  
      private volatile transient String schemeSpecificPart;
      private volatile transient int hash;        // Zero ==> undefined
  
      private volatile transient String decodedUserInfo = null;
      private volatile transient String decodedAuthority = null;
      private volatile transient String decodedPath = null;
      private volatile transient String decodedQuery = null;
      private volatile transient String decodedFragment = null;
      private volatile transient String decodedSchemeSpecificPart = null;
  
      /**
       * The string form of this URI.
       *
       * @serial
       */
      private volatile String string;             // The only serializable field
  
  
  
      // -- Constructors and factories --
  
      private URI() { }                           // Used internally
  
      /**
       * Constructs a URI by parsing the given string.
       *
       * <p> This constructor parses the given string exactly as specified by the
       * grammar in <a
       * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
       * Appendix&nbsp;A, <b><i>except for the following deviations:</i></b> </p>
       *
       * <ul>
       *
       *   <li><p> An empty authority component is permitted as long as it is
       *   followed by a non-empty path, a query component, or a fragment
       *   component.  This allows the parsing of URIs such as
       *   {@code "file:///foo/bar"}, which seems to be the intent of
       *   RFC&nbsp;2396 although the grammar does not permit it.  If the
       *   authority component is empty then the user-information, host, and port
       *   components are undefined. </p></li>
       *
       *   <li><p> Empty relative paths are permitted; this seems to be the
       *   intent of RFC&nbsp;2396 although the grammar does not permit it.  The
       *   primary consequence of this deviation is that a standalone fragment
       *   such as {@code "#foo"} parses as a relative URI with an empty path
       *   and the given fragment, and can be usefully <a
       *   href="#resolve-frag">resolved</a> against a base URI.
       *
       *   <li><p> IPv4 addresses in host components are parsed rigorously, as
       *   specified by <a
       *   href="http://www.ietf.org/rfc/rfc2732.txt">RFC&nbsp;2732</a>: Each
       *   element of a dotted-quad address must contain no more than three
       *   decimal digits.  Each element is further constrained to have a value
       *   no greater than 255. </p></li>
       *
       *   <li> <p> Hostnames in host components that comprise only a single
       *   domain label are permitted to start with an <i>alphanum</i>
       *   character. This seems to be the intent of <a
       *   href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>
       *   section&nbsp;3.2.2 although the grammar does not permit it. The
       *   consequence of this deviation is that the authority component of a
       *   hierarchical URI such as {@code s://123}, will parse as a server-based
       *   authority. </p></li>
       *
       *   <li><p> IPv6 addresses are permitted for the host component.  An IPv6
       *   address must be enclosed in square brackets ({@code '['} and
       *   {@code ']'}) as specified by <a
       *   href="http://www.ietf.org/rfc/rfc2732.txt">RFC&nbsp;2732</a>.  The
       *   IPv6 address itself must parse according to <a
       *   href="http://www.ietf.org/rfc/rfc2373.txt">RFC&nbsp;2373</a>.  IPv6
       *   addresses are further constrained to describe no more than sixteen
       *   bytes of address information, a constraint implicit in RFC&nbsp;2373
       *   but not expressible in the grammar. </p></li>
       *
       *   <li><p> Characters in the <i>other</i> category are permitted wherever
       *   RFC&nbsp;2396 permits <i>escaped</i> octets, that is, in the
       *   user-information, path, query, and fragment components, as well as in
       *   the authority component if the authority is registry-based.  This
       *   allows URIs to contain Unicode characters beyond those in the US-ASCII
       *   character set. </p></li>
       *
       * </ul>
       *
       * @param  str   The string to be parsed into a URI
       *
       * @throws  NullPointerException
       *          If {@code str} is {@code null}
       *
       * @throws  URISyntaxException
       *          If the given string violates RFC&nbsp;2396, as augmented
       *          by the above deviations
       */
      public URI(String str) throws URISyntaxException {
          new Parser(str).parse(false);
      }
  
      /**
       * Constructs a hierarchical URI from the given components.
       *
       * <p> If a scheme is given then the path, if also given, must either be
       * empty or begin with a slash character ({@code '/'}).  Otherwise a
       * component of the new URI may be left undefined by passing {@code null}
       * for the corresponding parameter or, in the case of the {@code port}
       * parameter, by passing {@code -1}.
       *
       * <p> This constructor first builds a URI string from the given components
       * according to the rules specified in <a
       * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
       * section&nbsp;5.2, step&nbsp;7: </p>
       *
       * <ol>
       *
       *   <li><p> Initially, the result string is empty. </p></li>
       *
       *   <li><p> If a scheme is given then it is appended to the result,
       *   followed by a colon character ({@code ':'}).  </p></li>
       *
       *   <li><p> If user information, a host, or a port are given then the
       *   string {@code "//"} is appended.  </p></li>
       *
       *   <li><p> If user information is given then it is appended, followed by
       *   a commercial-at character ({@code '@'}).  Any character not in the
       *   <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, or <i>other</i>
       *   categories is <a href="#quote">quoted</a>.  </p></li>
       *
       *   <li><p> If a host is given then it is appended.  If the host is a
       *   literal IPv6 address but is not enclosed in square brackets
       *   ({@code '['} and {@code ']'}) then the square brackets are added.
       *   </p></li>
       *
       *   <li><p> If a port number is given then a colon character
       *   ({@code ':'}) is appended, followed by the port number in decimal.
       *   </p></li>
       *
       *   <li><p> If a path is given then it is appended.  Any character not in
       *   the <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, or <i>other</i>
       *   categories, and not equal to the slash character ({@code '/'}) or the
       *   commercial-at character ({@code '@'}), is quoted.  </p></li>
       *
       *   <li><p> If a query is given then a question-mark character
       *   ({@code '?'}) is appended, followed by the query.  Any character that
       *   is not a <a href="#legal-chars">legal URI character</a> is quoted.
       *   </p></li>
       *
       *   <li><p> Finally, if a fragment is given then a hash character
       *   ({@code '#'}) is appended, followed by the fragment.  Any character
       *   that is not a legal URI character is quoted.  </p></li>
       *
       * </ol>
       *
       * <p> The resulting URI string is then parsed as if by invoking the {@link
       * #URI(String)} constructor and then invoking the {@link
       * #parseServerAuthority()} method upon the result; this may cause a {@link
       * URISyntaxException} to be thrown.  </p>
       *
       * @param   scheme    Scheme name
       * @param   userInfo  User name and authorization information
       * @param   host      Host name
       * @param   port      Port number
       * @param   path      Path
       * @param   query     Query
       * @param   fragment  Fragment
       *
       * @throws URISyntaxException
       *         If both a scheme and a path are given but the path is relative,
       *         if the URI string constructed from the given components violates
       *         RFC&nbsp;2396, or if the authority component of the string is
       *         present but cannot be parsed as a server-based authority
       */
      public URI(String scheme,
                 String userInfo, String host, int port,
                 String path, String query, String fragment)
          throws URISyntaxException
      {
          String s = toString(scheme, null,
                              null, userInfo, host, port,
                              path, query, fragment);
          checkPath(s, scheme, path);
          new Parser(s).parse(true);
      }
  
      /**
       * Constructs a hierarchical URI from the given components.
       *
       * <p> If a scheme is given then the path, if also given, must either be
       * empty or begin with a slash character ({@code '/'}).  Otherwise a
       * component of the new URI may be left undefined by passing {@code null}
       * for the corresponding parameter.
       *
       * <p> This constructor first builds a URI string from the given components
       * according to the rules specified in <a
       * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
       * section&nbsp;5.2, step&nbsp;7: </p>
       *
       * <ol>
       *
       *   <li><p> Initially, the result string is empty.  </p></li>
       *
       *   <li><p> If a scheme is given then it is appended to the result,
       *   followed by a colon character ({@code ':'}).  </p></li>
       *
       *   <li><p> If an authority is given then the string {@code "//"} is
       *   appended, followed by the authority.  If the authority contains a
       *   literal IPv6 address then the address must be enclosed in square
       *   brackets ({@code '['} and {@code ']'}).  Any character not in the
       *   <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, or <i>other</i>
       *   categories, and not equal to the commercial-at character
       *   ({@code '@'}), is <a href="#quote">quoted</a>.  </p></li>
       *
       *   <li><p> If a path is given then it is appended.  Any character not in
       *   the <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, or <i>other</i>
       *   categories, and not equal to the slash character ({@code '/'}) or the
       *   commercial-at character ({@code '@'}), is quoted.  </p></li>
       *
       *   <li><p> If a query is given then a question-mark character
       *   ({@code '?'}) is appended, followed by the query.  Any character that
       *   is not a <a href="#legal-chars">legal URI character</a> is quoted.
       *   </p></li>
       *
       *   <li><p> Finally, if a fragment is given then a hash character
       *   ({@code '#'}) is appended, followed by the fragment.  Any character
       *   that is not a legal URI character is quoted.  </p></li>
       *
       * </ol>
       *
       * <p> The resulting URI string is then parsed as if by invoking the {@link
       * #URI(String)} constructor and then invoking the {@link
       * #parseServerAuthority()} method upon the result; this may cause a {@link
       * URISyntaxException} to be thrown.  </p>
       *
       * @param   scheme     Scheme name
       * @param   authority  Authority
       * @param   path       Path
       * @param   query      Query
       * @param   fragment   Fragment
       *
       * @throws URISyntaxException
       *         If both a scheme and a path are given but the path is relative,
       *         if the URI string constructed from the given components violates
       *         RFC&nbsp;2396, or if the authority component of the string is
       *         present but cannot be parsed as a server-based authority
       */
      public URI(String scheme,
                 String authority,
                 String path, String query, String fragment)
          throws URISyntaxException
      {
          String s = toString(scheme, null,
                              authority, null, null, -1,
                              path, query, fragment);
          checkPath(s, scheme, path);
          new Parser(s).parse(false);
      }
  
      /**
       * Constructs a hierarchical URI from the given components.
       *
       * <p> A component may be left undefined by passing {@code null}.
       *
       * <p> This convenience constructor works as if by invoking the
       * seven-argument constructor as follows:
       *
       * <blockquote>
       * {@code new} {@link #URI(String, String, String, int, String, String, String)
       * URI}{@code (scheme, null, host, -1, path, null, fragment);}
       * </blockquote>
       *
       * @param   scheme    Scheme name
       * @param   host      Host name
       * @param   path      Path
       * @param   fragment  Fragment
       *
       * @throws  URISyntaxException
       *          If the URI string constructed from the given components
       *          violates RFC&nbsp;2396
       */
      public URI(String scheme, String host, String path, String fragment)
          throws URISyntaxException
      {
          this(scheme, null, host, -1, path, null, fragment);
      }
  
      /**
       * Constructs a URI from the given components.
       *
       * <p> A component may be left undefined by passing {@code null}.
       *
       * <p> This constructor first builds a URI in string form using the given
       * components as follows:  </p>
       *
       * <ol>
       *
       *   <li><p> Initially, the result string is empty.  </p></li>
       *
       *   <li><p> If a scheme is given then it is appended to the result,
       *   followed by a colon character ({@code ':'}).  </p></li>
       *
       *   <li><p> If a scheme-specific part is given then it is appended.  Any
       *   character that is not a <a href="#legal-chars">legal URI character</a>
       *   is <a href="#quote">quoted</a>.  </p></li>
       *
       *   <li><p> Finally, if a fragment is given then a hash character
       *   ({@code '#'}) is appended to the string, followed by the fragment.
       *   Any character that is not a legal URI character is quoted.  </p></li>
       *
       * </ol>
       *
       * <p> The resulting URI string is then parsed in order to create the new
       * URI instance as if by invoking the {@link #URI(String)} constructor;
       * this may cause a {@link URISyntaxException} to be thrown.  </p>
       *
       * @param   scheme    Scheme name
       * @param   ssp       Scheme-specific part
       * @param   fragment  Fragment
       *
       * @throws  URISyntaxException
       *          If the URI string constructed from the given components
       *          violates RFC&nbsp;2396
       */
      public URI(String scheme, String ssp, String fragment)
          throws URISyntaxException
      {
          new Parser(toString(scheme, ssp,
                              null, null, null, -1,
                              null, null, fragment))
              .parse(false);
      }
  
      /**
       * Creates a URI by parsing the given string.
       *
       * <p> This convenience factory method works as if by invoking the {@link
       * #URI(String)} constructor; any {@link URISyntaxException} thrown by the
       * constructor is caught and wrapped in a new {@link
       * IllegalArgumentException} object, which is then thrown.
       *
       * <p> This method is provided for use in situations where it is known that
       * the given string is a legal URI, for example for URI constants declared
       * within in a program, and so it would be considered a programming error
       * for the string not to parse as such.  The constructors, which throw
       * {@link URISyntaxException} directly, should be used situations where a
       * URI is being constructed from user input or from some other source that
       * may be prone to errors.  </p>
       *
       * @param  str   The string to be parsed into a URI
       * @return The new URI
       *
       * @throws  NullPointerException
       *          If {@code str} is {@code null}
       *
       * @throws  IllegalArgumentException
       *          If the given string violates RFC&nbsp;2396
       */
      public static URI create(String str) {
          try {
              return new URI(str);
          } catch (URISyntaxException x) {
              throw new IllegalArgumentException(x.getMessage(), x);
          }
      }
  
  
      // -- Operations --
  
      /**
       * Attempts to parse this URI's authority component, if defined, into
       * user-information, host, and port components.
       *
       * <p> If this URI's authority component has already been recognized as
       * being server-based then it will already have been parsed into
       * user-information, host, and port components.  In this case, or if this
       * URI has no authority component, this method simply returns this URI.
       *
       * <p> Otherwise this method attempts once more to parse the authority
       * component into user-information, host, and port components, and throws
       * an exception describing why the authority component could not be parsed
       * in that way.
       *
       * <p> This method is provided because the generic URI syntax specified in
       * <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>
       * cannot always distinguish a malformed server-based authority from a
       * legitimate registry-based authority.  It must therefore treat some
       * instances of the former as instances of the latter.  The authority
       * component in the URI string {@code "//foo:bar"}, for example, is not a
       * legal server-based authority but it is legal as a registry-based
       * authority.
       *
       * <p> In many common situations, for example when working URIs that are
       * known to be either URNs or URLs, the hierarchical URIs being used will
       * always be server-based.  They therefore must either be parsed as such or
       * treated as an error.  In these cases a statement such as
       *
       * <blockquote>
       * {@code URI }<i>u</i>{@code  = new URI(str).parseServerAuthority();}
       * </blockquote>
       *
       * <p> can be used to ensure that <i>u</i> always refers to a URI that, if
       * it has an authority component, has a server-based authority with proper
       * user-information, host, and port components.  Invoking this method also
       * ensures that if the authority could not be parsed in that way then an
       * appropriate diagnostic message can be issued based upon the exception
       * that is thrown. </p>
       *
       * @return  A URI whose authority field has been parsed
       *          as a server-based authority
       *
       * @throws  URISyntaxException
       *          If the authority component of this URI is defined
       *          but cannot be parsed as a server-based authority
       *          according to RFC&nbsp;2396
       */
      public URI parseServerAuthority()
          throws URISyntaxException
      {
          // We could be clever and cache the error message and index from the
          // exception thrown during the original parse, but that would require
          // either more fields or a more-obscure representation.
          if ((host != null) || (authority == null))
              return this;
          defineString();
          new Parser(string).parse(true);
          return this;
      }
  
      /**
       * Normalizes this URI's path.
       *
       * <p> If this URI is opaque, or if its path is already in normal form,
       * then this URI is returned.  Otherwise a new URI is constructed that is
       * identical to this URI except that its path is computed by normalizing
       * this URI's path in a manner consistent with <a
       * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
       * section&nbsp;5.2, step&nbsp;6, sub-steps&nbsp;c through&nbsp;f; that is:
       * </p>
       *
       * <ol>
       *
       *   <li><p> All {@code "."} segments are removed. </p></li>
       *
       *   <li><p> If a {@code ".."} segment is preceded by a non-{@code ".."}
       *   segment then both of these segments are removed.  This step is
       *   repeated until it is no longer applicable. </p></li>
       *
       *   <li><p> If the path is relative, and if its first segment contains a
       *   colon character ({@code ':'}), then a {@code "."} segment is
       *   prepended.  This prevents a relative URI with a path such as
       *   {@code "a:b/c/d"} from later being re-parsed as an opaque URI with a
       *   scheme of {@code "a"} and a scheme-specific part of {@code "b/c/d"}.
       *   <b><i>(Deviation from RFC&nbsp;2396)</i></b> </p></li>
       *
       * </ol>
       *
       * <p> A normalized path will begin with one or more {@code ".."} segments
       * if there were insufficient non-{@code ".."} segments preceding them to
       * allow their removal.  A normalized path will begin with a {@code "."}
       * segment if one was inserted by step 3 above.  Otherwise, a normalized
       * path will not contain any {@code "."} or {@code ".."} segments. </p>
       *
       * @return  A URI equivalent to this URI,
       *          but whose path is in normal form
       */
      public URI normalize() {
          return normalize(this);
      }
  
      /**
       * Resolves the given URI against this URI.
       *
       * <p> If the given URI is already absolute, or if this URI is opaque, then
       * the given URI is returned.
       *
       * <p><a name="resolve-frag"></a> If the given URI's fragment component is
       * defined, its path component is empty, and its scheme, authority, and
       * query components are undefined, then a URI with the given fragment but
       * with all other components equal to those of this URI is returned.  This
       * allows a URI representing a standalone fragment reference, such as
       * {@code "#foo"}, to be usefully resolved against a base URI.
       *
       * <p> Otherwise this method constructs a new hierarchical URI in a manner
       * consistent with <a
       * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
       * section&nbsp;5.2; that is: </p>
       *
       * <ol>
       *
       *   <li><p> A new URI is constructed with this URI's scheme and the given
       *   URI's query and fragment components. </p></li>
       *
       *   <li><p> If the given URI has an authority component then the new URI's
       *   authority and path are taken from the given URI. </p></li>
       *
       *   <li><p> Otherwise the new URI's authority component is copied from
       *   this URI, and its path is computed as follows: </p>
       *
       *   <ol>
       *
       *     <li><p> If the given URI's path is absolute then the new URI's path
       *     is taken from the given URI. </p></li>
       *
       *     <li><p> Otherwise the given URI's path is relative, and so the new
       *     URI's path is computed by resolving the path of the given URI
       *     against the path of this URI.  This is done by concatenating all but
       *     the last segment of this URI's path, if any, with the given URI's
       *     path and then normalizing the result as if by invoking the {@link
       *     #normalize() normalize} method. </p></li>
       *
       *   </ol></li>
       *
       * </ol>
       *
       * <p> The result of this method is absolute if, and only if, either this
       * URI is absolute or the given URI is absolute.  </p>
       *
       * @param  uri  The URI to be resolved against this URI
       * @return The resulting URI
       *
       * @throws  NullPointerException
       *          If {@code uri} is {@code null}
       */
      public URI resolve(URI uri) {
          return resolve(this, uri);
      }
  
      /**
       * Constructs a new URI by parsing the given string and then resolving it
       * against this URI.
       *
       * <p> This convenience method works as if invoking it were equivalent to
       * evaluating the expression {@link #resolve(URI)
       * resolve}{@code (URI.}{@link #create(String) create}{@code (str))}. </p>
       *
       * @param  str   The string to be parsed into a URI
       * @return The resulting URI
       *
       * @throws  NullPointerException
       *          If {@code str} is {@code null}
       *
       * @throws  IllegalArgumentException
       *          If the given string violates RFC&nbsp;2396
       */
      public URI resolve(String str) {
          return resolve(URI.create(str));
      }
  
      /**
       * Relativizes the given URI against this URI.
       *
       * <p> The relativization of the given URI against this URI is computed as
       * follows: </p>
       *
       * <ol>
       *
       *   <li><p> If either this URI or the given URI are opaque, or if the
       *   scheme and authority components of the two URIs are not identical, or
       *   if the path of this URI is not a prefix of the path of the given URI,
       *   then the given URI is returned. </p></li>
       *
       *   <li><p> Otherwise a new relative hierarchical URI is constructed with
       *   query and fragment components taken from the given URI and with a path
       *   component computed by removing this URI's path from the beginning of
       *   the given URI's path. </p></li>
       *
       * </ol>
       *
       * @param  uri  The URI to be relativized against this URI
       * @return The resulting URI
       *
       * @throws  NullPointerException
       *          If {@code uri} is {@code null}
       */
      public URI relativize(URI uri) {
          return relativize(this, uri);
      }
  
      /**
       * Constructs a URL from this URI.
       *
       * <p> This convenience method works as if invoking it were equivalent to
       * evaluating the expression {@code new URL(this.toString())} after
       * first checking that this URI is absolute. </p>
       *
       * @return  A URL constructed from this URI
       *
       * @throws  IllegalArgumentException
       *          If this URL is not absolute
       *
       * @throws  MalformedURLException
       *          If a protocol handler for the URL could not be found,
       *          or if some other error occurred while constructing the URL
       */
      public URL toURL()
          throws MalformedURLException {
          if (!isAbsolute())
              throw new IllegalArgumentException("URI is not absolute");
          return new URL(toString());
      }
  
      // -- Component access methods --
  
      /**
       * Returns the scheme component of this URI.
       *
       * <p> The scheme component of a URI, if defined, only contains characters
       * in the <i>alphanum</i> category and in the string {@code "-.+"}.  A
       * scheme always starts with an <i>alpha</i> character. <p>
       *
       * The scheme component of a URI cannot contain escaped octets, hence this
       * method does not perform any decoding.
       *
       * @return  The scheme component of this URI,
       *          or {@code null} if the scheme is undefined
       */
      public String getScheme() {
          return scheme;
      }
  
      /**
       * Tells whether or not this URI is absolute.
       *
       * <p> A URI is absolute if, and only if, it has a scheme component. </p>
       *
       * @return  {@code true} if, and only if, this URI is absolute
       */
      public boolean isAbsolute() {
          return scheme != null;
      }
  
      /**
       * Tells whether or not this URI is opaque.
       *
       * <p> A URI is opaque if, and only if, it is absolute and its
       * scheme-specific part does not begin with a slash character ('/').
       * An opaque URI has a scheme, a scheme-specific part, and possibly
       * a fragment; all other components are undefined. </p>
       *
       * @return  {@code true} if, and only if, this URI is opaque
       */
      public boolean isOpaque() {
          return path == null;
      }
  
      /**
       * Returns the raw scheme-specific part of this URI.  The scheme-specific
       * part is never undefined, though it may be empty.
       *
       * <p> The scheme-specific part of a URI only contains legal URI
       * characters. </p>
       *
       * @return  The raw scheme-specific part of this URI
       *          (never {@code null})
       */
      public String getRawSchemeSpecificPart() {
          defineSchemeSpecificPart();
          return schemeSpecificPart;
      }
  
      /**
       * Returns the decoded scheme-specific part of this URI.
       *
       * <p> The string returned by this method is equal to that returned by the
       * {@link #getRawSchemeSpecificPart() getRawSchemeSpecificPart} method
       * except that all sequences of escaped octets are <a
       * href="#decode">decoded</a>.  </p>
       *
       * @return  The decoded scheme-specific part of this URI
       *          (never {@code null})
       */
      public String getSchemeSpecificPart() {
          if (decodedSchemeSpecificPart == null)
              decodedSchemeSpecificPart = decode(getRawSchemeSpecificPart());
          return decodedSchemeSpecificPart;
      }
  
      /**
       * Returns the raw authority component of this URI.
       *
       * <p> The authority component of a URI, if defined, only contains the
       * commercial-at character ({@code '@'}) and characters in the
       * <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, and <i>other</i>
       * categories.  If the authority is server-based then it is further
       * constrained to have valid user-information, host, and port
       * components. </p>
       *
       * @return  The raw authority component of this URI,
       *          or {@code null} if the authority is undefined
       */
      public String getRawAuthority() {
          return authority;
      }
  
      /**
       * Returns the decoded authority component of this URI.
       *
       * <p> The string returned by this method is equal to that returned by the
       * {@link #getRawAuthority() getRawAuthority} method except that all
       * sequences of escaped octets are <a href="#decode">decoded</a>.  </p>
       *
       * @return  The decoded authority component of this URI,
       *          or {@code null} if the authority is undefined
       */
      public String getAuthority() {
          if (decodedAuthority == null)
              decodedAuthority = decode(authority);
          return decodedAuthority;
      }
  
      /**
       * Returns the raw user-information component of this URI.
       *
       * <p> The user-information component of a URI, if defined, only contains
       * characters in the <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, and
       * <i>other</i> categories. </p>
       *
       * @return  The raw user-information component of this URI,
       *          or {@code null} if the user information is undefined
       */
      public String getRawUserInfo() {
          return userInfo;
      }
  
      /**
       * Returns the decoded user-information component of this URI.
       *
       * <p> The string returned by this method is equal to that returned by the
       * {@link #getRawUserInfo() getRawUserInfo} method except that all
       * sequences of escaped octets are <a href="#decode">decoded</a>.  </p>
       *
       * @return  The decoded user-information component of this URI,
       *          or {@code null} if the user information is undefined
       */
      public String getUserInfo() {
          if ((decodedUserInfo == null) && (userInfo != null))
              decodedUserInfo = decode(userInfo);
          return decodedUserInfo;
      }
  
      /**
       * Returns the host component of this URI.
       *
       * <p> The host component of a URI, if defined, will have one of the
       * following forms: </p>
       *
       * <ul>
       *
       *   <li><p> A domain name consisting of one or more <i>labels</i>
       *   separated by period characters ({@code '.'}), optionally followed by
       *   a period character.  Each label consists of <i>alphanum</i> characters
       *   as well as hyphen characters ({@code '-'}), though hyphens never
       *   occur as the first or last characters in a label. The rightmost
       *   label of a domain name consisting of two or more labels, begins
       *   with an <i>alpha</i> character. </li>
       *
       *   <li><p> A dotted-quad IPv4 address of the form
       *   <i>digit</i>{@code +.}<i>digit</i>{@code +.}<i>digit</i>{@code +.}<i>digit</i>{@code +},
       *   where no <i>digit</i> sequence is longer than three characters and no
       *   sequence has a value larger than 255. </p></li>
       *
       *   <li><p> An IPv6 address enclosed in square brackets ({@code '['} and
       *   {@code ']'}) and consisting of hexadecimal digits, colon characters
       *   ({@code ':'}), and possibly an embedded IPv4 address.  The full
       *   syntax of IPv6 addresses is specified in <a
       *   href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC&nbsp;2373: IPv6
       *   Addressing Architecture</i></a>.  </p></li>
       *
       * </ul>
       *
       * The host component of a URI cannot contain escaped octets, hence this
       * method does not perform any decoding.
       *
       * @return  The host component of this URI,
       *          or {@code null} if the host is undefined
       */
      public String getHost() {
          return host;
      }
  
      /**
       * Returns the port number of this URI.
       *
       * <p> The port component of a URI, if defined, is a non-negative
       * integer. </p>
       *
       * @return  The port component of this URI,
       *          or {@code -1} if the port is undefined
       */
      public int getPort() {
          return port;
      }
  
      /**
       * Returns the raw path component of this URI.
       *
       * <p> The path component of a URI, if defined, only contains the slash
       * character ({@code '/'}), the commercial-at character ({@code '@'}),
       * and characters in the <i>unreserved</i>, <i>punct</i>, <i>escaped</i>,
       * and <i>other</i> categories. </p>
       *
       * @return  The path component of this URI,
       *          or {@code null} if the path is undefined
       */
      public String getRawPath() {
          return path;
      }
  
      /**
       * Returns the decoded path component of this URI.
       *
       * <p> The string returned by this method is equal to that returned by the
       * {@link #getRawPath() getRawPath} method except that all sequences of
       * escaped octets are <a href="#decode">decoded</a>.  </p>
       *
       * @return  The decoded path component of this URI,
       *          or {@code null} if the path is undefined
       */
      public String getPath() {
          if ((decodedPath == null) && (path != null))
              decodedPath = decode(path);
          return decodedPath;
      }
  
      /**
       * Returns the raw query component of this URI.
       *
       * <p> The query component of a URI, if defined, only contains legal URI
       * characters. </p>
       *
       * @return  The raw query component of this URI,
       *          or {@code null} if the query is undefined
       */
      public String getRawQuery() {
          return query;
      }
  
      /**
       * Returns the decoded query component of this URI.
       *
       * <p> The string returned by this method is equal to that returned by the
       * {@link #getRawQuery() getRawQuery} method except that all sequences of
       * escaped octets are <a href="#decode">decoded</a>.  </p>
       *
       * @return  The decoded query component of this URI,
       *          or {@code null} if the query is undefined
       */
      public String getQuery() {
          if ((decodedQuery == null) && (query != null))
              decodedQuery = decode(query);
          return decodedQuery;
      }
  
      /**
       * Returns the raw fragment component of this URI.
       *
       * <p> The fragment component of a URI, if defined, only contains legal URI
       * characters. </p>
       *
       * @return  The raw fragment component of this URI,
       *          or {@code null} if the fragment is undefined
       */
      public String getRawFragment() {
          return fragment;
      }
  
      /**
       * Returns the decoded fragment component of this URI.
       *
       * <p> The string returned by this method is equal to that returned by the
       * {@link #getRawFragment() getRawFragment} method except that all
       * sequences of escaped octets are <a href="#decode">decoded</a>.  </p>
       *
       * @return  The decoded fragment component of this URI,
       *          or {@code null} if the fragment is undefined
       */
      public String getFragment() {
          if ((decodedFragment == null) && (fragment != null))
              decodedFragment = decode(fragment);
          return decodedFragment;
      }
  
  
      // -- Equality, comparison, hash code, toString, and serialization --
  
      /**
       * Tests this URI for equality with another object.
       *
       * <p> If the given object is not a URI then this method immediately
       * returns {@code false}.
       *
       * <p> For two URIs to be considered equal requires that either both are
       * opaque or both are hierarchical.  Their schemes must either both be
       * undefined or else be equal without regard to case. Their fragments
       * must either both be undefined or else be equal.
       *
       * <p> For two opaque URIs to be considered equal, their scheme-specific
       * parts must be equal.
       *
       * <p> For two hierarchical URIs to be considered equal, their paths must
       * be equal and their queries must either both be undefined or else be
       * equal.  Their authorities must either both be undefined, or both be
       * registry-based, or both be server-based.  If their authorities are
       * defined and are registry-based, then they must be equal.  If their
       * authorities are defined and are server-based, then their hosts must be
       * equal without regard to case, their port numbers must be equal, and
       * their user-information components must be equal.
       *
       * <p> When testing the user-information, path, query, fragment, authority,
       * or scheme-specific parts of two URIs for equality, the raw forms rather
       * than the encoded forms of these components are compared and the
       * hexadecimal digits of escaped octets are compared without regard to
       * case.
       *
       * <p> This method satisfies the general contract of the {@link
       * Object#equals(Object) Object.equals} method. </p>
       *
       * @param   ob   The object to which this object is to be compared
       *
       * @return  {@code true} if, and only if, the given object is a URI that
       *          is identical to this URI
       */
      public boolean equals(Object ob) {
          if (ob == this)
              return true;
          if (!(ob instanceof URI))
              return false;
          URI that = (URI)ob;
          if (this.isOpaque() != that.isOpaque()) return false;
          if (!equalIgnoringCase(this.scheme, that.scheme)) return false;
          if (!equal(this.fragment, that.fragment)) return false;
  
          // Opaque
          if (this.isOpaque())
              return equal(this.schemeSpecificPart, that.schemeSpecificPart);
  
          // Hierarchical
          if (!equal(this.path, that.path)) return false;
          if (!equal(this.query, that.query)) return false;
  
          // Authorities
          if (this.authority == that.authority) return true;
          if (this.host != null) {
              // Server-based
              if (!equal(this.userInfo, that.userInfo)) return false;
              if (!equalIgnoringCase(this.host, that.host)) return false;
              if (this.port != that.port) return false;
          } else if (this.authority != null) {
              // Registry-based
              if (!equal(this.authority, that.authority)) return false;
          } else if (this.authority != that.authority) {
              return false;
          }
  
          return true;
      }
  
      /**
       * Returns a hash-code value for this URI.  The hash code is based upon all
       * of the URI's components, and satisfies the general contract of the
       * {@link Object#hashCode() Object.hashCode} method.
       *
       * @return  A hash-code value for this URI
       */
      public int hashCode() {
          if (hash != 0)
              return hash;
          int h = hashIgnoringCase(0, scheme);
          h = hash(h, fragment);
          if (isOpaque()) {
              h = hash(h, schemeSpecificPart);
          } else {
              h = hash(h, path);
              h = hash(h, query);
              if (host != null) {
                  h = hash(h, userInfo);
                  h = hashIgnoringCase(h, host);
                  h += 1949 * port;
              } else {
                  h = hash(h, authority);
              }
          }
          hash = h;
          return h;
      }
  
      /**
       * Compares this URI to another object, which must be a URI.
       *
       * <p> When comparing corresponding components of two URIs, if one
       * component is undefined but the other is defined then the first is
       * considered to be less than the second.  Unless otherwise noted, string
       * components are ordered according to their natural, case-sensitive
       * ordering as defined by the {@link String#compareTo(Object)
       * String.compareTo} method.  String components that are subject to
       * encoding are compared by comparing their raw forms rather than their
       * encoded forms.
       *
       * <p> The ordering of URIs is defined as follows: </p>
       *
       * <ul>
       *
       *   <li><p> Two URIs with different schemes are ordered according the
       *   ordering of their schemes, without regard to case. </p></li>
       *
       *   <li><p> A hierarchical URI is considered to be less than an opaque URI
       *   with an identical scheme. </p></li>
       *
       *   <li><p> Two opaque URIs with identical schemes are ordered according
       *   to the ordering of their scheme-specific parts. </p></li>
       *
       *   <li><p> Two opaque URIs with identical schemes and scheme-specific
       *   parts are ordered according to the ordering of their
       *   fragments. </p></li>
       *
       *   <li><p> Two hierarchical URIs with identical schemes are ordered
       *   according to the ordering of their authority components: </p>
       *
       *   <ul>
       *
       *     <li><p> If both authority components are server-based then the URIs
       *     are ordered according to their user-information components; if these
       *     components are identical then the URIs are ordered according to the
       *     ordering of their hosts, without regard to case; if the hosts are
       *     identical then the URIs are ordered according to the ordering of
       *     their ports. </p></li>
       *
       *     <li><p> If one or both authority components are registry-based then
       *     the URIs are ordered according to the ordering of their authority
       *     components. </p></li>
       *
       *   </ul></li>
       *
       *   <li><p> Finally, two hierarchical URIs with identical schemes and
       *   authority components are ordered according to the ordering of their
       *   paths; if their paths are identical then they are ordered according to
       *   the ordering of their queries; if the queries are identical then they
       *   are ordered according to the order of their fragments. </p></li>
       *
       * </ul>
       *
       * <p> This method satisfies the general contract of the {@link
       * Comparable#compareTo(Object) Comparable.compareTo}
       * method. </p>
       *
       * @param   that
       *          The object to which this URI is to be compared
       *
       * @return  A negative integer, zero, or a positive integer as this URI is
       *          less than, equal to, or greater than the given URI
       *
       * @throws  ClassCastException
       *          If the given object is not a URI
       */
      public int compareTo(URI that) {
          int c;
  
          if ((c = compareIgnoringCase(this.scheme, that.scheme)) != 0)
              return c;
  
          if (this.isOpaque()) {
              if (that.isOpaque()) {
                  // Both opaque
                  if ((c = compare(this.schemeSpecificPart,
                                   that.schemeSpecificPart)) != 0)
                      return c;
                  return compare(this.fragment, that.fragment);
              }
              return +1;                  // Opaque > hierarchical
          } else if (that.isOpaque()) {
              return -1;                  // Hierarchical < opaque
          }
  
          // Hierarchical
          if ((this.host != null) && (that.host != null)) {
              // Both server-based
              if ((c = compare(this.userInfo, that.userInfo)) != 0)
                  return c;
              if ((c = compareIgnoringCase(this.host, that.host)) != 0)
                  return c;
              if ((c = this.port - that.port) != 0)
                  return c;
          } else {
              // If one or both authorities are registry-based then we simply
              // compare them in the usual, case-sensitive way.  If one is
              // registry-based and one is server-based then the strings are
              // guaranteed to be unequal, hence the comparison will never return
              // zero and the compareTo and equals methods will remain
              // consistent.
              if ((c = compare(this.authority, that.authority)) != 0) return c;
          }
  
          if ((c = compare(this.path, that.path)) != 0) return c;
          if ((c = compare(this.query, that.query)) != 0) return c;
          return compare(this.fragment, that.fragment);
      }
  
      /**
       * Returns the content of this URI as a string.
       *
       * <p> If this URI was created by invoking one of the constructors in this
       * class then a string equivalent to the original input string, or to the
       * string computed from the originally-given components, as appropriate, is
       * returned.  Otherwise this URI was created by normalization, resolution,
       * or relativization, and so a string is constructed from this URI's
       * components according to the rules specified in <a
       * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
       * section&nbsp;5.2, step&nbsp;7. </p>
       *
       * @return  The string form of this URI
       */
      public String toString() {
          defineString();
          return string;
      }
  
      /**
       * Returns the content of this URI as a US-ASCII string.
       *
       * <p> If this URI does not contain any characters in the <i>other</i>
       * category then an invocation of this method will return the same value as
       * an invocation of the {@link #toString() toString} method.  Otherwise
       * this method works as if by invoking that method and then <a
       * href="#encode">encoding</a> the result.  </p>
       *
       * @return  The string form of this URI, encoded as needed
       *          so that it only contains characters in the US-ASCII
       *          charset
       */
      public String toASCIIString() {
          defineString();
          return encode(string);
      }
  
  
      // -- Serialization support --
  
      /**
       * Saves the content of this URI to the given serial stream.
       *
       * <p> The only serializable field of a URI instance is its {@code string}
       * field.  That field is given a value, if it does not have one already,
       * and then the {@link ObjectOutputStream#defaultWriteObject()}
       * method of the given object-output stream is invoked. </p>
       *
       * @param  os  The object-output stream to which this object
       *             is to be written
       */
      private void writeObject(ObjectOutputStream os)
          throws IOException
      {
          defineString();
          os.defaultWriteObject();        // Writes the string field only
      }
  
      /**
       * Reconstitutes a URI from the given serial stream.
       *
       * <p> The {@link ObjectInputStream#defaultReadObject()} method is
       * invoked to read the value of the {@code string} field.  The result is
       * then parsed in the usual way.
       *
       * @param  is  The object-input stream from which this object
       *             is being read
       */
      private void readObject(ObjectInputStream is)
          throws ClassNotFoundException, IOException
      {
          port = -1;                      // Argh
          is.defaultReadObject();
          try {
              new Parser(string).parse(false);
          } catch (URISyntaxException x) {
              IOException y = new InvalidObjectException("Invalid URI");
              y.initCause(x);
              throw y;
          }
      }
  
  
      // -- End of public methods --
  
  
      // -- Utility methods for string-field comparison and hashing --
  
      // These methods return appropriate values for null string arguments,
      // thereby simplifying the equals, hashCode, and compareTo methods.
      //
      // The case-ignoring methods should only be applied to strings whose
      // characters are all known to be US-ASCII.  Because of this restriction,
      // these methods are faster than the similar methods in the String class.
  
      // US-ASCII only
      private static int toLower(char c) {
          if ((c >= 'A') && (c <= 'Z'))
              return c + ('a' - 'A');
          return c;
      }
  
      // US-ASCII only
      private static int toUpper(char c) {
          if ((c >= 'a') && (c <= 'z'))
              return c - ('a' - 'A');
          return c;
      }
  
      private static boolean equal(String s, String t) {
          if (s == t) return true;
          if ((s != null) && (t != null)) {
              if (s.length() != t.length())
                  return false;
              if (s.indexOf('%') < 0)
                  return s.equals(t);
              int n = s.length();
              for (int i = 0; i < n;) {
                  char c = s.charAt(i);
                  char d = t.charAt(i);
                  if (c != '%') {
                      if (c != d)
                          return false;
                      i++;
                      continue;
                  }
                  if (d != '%')
                      return false;
                  i++;
                  if (toLower(s.charAt(i)) != toLower(t.charAt(i)))
                      return false;
                  i++;
                  if (toLower(s.charAt(i)) != toLower(t.charAt(i)))
                      return false;
                  i++;
              }
              return true;
          }
          return false;
      }
  
      // US-ASCII only
      private static boolean equalIgnoringCase(String s, String t) {
          if (s == t) return true;
          if ((s != null) && (t != null)) {
              int n = s.length();
              if (t.length() != n)
                  return false;
              for (int i = 0; i < n; i++) {
                  if (toLower(s.charAt(i)) != toLower(t.charAt(i)))
                      return false;
              }
              return true;
          }
          return false;
      }
  
      private static int hash(int hash, String s) {
          if (s == null) return hash;
          return s.indexOf('%') < 0 ? hash * 127 + s.hashCode()
                                    : normalizedHash(hash, s);
      }
  
  
      private static int normalizedHash(int hash, String s) {
          int h = 0;
          for (int index = 0; index < s.length(); index++) {
              char ch = s.charAt(index);
              h = 31 * h + ch;
              if (ch == '%') {
                  /*
                   * Process the next two encoded characters
                   */
                  for (int i = index + 1; i < index + 3; i++)
                      h = 31 * h + toUpper(s.charAt(i));
                  index += 2;
              }
          }
          return hash * 127 + h;
      }
  
      // US-ASCII only
      private static int hashIgnoringCase(int hash, String s) {
          if (s == null) return hash;
          int h = hash;
          int n = s.length();
          for (int i = 0; i < n; i++)
              h = 31 * h + toLower(s.charAt(i));
          return h;
      }
  
      private static int compare(String s, String t) {
          if (s == t) return 0;
          if (s != null) {
              if (t != null)
                  return s.compareTo(t);
              else
                  return +1;
          } else {
              return -1;
          }
      }
  
      // US-ASCII only
      private static int compareIgnoringCase(String s, String t) {
          if (s == t) return 0;
          if (s != null) {
              if (t != null) {
                  int sn = s.length();
                  int tn = t.length();
                  int n = sn < tn ? sn : tn;
                  for (int i = 0; i < n; i++) {
                      int c = toLower(s.charAt(i)) - toLower(t.charAt(i));
                      if (c != 0)
                          return c;
                  }
                  return sn - tn;
              }
              return +1;
          } else {
              return -1;
          }
      }
  
  
      // -- String construction --
  
      // If a scheme is given then the path, if given, must be absolute
      //
      private static void checkPath(String s, String scheme, String path)
          throws URISyntaxException
      {
          if (scheme != null) {
              if ((path != null)
                  && ((path.length() > 0) && (path.charAt(0) != '/')))
                  throw new URISyntaxException(s,
                                               "Relative path in absolute URI");
          }
      }
  
      private void appendAuthority(StringBuffer sb,
                                   String authority,
                                   String userInfo,
                                   String host,
                                   int port)
      {
          if (host != null) {
              sb.append("//");
              if (userInfo != null) {
                  sb.append(quote(userInfo, L_USERINFO, H_USERINFO));
                  sb.append('@');
              }
              boolean needBrackets = ((host.indexOf(':') >= 0)
                                      && !host.startsWith("[")
                                      && !host.endsWith("]"));
              if (needBrackets) sb.append('[');
              sb.append(host);
              if (needBrackets) sb.append(']');
              if (port != -1) {
                  sb.append(':');
                  sb.append(port);
              }
          } else if (authority != null) {
              sb.append("//");
              if (authority.startsWith("[")) {
                  // authority should (but may not) contain an embedded IPv6 address
                  int end = authority.indexOf("]");
                  String doquote = authority, dontquote = "";
                  if (end != -1 && authority.indexOf(":") != -1) {
                      // the authority contains an IPv6 address
                      if (end == authority.length()) {
                          dontquote = authority;
                          doquote = "";
                      } else {
                          dontquote = authority.substring(0 , end + 1);
                          doquote = authority.substring(end + 1);
                      }
                  }
                  sb.append(dontquote);
                  sb.append(quote(doquote,
                              L_REG_NAME | L_SERVER,
                              H_REG_NAME | H_SERVER));
              } else {
                  sb.append(quote(authority,
                              L_REG_NAME | L_SERVER,
                              H_REG_NAME | H_SERVER));
              }
          }
      }
  
      private void appendSchemeSpecificPart(StringBuffer sb,
                                            String opaquePart,
                                            String authority,
                                            String userInfo,
                                            String host,
                                            int port,
                                            String path,
                                            String query)
      {
          if (opaquePart != null) {
              /* check if SSP begins with an IPv6 address
               * because we must not quote a literal IPv6 address
               */
              if (opaquePart.startsWith("//[")) {
                  int end =  opaquePart.indexOf("]");
                  if (end != -1 && opaquePart.indexOf(":")!=-1) {
                      String doquote, dontquote;
                      if (end == opaquePart.length()) {
                          dontquote = opaquePart;
                          doquote = "";
                      } else {
                          dontquote = opaquePart.substring(0,end+1);
                          doquote = opaquePart.substring(end+1);
                      }
                      sb.append (dontquote);
                      sb.append(quote(doquote, L_URIC, H_URIC));
                  }
              } else {
                  sb.append(quote(opaquePart, L_URIC, H_URIC));
              }
          } else {
              appendAuthority(sb, authority, userInfo, host, port);
              if (path != null)
                  sb.append(quote(path, L_PATH, H_PATH));
              if (query != null) {
                  sb.append('?');
                  sb.append(quote(query, L_URIC, H_URIC));
              }
          }
      }
  
      private void appendFragment(StringBuffer sb, String fragment) {
          if (fragment != null) {
              sb.append('#');
              sb.append(quote(fragment, L_URIC, H_URIC));
          }
      }
  
      private String toString(String scheme,
                              String opaquePart,
                              String authority,
                              String userInfo,
                              String host,
                              int port,
                              String path,
                              String query,
                              String fragment)
      {
          StringBuffer sb = new StringBuffer();
          if (scheme != null) {
              sb.append(scheme);
              sb.append(':');
          }
          appendSchemeSpecificPart(sb, opaquePart,
                                   authority, userInfo, host, port,
                                   path, query);
          appendFragment(sb, fragment);
          return sb.toString();
      }
  
      private void defineSchemeSpecificPart() {
          if (schemeSpecificPart != null) return;
          StringBuffer sb = new StringBuffer();
          appendSchemeSpecificPart(sb, null, getAuthority(), getUserInfo(),
                                   host, port, getPath(), getQuery());
          if (sb.length() == 0) return;
          schemeSpecificPart = sb.toString();
      }
  
      private void defineString() {
          if (string != null) return;
  
          StringBuffer sb = new StringBuffer();
          if (scheme != null) {
              sb.append(scheme);
              sb.append(':');
          }
          if (isOpaque()) {
              sb.append(schemeSpecificPart);
          } else {
              if (host != null) {
                  sb.append("//");
                  if (userInfo != null) {
                      sb.append(userInfo);
                      sb.append('@');
                  }
                  boolean needBrackets = ((host.indexOf(':') >= 0)
                                      && !host.startsWith("[")
                                      && !host.endsWith("]"));
                  if (needBrackets) sb.append('[');
                  sb.append(host);
                  if (needBrackets) sb.append(']');
                  if (port != -1) {
                      sb.append(':');
                      sb.append(port);
                  }
              } else if (authority != null) {
                  sb.append("//");
                  sb.append(authority);
              }
              if (path != null)
                  sb.append(path);
              if (query != null) {
                  sb.append('?');
                  sb.append(query);
              }
          }
          if (fragment != null) {
              sb.append('#');
              sb.append(fragment);
          }
          string = sb.toString();
      }
  
  
      // -- Normalization, resolution, and relativization --
  
      // RFC2396 5.2 (6)
      private static String resolvePath(String base, String child,
                                        boolean absolute)
      {
          int i = base.lastIndexOf('/');
          int cn = child.length();
          String path = "";
  
          if (cn == 0) {
              // 5.2 (6a)
              if (i >= 0)
                  path = base.substring(0, i + 1);
          } else {
              StringBuffer sb = new StringBuffer(base.length() + cn);
              // 5.2 (6a)
              if (i >= 0)
                  sb.append(base.substring(0, i + 1));
              // 5.2 (6b)
              sb.append(child);
              path = sb.toString();
          }
  
          // 5.2 (6c-f)
          // Android-changed: App compat. Remove leading dots when resolving path. http://b/25897693
          // String np = normalize(path);
          String np = normalize(path, true);
  
          // 5.2 (6g): If the result is absolute but the path begins with "../",
          // then we simply leave the path as-is
  
          return np;
      }
  
      // RFC2396 5.2
      private static URI resolve(URI base, URI child) {
          // check if child if opaque first so that NPE is thrown
          // if child is null.
          if (child.isOpaque() || base.isOpaque())
              return child;
  
          // 5.2 (2): Reference to current document (lone fragment)
          if ((child.scheme == null) && (child.authority == null)
              && child.path.equals("") && (child.fragment != null)
              && (child.query == null)) {
              if ((base.fragment != null)
                  && child.fragment.equals(base.fragment)) {
                  return base;
              }
              URI ru = new URI();
              ru.scheme = base.scheme;
              ru.authority = base.authority;
              ru.userInfo = base.userInfo;
              ru.host = base.host;
              ru.port = base.port;
              ru.path = base.path;
              ru.fragment = child.fragment;
              ru.query = base.query;
              return ru;
          }
  
          // 5.2 (3): Child is absolute
          if (child.scheme != null)
              return child;
  
          URI ru = new URI();             // Resolved URI
          ru.scheme = base.scheme;
          ru.query = child.query;
          ru.fragment = child.fragment;
  
          // 5.2 (4): Authority
          if (child.authority == null) {
              ru.authority = base.authority;
              ru.host = base.host;
              ru.userInfo = base.userInfo;
              ru.port = base.port;
  
              // BEGIN Android-changed: App Compat. Handle null and empty path using RFC 3986 logic
              // http://b/25897693
              if (child.path == null || child.path.isEmpty()) {
                  // This is an additional path from RFC 3986 RI, which fixes following RFC 2396
                  // "normal" examples:
                  // Base: http://a/b/c/d;p?q
                  //   "?y" = "http://a/b/c/d;p?y"
                  //   ""   = "http://a/b/c/d;p?q"
                  // http://b/25897693
                  ru.path = base.path;
                  ru.query = child.query != null ? child.query : base.query;
              // END Android-changed: App Compat. Handle null and empty path using RFC 3986 logic
              } else if ((child.path.length() > 0) && (child.path.charAt(0) == '/')) {
                  // 5.2 (5): Child path is absolute
                  //
                  // Android-changed: App Compat. Remove leading dots in path.
                  // There is an additional step from RFC 3986 RI, requiring to remove dots for
                  // absolute path as well.
                  // http://b/25897693
                  // ru.path = child.path;
                  ru.path = normalize(child.path, true);
              } else {
                  // 5.2 (6): Resolve relative path
                  ru.path = resolvePath(base.path, child.path, base.isAbsolute());
              }
          } else {
              ru.authority = child.authority;
              ru.host = child.host;
              ru.userInfo = child.userInfo;
              ru.host = child.host;
              ru.port = child.port;
              ru.path = child.path;
          }
  
          // 5.2 (7): Recombine (nothing to do here)
          return ru;
      }
  
      // If the given URI's path is normal then return the URI;
      // o.w., return a new URI containing the normalized path.
      //
      private static URI normalize(URI u) {
          if (u.isOpaque() || (u.path == null) || (u.path.length() == 0))
              return u;
  
          String np = normalize(u.path);
          if (np == u.path)
              return u;
  
          URI v = new URI();
          v.scheme = u.scheme;
          v.fragment = u.fragment;
          v.authority = u.authority;
          v.userInfo = u.userInfo;
          v.host = u.host;
          v.port = u.port;
          v.path = np;
          v.query = u.query;
          return v;
      }
  
      // If both URIs are hierarchical, their scheme and authority components are
      // identical, and the base path is a prefix of the child's path, then
      // return a relative URI that, when resolved against the base, yields the
      // child; otherwise, return the child.
      //
      private static URI relativize(URI base, URI child) {
          // check if child if opaque first so that NPE is thrown
          // if child is null.
          if (child.isOpaque() || base.isOpaque())
              return child;
          if (!equalIgnoringCase(base.scheme, child.scheme)
              || !equal(base.authority, child.authority))
              return child;
  
          String bp = normalize(base.path);
          String cp = normalize(child.path);
          if (!bp.equals(cp)) {
              // Android-changed: App Compat. Interpret ambiguous base path as a file, not a directory
              // Upstream would append '/' to bp if not present, interpreting it as a directory; thus,
              // /a/b/c relative to /a/b would become /c, whereas Android would relativize to /b/c.
              // The spec is pretty vague about this but the Android behavior is kept because several
              // tests enforce it.
              // if (!bp.endsWith("/"))
              //     bp = bp + "/";
              if (bp.indexOf('/') != -1) {
                  bp = bp.substring(0, bp.lastIndexOf('/') + 1);
              }
  
              if (!cp.startsWith(bp))
                  return child;
          }
  
          URI v = new URI();
          v.path = cp.substring(bp.length());
          v.query = child.query;
          v.fragment = child.fragment;
          return v;
      }
  
  
  
      // -- Path normalization --
  
      // The following algorithm for path normalization avoids the creation of a
      // string object for each segment, as well as the use of a string buffer to
      // compute the final result, by using a single char array and editing it in
      // place.  The array is first split into segments, replacing each slash
      // with '\0' and creating a segment-index array, each element of which is
      // the index of the first char in the corresponding segment.  We then walk
      // through both arrays, removing ".", "..", and other segments as necessary
      // by setting their entries in the index array to -1.  Finally, the two
      // arrays are used to rejoin the segments and compute the final result.
      //
      // This code is based upon src/solaris/native/java/io/canonicalize_md.c
  
  
      // Check the given path to see if it might need normalization.  A path
      // might need normalization if it contains duplicate slashes, a "."
      // segment, or a ".." segment.  Return -1 if no further normalization is
      // possible, otherwise return the number of segments found.
      //
      // This method takes a string argument rather than a char array so that
      // this test can be performed without invoking path.toCharArray().
      //
      static private int needsNormalization(String path) {
          boolean normal = true;
          int ns = 0;                     // Number of segments
          int end = path.length() - 1;    // Index of last char in path
          int p = 0;                      // Index of next char in path
  
          // Skip initial slashes
          while (p <= end) {
              if (path.charAt(p) != '/') break;
              p++;
          }
          if (p > 1) normal = false;
  
          // Scan segments
          while (p <= end) {
  
              // Looking at "." or ".." ?
              if ((path.charAt(p) == '.')
                  && ((p == end)
                      || ((path.charAt(p + 1) == '/')
                          || ((path.charAt(p + 1) == '.')
                              && ((p + 1 == end)
                                  || (path.charAt(p + 2) == '/')))))) {
                  normal = false;
              }
              ns++;
  
              // Find beginning of next segment
              while (p <= end) {
                  if (path.charAt(p++) != '/')
                      continue;
  
                  // Skip redundant slashes
                  while (p <= end) {
                      if (path.charAt(p) != '/') break;
                      normal = false;
                      p++;
                  }
  
                  break;
              }
          }
  
          return normal ? -1 : ns;
      }
  
  
      // Split the given path into segments, replacing slashes with nulls and
      // filling in the given segment-index array.
      //
      // Preconditions:
      //   segs.length == Number of segments in path
      //
      // Postconditions:
      //   All slashes in path replaced by '\0'
      //   segs[i] == Index of first char in segment i (0 <= i < segs.length)
      //
      static private void split(char[] path, int[] segs) {
          int end = path.length - 1;      // Index of last char in path
          int p = 0;                      // Index of next char in path
          int i = 0;                      // Index of current segment
  
          // Skip initial slashes
          while (p <= end) {
              if (path[p] != '/') break;
              path[p] = '\0';
              p++;
          }
  
          while (p <= end) {
  
              // Note start of segment
              segs[i++] = p++;
  
              // Find beginning of next segment
              while (p <= end) {
                  if (path[p++] != '/')
                      continue;
                  path[p - 1] = '\0';
  
                  // Skip redundant slashes
                  while (p <= end) {
                      if (path[p] != '/') break;
                      path[p++] = '\0';
                  }
                  break;
              }
          }
  
          if (i != segs.length)
              throw new InternalError();  // ASSERT
      }
  
  
      // Join the segments in the given path according to the given segment-index
      // array, ignoring those segments whose index entries have been set to -1,
      // and inserting slashes as needed.  Return the length of the resulting
      // path.
      //
      // Preconditions:
      //   segs[i] == -1 implies segment i is to be ignored
      //   path computed by split, as above, with '\0' having replaced '/'
      //
      // Postconditions:
      //   path[0] .. path[return value] == Resulting path
      //
      static private int join(char[] path, int[] segs) {
          int ns = segs.length;           // Number of segments
          int end = path.length - 1;      // Index of last char in path
          int p = 0;                      // Index of next path char to write
  
          if (path[p] == '\0') {
              // Restore initial slash for absolute paths
              path[p++] = '/';
          }
  
          for (int i = 0; i < ns; i++) {
              int q = segs[i];            // Current segment
              if (q == -1)
                  // Ignore this segment
                  continue;
  
              if (p == q) {
                  // We're already at this segment, so just skip to its end
                  while ((p <= end) && (path[p] != '\0'))
                      p++;
                  if (p <= end) {
                      // Preserve trailing slash
                      path[p++] = '/';
                  }
              } else if (p < q) {
                  // Copy q down to p
                  while ((q <= end) && (path[q] != '\0'))
                      path[p++] = path[q++];
                  if (q <= end) {
                      // Preserve trailing slash
                      path[p++] = '/';
                  }
              } else
                  throw new InternalError(); // ASSERT false
          }
  
          return p;
      }
  
  
      // Remove "." segments from the given path, and remove segment pairs
      // consisting of a non-".." segment followed by a ".." segment.
      //
      // Android-changed: App compat. Remove leading dots when resolving path. http://b/25897693
      // private static void removeDots(char[] path, int[] segs) {
      private static void removeDots(char[] path, int[] segs, boolean removeLeading) {
          int ns = segs.length;
          int end = path.length - 1;
  
          for (int i = 0; i < ns; i++) {
              int dots = 0;               // Number of dots found (0, 1, or 2)
  
              // Find next occurrence of "." or ".."
              do {
                  int p = segs[i];
                  if (path[p] == '.') {
                      if (p == end) {
                          dots = 1;
                          break;
                      } else if (path[p + 1] == '\0') {
                          dots = 1;
                          break;
                      } else if ((path[p + 1] == '.')
                                 && ((p + 1 == end)
                                     || (path[p + 2] == '\0'))) {
                          dots = 2;
                          break;
                      }
                  }
                  i++;
              } while (i < ns);
              if ((i > ns) || (dots == 0))
                  break;
  
              if (dots == 1) {
                  // Remove this occurrence of "."
                  segs[i] = -1;
              } else {
                  // If there is a preceding non-".." segment, remove both that
                  // segment and this occurrence of ".."
                  int j;
                  for (j = i - 1; j >= 0; j--) {
                      if (segs[j] != -1) break;
                  }
                  if (j >= 0) {
                      int q = segs[j];
                      if (!((path[q] == '.')
                            && (path[q + 1] == '.')
                            && (path[q + 2] == '\0'))) {
                          segs[i] = -1;
                          segs[j] = -1;
                      }
                  // Android-added: App compat. Remove leading dots when resolving path.
                  // This is a leading ".." segment. Per RFC 3986 RI, this should be removed as
                  // well. This fixes RFC 2396 "abnormal" examples.
                  // http://b/25897693
                  } else if (removeLeading) {
                      segs[i] = -1;
                  }
              }
          }
      }
  
  
      // DEVIATION: If the normalized path is relative, and if the first
      // segment could be parsed as a scheme name, then prepend a "." segment
      //
      private static void maybeAddLeadingDot(char[] path, int[] segs) {
  
          if (path[0] == '\0')
              // The path is absolute
              return;
  
          int ns = segs.length;
          int f = 0;                      // Index of first segment
          while (f < ns) {
              if (segs[f] >= 0)
                  break;
              f++;
          }
          if ((f >= ns) || (f == 0))
              // The path is empty, or else the original first segment survived,
              // in which case we already know that no leading "." is needed
              return;
  
          int p = segs[f];
          while ((p < path.length) && (path[p] != ':') && (path[p] != '\0')) p++;
          if (p >= path.length || path[p] == '\0')
              // No colon in first segment, so no "." needed
              return;
  
          // At this point we know that the first segment is unused,
          // hence we can insert a "." segment at that position
          path[0] = '.';
          path[1] = '\0';
          segs[0] = 0;
      }
  
  
      // Normalize the given path string.  A normal path string has no empty
      // segments (i.e., occurrences of "//"), no segments equal to ".", and no
      // segments equal to ".." that are preceded by a segment not equal to "..".
      // In contrast to Unix-style pathname normalization, for URI paths we
      // always retain trailing slashes.
      //
      private static String normalize(String ps) {
          // BEGIN Android-changed: App compat. Remove leading dots when resolving path.
          // Controlled by the "boolean removeLeading" argument added to normalize().
          return normalize(ps, false);
      }
  
      private static String normalize(String ps, boolean removeLeading) {
          // END Android-changed: App compat. Remove leading dots when resolving path.
          // Does this path need normalization?
          int ns = needsNormalization(ps);        // Number of segments
          if (ns < 0)
              // Nope -- just return it
              return ps;
  
          char[] path = ps.toCharArray();         // Path in char-array form
  
          // Split path into segments
          int[] segs = new int[ns];               // Segment-index array
          split(path, segs);
  
          // Remove dots
          // Android-changed: App compat. Remove leading dots when resolving path.
          // removeDots(path, segs);
          removeDots(path, segs, removeLeading);
  
          // Prevent scheme-name confusion
          maybeAddLeadingDot(path, segs);
  
          // Join the remaining segments and return the result
          String s = new String(path, 0, join(path, segs));
          if (s.equals(ps)) {
              // string was already normalized
              return ps;
          }
          return s;
      }
  
  
  
      // -- Character classes for parsing --
  
      // RFC2396 precisely specifies which characters in the US-ASCII charset are
      // permissible in the various components of a URI reference.  We here
      // define a set of mask pairs to aid in enforcing these restrictions.  Each
      // mask pair consists of two longs, a low mask and a high mask.  Taken
      // together they represent a 128-bit mask, where bit i is set iff the
      // character with value i is permitted.
      //
      // This approach is more efficient than sequentially searching arrays of
      // permitted characters.  It could be made still more efficient by
      // precompiling the mask information so that a character's presence in a
      // given mask could be determined by a single table lookup.
  
      // Compute the low-order mask for the characters in the given string
      private static long lowMask(String chars) {
          int n = chars.length();
          long m = 0;
          for (int i = 0; i < n; i++) {
              char c = chars.charAt(i);
              if (c < 64)
                  m |= (1L << c);
          }
          return m;
      }
  
      // Compute the high-order mask for the characters in the given string
      private static long highMask(String chars) {
          int n = chars.length();
          long m = 0;
          for (int i = 0; i < n; i++) {
              char c = chars.charAt(i);
              if ((c >= 64) && (c < 128))
                  m |= (1L << (c - 64));
          }
          return m;
      }
  
      // Compute a low-order mask for the characters
      // between first and last, inclusive
      private static long lowMask(char first, char last) {
          long m = 0;
          int f = Math.max(Math.min(first, 63), 0);
          int l = Math.max(Math.min(last, 63), 0);
          for (int i = f; i <= l; i++)
              m |= 1L << i;
          return m;
      }
  
      // Compute a high-order mask for the characters
      // between first and last, inclusive
      private static long highMask(char first, char last) {
          long m = 0;
          int f = Math.max(Math.min(first, 127), 64) - 64;
          int l = Math.max(Math.min(last, 127), 64) - 64;
          for (int i = f; i <= l; i++)
              m |= 1L << i;
          return m;
      }
  
      // Tell whether the given character is permitted by the given mask pair
      private static boolean match(char c, long lowMask, long highMask) {
          if (c == 0) // 0 doesn't have a slot in the mask. So, it never matches.
              return false;
          if (c < 64)
              return ((1L << c) & lowMask) != 0;
          if (c < 128)
              return ((1L << (c - 64)) & highMask) != 0;
          return false;
      }
  
      // Character-class masks, in reverse order from RFC2396 because
      // initializers for static fields cannot make forward references.
  
      // digit    = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
      //            "8" | "9"
      private static final long L_DIGIT = lowMask('0', '9');
      private static final long H_DIGIT = 0L;
  
      // upalpha  = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" |
      //            "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" |
      //            "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
      private static final long L_UPALPHA = 0L;
      private static final long H_UPALPHA = highMask('A', 'Z');
  
      // lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" |
      //            "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" |
      //            "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"
      private static final long L_LOWALPHA = 0L;
      private static final long H_LOWALPHA = highMask('a', 'z');
  
      // alpha         = lowalpha | upalpha
      private static final long L_ALPHA = L_LOWALPHA | L_UPALPHA;
      private static final long H_ALPHA = H_LOWALPHA | H_UPALPHA;
  
      // alphanum      = alpha | digit
      private static final long L_ALPHANUM = L_DIGIT | L_ALPHA;
      private static final long H_ALPHANUM = H_DIGIT | H_ALPHA;
  
      // hex           = digit | "A" | "B" | "C" | "D" | "E" | "F" |
      //                         "a" | "b" | "c" | "d" | "e" | "f"
      private static final long L_HEX = L_DIGIT;
      private static final long H_HEX = highMask('A', 'F') | highMask('a', 'f');
  
      // mark          = "-" | "_" | "." | "!" | "~" | "*" | "'" |
      //                 "(" | ")"
      private static final long L_MARK = lowMask("-_.!~*'()");
      private static final long H_MARK = highMask("-_.!~*'()");
  
      // unreserved    = alphanum | mark
      private static final long L_UNRESERVED = L_ALPHANUM | L_MARK;
      private static final long H_UNRESERVED = H_ALPHANUM | H_MARK;
  
      // reserved      = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" |
      //                 "$" | "," | "[" | "]"
      // Added per RFC2732: "[", "]"
      private static final long L_RESERVED = lowMask(";/?:@&=+$,[]");
      private static final long H_RESERVED = highMask(";/?:@&=+$,[]");
  
      // The zero'th bit is used to indicate that escape pairs and non-US-ASCII
      // characters are allowed; this is handled by the scanEscape method below.
      private static final long L_ESCAPED = 1L;
      private static final long H_ESCAPED = 0L;
  
      // uric          = reserved | unreserved | escaped
      private static final long L_URIC = L_RESERVED | L_UNRESERVED | L_ESCAPED;
      private static final long H_URIC = H_RESERVED | H_UNRESERVED | H_ESCAPED;
  
      // pchar         = unreserved | escaped |
      //                 ":" | "@" | "&" | "=" | "+" | "$" | ","
      private static final long L_PCHAR
          = L_UNRESERVED | L_ESCAPED | lowMask(":@&=+$,");
      private static final long H_PCHAR
          = H_UNRESERVED | H_ESCAPED | highMask(":@&=+$,");
  
      // All valid path characters
      private static final long L_PATH = L_PCHAR | lowMask(";/");
      private static final long H_PATH = H_PCHAR | highMask(";/");
  
      // Dash, for use in domainlabel and toplabel
      private static final long L_DASH = lowMask("-");
      private static final long H_DASH = highMask("-");
  
      // BEGIN Android-added: Allow underscore in hostname.
      // UNDERSCORE, for use in domainlabel and toplabel
      private static final long L_UNDERSCORE = lowMask("_");
      private static final long H_UNDERSCORE = highMask("_");
      // END Android-added: Allow underscore in hostname.
  
      // Dot, for use in hostnames
      private static final long L_DOT = lowMask(".");
      private static final long H_DOT = highMask(".");
  
      // userinfo      = *( unreserved | escaped |
      //                    ";" | ":" | "&" | "=" | "+" | "$" | "," )
      private static final long L_USERINFO
          = L_UNRESERVED | L_ESCAPED | lowMask(";:&=+$,");
      private static final long H_USERINFO
          = H_UNRESERVED | H_ESCAPED | highMask(";:&=+$,");
  
      // reg_name      = 1*( unreserved | escaped | "$" | "," |
      //                     ";" | ":" | "@" | "&" | "=" | "+" )
      private static final long L_REG_NAME
          = L_UNRESERVED | L_ESCAPED | lowMask("$,;:@&=+");
      private static final long H_REG_NAME
          = H_UNRESERVED | H_ESCAPED | highMask("$,;:@&=+");
  
      // All valid characters for server-based authorities
      private static final long L_SERVER
          = L_USERINFO | L_ALPHANUM | L_DASH | lowMask(".:@[]");
      private static final long H_SERVER
          = H_USERINFO | H_ALPHANUM | H_DASH | highMask(".:@[]");
  
      // Special case of server authority that represents an IPv6 address
      // In this case, a % does not signify an escape sequence
      private static final long L_SERVER_PERCENT
          = L_SERVER | lowMask("%");
      private static final long H_SERVER_PERCENT
          = H_SERVER | highMask("%");
      private static final long L_LEFT_BRACKET = lowMask("[");
      private static final long H_LEFT_BRACKET = highMask("[");
  
      // scheme        = alpha *( alpha | digit | "+" | "-" | "." )
      private static final long L_SCHEME = L_ALPHA | L_DIGIT | lowMask("+-.");
      private static final long H_SCHEME = H_ALPHA | H_DIGIT | highMask("+-.");
  
      // uric_no_slash = unreserved | escaped | ";" | "?" | ":" | "@" |
      //                 "&" | "=" | "+" | "$" | ","
      private static final long L_URIC_NO_SLASH
          = L_UNRESERVED | L_ESCAPED | lowMask(";?:@&=+$,");
      private static final long H_URIC_NO_SLASH
          = H_UNRESERVED | H_ESCAPED | highMask(";?:@&=+$,");
  
  
      // -- Escaping and encoding --
  
      private final static char[] hexDigits = {
          '0', '1', '2', '3', '4', '5', '6', '7',
          '8', '9', 'A', 'B', 'C', 'D', 'E', 'F'
      };
  
      private static void appendEscape(StringBuffer sb, byte b) {
          sb.append('%');
          sb.append(hexDigits[(b >> 4) & 0x0f]);
          sb.append(hexDigits[(b >> 0) & 0x0f]);
      }
  
      private static void appendEncoded(StringBuffer sb, char c) {
          ByteBuffer bb = null;
          try {
              bb = ThreadLocalCoders.encoderFor("UTF-8")
                  .encode(CharBuffer.wrap("" + c));
          } catch (CharacterCodingException x) {
              assert false;
          }
          while (bb.hasRemaining()) {
              int b = bb.get() & 0xff;
              if (b >= 0x80)
                  appendEscape(sb, (byte)b);
              else
                  sb.append((char)b);
          }
      }
  
      // Quote any characters in s that are not permitted
      // by the given mask pair
      //
      private static String quote(String s, long lowMask, long highMask) {
          int n = s.length();
          StringBuffer sb = null;
          boolean allowNonASCII = ((lowMask & L_ESCAPED) != 0);
          for (int i = 0; i < s.length(); i++) {
              char c = s.charAt(i);
              if (c < '\u0080') {
                  if (!match(c, lowMask, highMask)) {
                      if (sb == null) {
                          sb = new StringBuffer();
                          sb.append(s.substring(0, i));
                      }
                      appendEscape(sb, (byte)c);
                  } else {
                      if (sb != null)
                          sb.append(c);
                  }
              } else if (allowNonASCII
                         && (Character.isSpaceChar(c)
                             || Character.isISOControl(c))) {
                  if (sb == null) {
                      sb = new StringBuffer();
                      sb.append(s.substring(0, i));
                  }
                  appendEncoded(sb, c);
              } else {
                  if (sb != null)
                      sb.append(c);
              }
          }
          return (sb == null) ? s : sb.toString();
      }
  
      // Encodes all characters >= \u0080 into escaped, normalized UTF-8 octets,
      // assuming that s is otherwise legal
      //
      private static String encode(String s) {
          int n = s.length();
          if (n == 0)
              return s;
  
          // First check whether we actually need to encode
          for (int i = 0;;) {
              if (s.charAt(i) >= '\u0080')
                  break;
              if (++i >= n)
                  return s;
          }
  
          String ns = Normalizer.normalize(s, Normalizer.Form.NFC);
          ByteBuffer bb = null;
          try {
              bb = ThreadLocalCoders.encoderFor("UTF-8")
                  .encode(CharBuffer.wrap(ns));
          } catch (CharacterCodingException x) {
              assert false;
          }
  
          StringBuffer sb = new StringBuffer();
          while (bb.hasRemaining()) {
              int b = bb.get() & 0xff;
              if (b >= 0x80)
                  appendEscape(sb, (byte)b);
              else
                  sb.append((char)b);
          }
          return sb.toString();
      }
  
      private static int decode(char c) {
          if ((c >= '0') && (c <= '9'))
              return c - '0';
          if ((c >= 'a') && (c <= 'f'))
              return c - 'a' + 10;
          if ((c >= 'A') && (c <= 'F'))
              return c - 'A' + 10;
          assert false;
          return -1;
      }
  
      private static byte decode(char c1, char c2) {
          return (byte)(  ((decode(c1) & 0xf) << 4)
                        | ((decode(c2) & 0xf) << 0));
      }
  
      // Evaluates all escapes in s, applying UTF-8 decoding if needed.  Assumes
      // that escapes are well-formed syntactically, i.e., of the form %XX.  If a
      // sequence of escaped octets is not valid UTF-8 then the erroneous octets
      // are replaced with '\uFFFD'.
      // Exception: any "%" found between "[]" is left alone. It is an IPv6 literal
      //            with a scope_id
      //
      private static String decode(String s) {
          if (s == null)
              return s;
          int n = s.length();
          if (n == 0)
              return s;
          if (s.indexOf('%') < 0)
              return s;
  
          StringBuffer sb = new StringBuffer(n);
          ByteBuffer bb = ByteBuffer.allocate(n);
          CharBuffer cb = CharBuffer.allocate(n);
          CharsetDecoder dec = ThreadLocalCoders.decoderFor("UTF-8")
              .onMalformedInput(CodingErrorAction.REPLACE)
              .onUnmappableCharacter(CodingErrorAction.REPLACE);
  
          // This is not horribly efficient, but it will do for now
          char c = s.charAt(0);
          boolean betweenBrackets = false;
  
          for (int i = 0; i < n;) {
              assert c == s.charAt(i);    // Loop invariant
              if (c == '[') {
                  betweenBrackets = true;
              } else if (betweenBrackets && c == ']') {
                  betweenBrackets = false;
              }
              if (c != '%' || betweenBrackets) {
                  sb.append(c);
                  if (++i >= n)
                      break;
                  c = s.charAt(i);
                  continue;
              }
              bb.clear();
              int ui = i;
              for (;;) {
                  assert (n - i >= 2);
                  bb.put(decode(s.charAt(++i), s.charAt(++i)));
                  if (++i >= n)
                      break;
                  c = s.charAt(i);
                  if (c != '%')
                      break;
              }
              bb.flip();
              cb.clear();
              dec.reset();
              CoderResult cr = dec.decode(bb, cb, true);
              assert cr.isUnderflow();
              cr = dec.flush(cb);
              assert cr.isUnderflow();
              sb.append(cb.flip().toString());
          }
  
          return sb.toString();
      }
  
  
      // -- Parsing --
  
      // For convenience we wrap the input URI string in a new instance of the
      // following internal class.  This saves always having to pass the input
      // string as an argument to each internal scan/parse method.
  
      private class Parser {
  
          private String input;           // URI input string
          private boolean requireServerAuthority = false;
  
          Parser(String s) {
              input = s;
              string = s;
          }
  
          // -- Methods for throwing URISyntaxException in various ways --
  
          private void fail(String reason) throws URISyntaxException {
              throw new URISyntaxException(input, reason);
          }
  
          private void fail(String reason, int p) throws URISyntaxException {
              throw new URISyntaxException(input, reason, p);
          }
  
          private void failExpecting(String expected, int p)
              throws URISyntaxException
          {
              fail("Expected " + expected, p);
          }
  
          private void failExpecting(String expected, String prior, int p)
              throws URISyntaxException
          {
              fail("Expected " + expected + " following " + prior, p);
          }
  
  
          // -- Simple access to the input string --
  
          // Return a substring of the input string
          //
          private String substring(int start, int end) {
              return input.substring(start, end);
          }
  
          // Return the char at position p,
          // assuming that p < input.length()
          //
          private char charAt(int p) {
              return input.charAt(p);
          }
  
          // Tells whether start < end and, if so, whether charAt(start) == c
          //
          private boolean at(int start, int end, char c) {
              return (start < end) && (charAt(start) == c);
          }
  
          // Tells whether start + s.length() < end and, if so,
          // whether the chars at the start position match s exactly
          //
          private boolean at(int start, int end, String s) {
              int p = start;
              int sn = s.length();
              if (sn > end - p)
                  return false;
              int i = 0;
              while (i < sn) {
                  if (charAt(p++) != s.charAt(i)) {
                      break;
                  }
                  i++;
              }
              return (i == sn);
          }
  
  
          // -- Scanning --
  
          // The various scan and parse methods that follow use a uniform
          // convention of taking the current start position and end index as
          // their first two arguments.  The start is inclusive while the end is
          // exclusive, just as in the String class, i.e., a start/end pair
          // denotes the left-open interval [start, end) of the input string.
          //
          // These methods never proceed past the end position.  They may return
          // -1 to indicate outright failure, but more often they simply return
          // the position of the first char after the last char scanned.  Thus
          // a typical idiom is
          //
          //     int p = start;
          //     int q = scan(p, end, ...);
          //     if (q > p)
          //         // We scanned something
          //         ...;
          //     else if (q == p)
          //         // We scanned nothing
          //         ...;
          //     else if (q == -1)
          //         // Something went wrong
          //         ...;
  
  
          // Scan a specific char: If the char at the given start position is
          // equal to c, return the index of the next char; otherwise, return the
          // start position.
          //
          private int scan(int start, int end, char c) {
              if ((start < end) && (charAt(start) == c))
                  return start + 1;
              return start;
          }
  
          // Scan forward from the given start position.  Stop at the first char
          // in the err string (in which case -1 is returned), or the first char
          // in the stop string (in which case the index of the preceding char is
          // returned), or the end of the input string (in which case the length
          // of the input string is returned).  May return the start position if
          // nothing matches.
          //
          private int scan(int start, int end, String err, String stop) {
              int p = start;
              while (p < end) {
                  char c = charAt(p);
                  if (err.indexOf(c) >= 0)
                      return -1;
                  if (stop.indexOf(c) >= 0)
                      break;
                  p++;
              }
              return p;
          }
  
          // Scan a potential escape sequence, starting at the given position,
          // with the given first char (i.e., charAt(start) == c).
          //
          // This method assumes that if escapes are allowed then visible
          // non-US-ASCII chars are also allowed.
          //
          private int scanEscape(int start, int n, char first)
              throws URISyntaxException
          {
              int p = start;
              char c = first;
              if (c == '%') {
                  // Process escape pair
                  if ((p + 3 <= n)
                      && match(charAt(p + 1), L_HEX, H_HEX)
                      && match(charAt(p + 2), L_HEX, H_HEX)) {
                      return p + 3;
                  }
                  fail("Malformed escape pair", p);
              } else if ((c > 128)
                         && !Character.isSpaceChar(c)
                         && !Character.isISOControl(c)) {
                  // Allow unescaped but visible non-US-ASCII chars
                  return p + 1;
              }
              return p;
          }
  
          // Scan chars that match the given mask pair
          //
          private int scan(int start, int n, long lowMask, long highMask)
              throws URISyntaxException
          {
              int p = start;
              while (p < n) {
                  char c = charAt(p);
                  if (match(c, lowMask, highMask)) {
                      p++;
                      continue;
                  }
                  if ((lowMask & L_ESCAPED) != 0) {
                      int q = scanEscape(p, n, c);
                      if (q > p) {
                          p = q;
                          continue;
                      }
                  }
                  break;
              }
              return p;
          }
  
          // Check that each of the chars in [start, end) matches the given mask
          //
          private void checkChars(int start, int end,
                                  long lowMask, long highMask,
                                  String what)
              throws URISyntaxException
          {
              int p = scan(start, end, lowMask, highMask);
              if (p < end)
                  fail("Illegal character in " + what, p);
          }
  
          // Check that the char at position p matches the given mask
          //
          private void checkChar(int p,
                                 long lowMask, long highMask,
                                 String what)
              throws URISyntaxException
          {
              checkChars(p, p + 1, lowMask, highMask, what);
          }
  
  
          // -- Parsing --
  
          // [<scheme>:]<scheme-specific-part>[#<fragment>]
          //
          void parse(boolean rsa) throws URISyntaxException {
              requireServerAuthority = rsa;
              int ssp;                    // Start of scheme-specific part
              int n = input.length();
              int p = scan(0, n, "/?#", ":");
              if ((p >= 0) && at(p, n, ':')) {
                  if (p == 0)
                      failExpecting("scheme name", 0);
                  checkChar(0, L_ALPHA, H_ALPHA, "scheme name");
                  checkChars(1, p, L_SCHEME, H_SCHEME, "scheme name");
                  scheme = substring(0, p);
                  p++;                    // Skip ':'
                  ssp = p;
                  if (at(p, n, '/')) {
                      p = parseHierarchical(p, n);
                  } else {
                      int q = scan(p, n, "", "#");
                      if (q <= p)
                          failExpecting("scheme-specific part", p);
                      checkChars(p, q, L_URIC, H_URIC, "opaque part");
                      p = q;
                  }
              } else {
                  ssp = 0;
                  p = parseHierarchical(0, n);
              }
              schemeSpecificPart = substring(ssp, p);
              if (at(p, n, '#')) {
                  checkChars(p + 1, n, L_URIC, H_URIC, "fragment");
                  fragment = substring(p + 1, n);
                  p = n;
              }
              if (p < n)
                  fail("end of URI", p);
          }
  
          // [//authority]<path>[?<query>]
          //
          // DEVIATION from RFC2396: We allow an empty authority component as
          // long as it's followed by a non-empty path, query component, or
          // fragment component.  This is so that URIs such as "file:///foo/bar"
          // will parse.  This seems to be the intent of RFC2396, though the
          // grammar does not permit it.  If the authority is empty then the
          // userInfo, host, and port components are undefined.
          //
          // DEVIATION from RFC2396: We allow empty relative paths.  This seems
          // to be the intent of RFC2396, but the grammar does not permit it.
          // The primary consequence of this deviation is that "#f" parses as a
          // relative URI with an empty path.
          //
          private int parseHierarchical(int start, int n)
              throws URISyntaxException
          {
              int p = start;
              if (at(p, n, '/') && at(p + 1, n, '/')) {
                  p += 2;
                  int q = scan(p, n, "", "/?#");
                  if (q > p) {
                      p = parseAuthority(p, q);
                  } else if (q < n) {
                      // DEVIATION: Allow empty authority prior to non-empty
                      // path, query component or fragment identifier
                  } else
                      failExpecting("authority", p);
              }
              int q = scan(p, n, "", "?#"); // DEVIATION: May be empty
              checkChars(p, q, L_PATH, H_PATH, "path");
              path = substring(p, q);
              p = q;
              if (at(p, n, '?')) {
                  p++;
                  q = scan(p, n, "", "#");
                  checkChars(p, q, L_URIC, H_URIC, "query");
                  query = substring(p, q);
                  p = q;
              }
              return p;
          }
  
          // authority     = server | reg_name
          //
          // Ambiguity: An authority that is a registry name rather than a server
          // might have a prefix that parses as a server.  We use the fact that
          // the authority component is always followed by '/' or the end of the
          // input string to resolve this: If the complete authority did not
          // parse as a server then we try to parse it as a registry name.
          //
          private int parseAuthority(int start, int n)
              throws URISyntaxException
          {
              int p = start;
              int q = p;
              URISyntaxException ex = null;
  
              boolean serverChars;
              boolean regChars;
  
              if (scan(p, n, "", "]") > p) {
                  // contains a literal IPv6 address, therefore % is allowed
                  serverChars = (scan(p, n, L_SERVER_PERCENT, H_SERVER_PERCENT) == n);
              } else {
                  serverChars = (scan(p, n, L_SERVER, H_SERVER) == n);
              }
              regChars = (scan(p, n, L_REG_NAME, H_REG_NAME) == n);
  
              if (regChars && !serverChars) {
                  // Must be a registry-based authority
                  authority = substring(p, n);
                  return n;
              }
  
              if (serverChars) {
                  // Might be (probably is) a server-based authority, so attempt
                  // to parse it as such.  If the attempt fails, try to treat it
                  // as a registry-based authority.
                  try {
                      q = parseServer(p, n);
                      if (q < n)
                          failExpecting("end of authority", q);
                      authority = substring(p, n);
                  } catch (URISyntaxException x) {
                      // Undo results of failed parse
                      userInfo = null;
                      host = null;
                      port = -1;
                      if (requireServerAuthority) {
                          // If we're insisting upon a server-based authority,
                          // then just re-throw the exception
                          throw x;
                      } else {
                          // Save the exception in case it doesn't parse as a
                          // registry either
                          ex = x;
                          q = p;
                      }
                  }
              }
  
              if (q < n) {
                  if (regChars) {
                      // Registry-based authority
                      authority = substring(p, n);
                  } else if (ex != null) {
                      // Re-throw exception; it was probably due to
                      // a malformed IPv6 address
                      throw ex;
                  } else {
                      fail("Illegal character in authority", q);
                  }
              }
  
              return n;
          }
  
  
          // [<userinfo>@]<host>[:<port>]
          //
          private int parseServer(int start, int n)
              throws URISyntaxException
          {
              int p = start;
              int q;
  
              // userinfo
              q = scan(p, n, "/?#", "@");
              if ((q >= p) && at(q, n, '@')) {
                  checkChars(p, q, L_USERINFO, H_USERINFO, "user info");
                  userInfo = substring(p, q);
                  p = q + 1;              // Skip '@'
              }
  
              // hostname, IPv4 address, or IPv6 address
              if (at(p, n, '[')) {
                  // DEVIATION from RFC2396: Support IPv6 addresses, per RFC2732
                  p++;
                  q = scan(p, n, "/?#", "]");
                  if ((q > p) && at(q, n, ']')) {
                      // look for a "%" scope id
                      int r = scan (p, q, "", "%");
                      if (r > p) {
                          parseIPv6Reference(p, r);
                          if (r+1 == q) {
                              fail ("scope id expected");
                          }
                          checkChars (r+1, q, L_ALPHANUM, H_ALPHANUM,
                                                  "scope id");
                      } else {
                          parseIPv6Reference(p, q);
                      }
                      host = substring(p-1, q+1);
                      p = q + 1;
                  } else {
                      failExpecting("closing bracket for IPv6 address", q);
                  }
              } else {
                  q = parseIPv4Address(p, n);
                  if (q <= p)
                      q = parseHostname(p, n);
                  p = q;
              }
  
              // port
              if (at(p, n, ':')) {
                  p++;
                  q = scan(p, n, "", "/");
                  if (q > p) {
                      checkChars(p, q, L_DIGIT, H_DIGIT, "port number");
                      try {
                          port = Integer.parseInt(substring(p, q));
                      } catch (NumberFormatException x) {
                          fail("Malformed port number", p);
                      }
                      p = q;
                  }
              }
              if (p < n)
                  failExpecting("port number", p);
  
              return p;
          }
  
          // Scan a string of decimal digits whose value fits in a byte
          //
          private int scanByte(int start, int n)
              throws URISyntaxException
          {
              int p = start;
              int q = scan(p, n, L_DIGIT, H_DIGIT);
              if (q <= p) return q;
              if (Integer.parseInt(substring(p, q)) > 255) return p;
              return q;
          }
  
          // Scan an IPv4 address.
          //
          // If the strict argument is true then we require that the given
          // interval contain nothing besides an IPv4 address; if it is false
          // then we only require that it start with an IPv4 address.
          //
          // If the interval does not contain or start with (depending upon the
          // strict argument) a legal IPv4 address characters then we return -1
          // immediately; otherwise we insist that these characters parse as a
          // legal IPv4 address and throw an exception on failure.
          //
          // We assume that any string of decimal digits and dots must be an IPv4
          // address.  It won't parse as a hostname anyway, so making that
          // assumption here allows more meaningful exceptions to be thrown.
          //
          private int scanIPv4Address(int start, int n, boolean strict)
              throws URISyntaxException
          {
              int p = start;
              int q;
              int m = scan(p, n, L_DIGIT | L_DOT, H_DIGIT | H_DOT);
              if ((m <= p) || (strict && (m != n)))
                  return -1;
              for (;;) {
                  // Per RFC2732: At most three digits per byte
                  // Further constraint: Each element fits in a byte
                  if ((q = scanByte(p, m)) <= p) break;   p = q;
                  if ((q = scan(p, m, '.')) <= p) break;  p = q;
                  if ((q = scanByte(p, m)) <= p) break;   p = q;
                  if ((q = scan(p, m, '.')) <= p) break;  p = q;
                  if ((q = scanByte(p, m)) <= p) break;   p = q;
                  if ((q = scan(p, m, '.')) <= p) break;  p = q;
                  if ((q = scanByte(p, m)) <= p) break;   p = q;
                  if (q < m) break;
                  return q;
              }
              fail("Malformed IPv4 address", q);
              return -1;
          }
  
          // Take an IPv4 address: Throw an exception if the given interval
          // contains anything except an IPv4 address
          //
          private int takeIPv4Address(int start, int n, String expected)
              throws URISyntaxException
          {
              int p = scanIPv4Address(start, n, true);
              if (p <= start)
                  failExpecting(expected, start);
              return p;
          }
  
          // Attempt to parse an IPv4 address, returning -1 on failure but
          // allowing the given interval to contain [:<characters>] after
          // the IPv4 address.
          //
          private int parseIPv4Address(int start, int n) {
              int p;
  
              try {
                  p = scanIPv4Address(start, n, false);
              } catch (URISyntaxException x) {
                  return -1;
              } catch (NumberFormatException nfe) {
                  return -1;
              }
  
              if (p > start && p < n) {
                  // IPv4 address is followed by something - check that
                  // it's a ":" as this is the only valid character to
                  // follow an address.
                  if (charAt(p) != ':') {
                      p = -1;
                  }
              }
  
              if (p > start)
                  host = substring(start, p);
  
              return p;
          }
  
          // Android-changed: Allow underscore in hostname.
          // Added "_" to the grammars for domainLabel and topLabel.
          // hostname      = domainlabel [ "." ] | 1*( domainlabel "." ) toplabel [ "." ]
          // domainlabel   = alphanum | alphanum *( alphanum | "-" | "_" ) alphanum
          // toplabel      = alpha | alpha *( alphanum | "-" | "_" ) alphanum
          //
          private int parseHostname(int start, int n)
              throws URISyntaxException
          {
              int p = start;
              int q;
              int l = -1;                 // Start of last parsed label
  
              do {
                  // Android-changed: Allow underscore in hostname.
                  // RFC 2396 only allows alphanumeric characters and hyphens, but real,
                  // large Internet hosts in the wild use underscore, so we have to allow it.
                  // http://code.google.com/p/android/issues/detail?id=37577
                  // http://b/17579865
                  // http://b/18016625
                  // http://b/18023709
  
                  // domainlabel = alphanum [ *( alphanum | "-" | "_" ) alphanum ]
                  q = scan(p, n, L_ALPHANUM, H_ALPHANUM);
                  if (q <= p)
                      break;
                  l = p;
                  if (q > p) {
                      p = q;
                      // Android-changed: Allow underscore in hostname.
                      // q = scan(p, n, L_ALPHANUM | L_DASH, H_ALPHANUM | H_DASH);
                      q = scan(p, n, L_ALPHANUM | L_DASH | L_UNDERSCORE, H_ALPHANUM | H_DASH | H_UNDERSCORE);
                      if (q > p) {
                          if (charAt(q - 1) == '-')
                              fail("Illegal character in hostname", q - 1);
                          p = q;
                      }
                  }
                  q = scan(p, n, '.');
                  if (q <= p)
                      break;
                  p = q;
              } while (p < n);
  
              if ((p < n) && !at(p, n, ':'))
                  fail("Illegal character in hostname", p);
  
              if (l < 0)
                  failExpecting("hostname", start);
  
              // for a fully qualified hostname check that the rightmost
              // label starts with an alpha character.
              if (l > start && !match(charAt(l), L_ALPHA, H_ALPHA)) {
                  fail("Illegal character in hostname", l);
              }
  
              host = substring(start, p);
              return p;
          }
  
  
          // IPv6 address parsing, from RFC2373: IPv6 Addressing Architecture
          //
          // Bug: The grammar in RFC2373 Appendix B does not allow addresses of
          // the form ::12.34.56.78, which are clearly shown in the examples
          // earlier in the document.  Here is the original grammar:
          //
          //   IPv6address = hexpart [ ":" IPv4address ]
          //   hexpart     = hexseq | hexseq "::" [ hexseq ] | "::" [ hexseq ]
          //   hexseq      = hex4 *( ":" hex4)
          //   hex4        = 1*4HEXDIG
          //
          // We therefore use the following revised grammar:
          //
          //   IPv6address = hexseq [ ":" IPv4address ]
          //                 | hexseq [ "::" [ hexpost ] ]
          //                 | "::" [ hexpost ]
          //   hexpost     = hexseq | hexseq ":" IPv4address | IPv4address
          //   hexseq      = hex4 *( ":" hex4)
          //   hex4        = 1*4HEXDIG
          //
          // This covers all and only the following cases:
          //
          //   hexseq
          //   hexseq : IPv4address
          //   hexseq ::
          //   hexseq :: hexseq
          //   hexseq :: hexseq : IPv4address
          //   hexseq :: IPv4address
          //   :: hexseq
          //   :: hexseq : IPv4address
          //   :: IPv4address
          //   ::
          //
          // Additionally we constrain the IPv6 address as follows :-
          //
          //  i.  IPv6 addresses without compressed zeros should contain
          //      exactly 16 bytes.
          //
          //  ii. IPv6 addresses with compressed zeros should contain
          //      less than 16 bytes.
  
          private int ipv6byteCount = 0;
  
          private int parseIPv6Reference(int start, int n)
              throws URISyntaxException
          {
              int p = start;
              int q;
              boolean compressedZeros = false;
  
              q = scanHexSeq(p, n);
  
              if (q > p) {
                  p = q;
                  if (at(p, n, "::")) {
                      compressedZeros = true;
                      p = scanHexPost(p + 2, n);
                  } else if (at(p, n, ':')) {
                      p = takeIPv4Address(p + 1,  n, "IPv4 address");
                      ipv6byteCount += 4;
                  }
              } else if (at(p, n, "::")) {
                  compressedZeros = true;
                  p = scanHexPost(p + 2, n);
              }
              if (p < n)
                  fail("Malformed IPv6 address", start);
              if (ipv6byteCount > 16)
                  fail("IPv6 address too long", start);
              if (!compressedZeros && ipv6byteCount < 16)
                  fail("IPv6 address too short", start);
              if (compressedZeros && ipv6byteCount == 16)
                  fail("Malformed IPv6 address", start);
  
              return p;
          }
  
          private int scanHexPost(int start, int n)
              throws URISyntaxException
          {
              int p = start;
              int q;
  
              if (p == n)
                  return p;
  
              q = scanHexSeq(p, n);
              if (q > p) {
                  p = q;
                  if (at(p, n, ':')) {
                      p++;
                      p = takeIPv4Address(p, n, "hex digits or IPv4 address");
                      ipv6byteCount += 4;
                  }
              } else {
                  p = takeIPv4Address(p, n, "hex digits or IPv4 address");
                  ipv6byteCount += 4;
              }
              return p;
          }
  
          // Scan a hex sequence; return -1 if one could not be scanned
          //
          private int scanHexSeq(int start, int n)
              throws URISyntaxException
          {
              int p = start;
              int q;
  
              q = scan(p, n, L_HEX, H_HEX);
              if (q <= p)
                  return -1;
              if (at(q, n, '.'))          // Beginning of IPv4 address
                  return -1;
              if (q > p + 4)
                  fail("IPv6 hexadecimal digit sequence too long", p);
              ipv6byteCount += 2;
              p = q;
              while (p < n) {
                  if (!at(p, n, ':'))
                      break;
                  if (at(p + 1, n, ':'))
                      break;              // "::"
                  p++;
                  q = scan(p, n, L_HEX, H_HEX);
                  if (q <= p)
                      failExpecting("digits for an IPv6 address", p);
                  if (at(q, n, '.')) {    // Beginning of IPv4 address
                      p--;
                      break;
                  }
                  if (q > p + 4)
                      fail("IPv6 hexadecimal digit sequence too long", p);
                  ipv6byteCount += 2;
                  p = q;
              }
  
              return p;
          }
  
      }
  
  }
  