History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/net/URI.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/net/URI.java+3524−0
@@ -0,0 +1,3524 @@
1+/*
2+ * Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.net;
27+
28+import java.io.IOException;
29+import java.io.InvalidObjectException;
30+import java.io.ObjectInputStream;
31+import java.io.ObjectOutputStream;
32+import java.io.Serializable;
33+import java.nio.ByteBuffer;
34+import java.nio.CharBuffer;
35+import java.nio.charset.CharsetDecoder;
36+import java.nio.charset.CharsetEncoder;
37+import java.nio.charset.CoderResult;
38+import java.nio.charset.CodingErrorAction;
39+import java.nio.charset.CharacterCodingException;
40+import java.text.Normalizer;
41+import sun.nio.cs.ThreadLocalCoders;
42+
43+import java.lang.Character; // for javadoc
44+import java.lang.NullPointerException; // for javadoc
45+
46+
47+/**
48+ * Represents a Uniform Resource Identifier (URI) reference.
49+ *
50+ * <p> Aside from some minor deviations noted below, an instance of this
51+ * class represents a URI reference as defined by
52+ * <a href="http://www.ietf.org/rfc/rfc2396.txt"><i>RFC&nbsp;2396: Uniform
53+ * Resource Identifiers (URI): Generic Syntax</i></a>, amended by <a
54+ * href="http://www.ietf.org/rfc/rfc2732.txt"><i>RFC&nbsp;2732: Format for
55+ * Literal IPv6 Addresses in URLs</i></a>. The Literal IPv6 address format
56+ * also supports scope_ids. The syntax and usage of scope_ids is described
57+ * <a href="Inet6Address.html#scoped">here</a>.
58+ * This class provides constructors for creating URI instances from
59+ * their components or by parsing their string forms, methods for accessing the
60+ * various components of an instance, and methods for normalizing, resolving,
61+ * and relativizing URI instances. Instances of this class are immutable.
62+ *
63+ *
64+ * <h4> URI syntax and components </h4>
65+ *
66+ * At the highest level a URI reference (hereinafter simply "URI") in string
67+ * form has the syntax
68+ *
69+ * <blockquote>
70+ * [<i>scheme</i><tt><b>:</b></tt><i></i>]<i>scheme-specific-part</i>[<tt><b>#</b></tt><i>fragment</i>]
71+ * </blockquote>
72+ *
73+ * where square brackets [...] delineate optional components and the characters
74+ * <tt><b>:</b></tt> and <tt><b>#</b></tt> stand for themselves.
75+ *
76+ * <p> An <i>absolute</i> URI specifies a scheme; a URI that is not absolute is
77+ * said to be <i>relative</i>. URIs are also classified according to whether
78+ * they are <i>opaque</i> or <i>hierarchical</i>.
79+ *
80+ * <p> An <i>opaque</i> URI is an absolute URI whose scheme-specific part does
81+ * not begin with a slash character (<tt>'/'</tt>). Opaque URIs are not
82+ * subject to further parsing. Some examples of opaque URIs are:
83+ *
84+ * <blockquote><table cellpadding=0 cellspacing=0 summary="layout">
85+ * <tr><td><tt>mailto:java-net@java.sun.com</tt><td></tr>
86+ * <tr><td><tt>news:comp.lang.java</tt><td></tr>
87+ * <tr><td><tt>urn:isbn:096139210x</tt></td></tr>
88+ * </table></blockquote>
89+ *
90+ * <p> A <i>hierarchical</i> URI is either an absolute URI whose
91+ * scheme-specific part begins with a slash character, or a relative URI, that
92+ * is, a URI that does not specify a scheme. Some examples of hierarchical
93+ * URIs are:
94+ *
95+ * <blockquote>
96+ * <tt>http://java.sun.com/j2se/1.3/</tt><br>
97+ * <tt>docs/guide/collections/designfaq.html#28</tt><br>
98+ * <tt>../../../demo/jfc/SwingSet2/src/SwingSet2.java</tt><br>
99+ * <tt>file:///~/calendar</tt>
100+ * </blockquote>
101+ *
102+ * <p> A hierarchical URI is subject to further parsing according to the syntax
103+ *
104+ * <blockquote>
105+ * [<i>scheme</i><tt><b>:</b></tt>][<tt><b>//</b></tt><i>authority</i>][<i>path</i>][<tt><b>?</b></tt><i>query</i>][<tt><b>#</b></tt><i>fragment</i>]
106+ * </blockquote>
107+ *
108+ * where the characters <tt><b>:</b></tt>, <tt><b>/</b></tt>,
109+ * <tt><b>?</b></tt>, and <tt><b>#</b></tt> stand for themselves. The
110+ * scheme-specific part of a hierarchical URI consists of the characters
111+ * between the scheme and fragment components.
112+ *
113+ * <p> The authority component of a hierarchical URI is, if specified, either
114+ * <i>server-based</i> or <i>registry-based</i>. A server-based authority
115+ * parses according to the familiar syntax
116+ *
117+ * <blockquote>
118+ * [<i>user-info</i><tt><b>@</b></tt>]<i>host</i>[<tt><b>:</b></tt><i>port</i>]
119+ * </blockquote>
120+ *
121+ * where the characters <tt><b>@</b></tt> and <tt><b>:</b></tt> stand for
122+ * themselves. Nearly all URI schemes currently in use are server-based. An
123+ * authority component that does not parse in this way is considered to be
124+ * registry-based.
125+ *
126+ * <p> The path component of a hierarchical URI is itself said to be absolute
127+ * if it begins with a slash character (<tt>'/'</tt>); otherwise it is
128+ * relative. The path of a hierarchical URI that is either absolute or
129+ * specifies an authority is always absolute.
130+ *
131+ * <p> All told, then, a URI instance has the following nine components:
132+ *
133+ * <blockquote><table summary="Describes the components of a URI:scheme,scheme-specific-part,authority,user-info,host,port,path,query,fragment">
134+ * <tr><th><i>Component</i></th><th><i>Type</i></th></tr>
135+ * <tr><td>scheme</td><td><tt>String</tt></td></tr>
136+ * <tr><td>scheme-specific-part&nbsp;&nbsp;&nbsp;&nbsp;</td><td><tt>String</tt></td></tr>
137+ * <tr><td>authority</td><td><tt>String</tt></td></tr>
138+ * <tr><td>user-info</td><td><tt>String</tt></td></tr>
139+ * <tr><td>host</td><td><tt>String</tt></td></tr>
140+ * <tr><td>port</td><td><tt>int</tt></td></tr>
141+ * <tr><td>path</td><td><tt>String</tt></td></tr>
142+ * <tr><td>query</td><td><tt>String</tt></td></tr>
143+ * <tr><td>fragment</td><td><tt>String</tt></td></tr>
144+ * </table></blockquote>
145+ *
146+ * In a given instance any particular component is either <i>undefined</i> or
147+ * <i>defined</i> with a distinct value. Undefined string components are
148+ * represented by <tt>null</tt>, while undefined integer components are
149+ * represented by <tt>-1</tt>. A string component may be defined to have the
150+ * empty string as its value; this is not equivalent to that component being
151+ * undefined.
152+ *
153+ * <p> Whether a particular component is or is not defined in an instance
154+ * depends upon the type of the URI being represented. An absolute URI has a
155+ * scheme component. An opaque URI has a scheme, a scheme-specific part, and
156+ * possibly a fragment, but has no other components. A hierarchical URI always
157+ * has a path (though it may be empty) and a scheme-specific-part (which at
158+ * least contains the path), and may have any of the other components. If the
159+ * authority component is present and is server-based then the host component
160+ * will be defined and the user-information and port components may be defined.
161+ *
162+ *
163+ * <h4> Operations on URI instances </h4>
164+ *
165+ * The key operations supported by this class are those of
166+ * <i>normalization</i>, <i>resolution</i>, and <i>relativization</i>.
167+ *
168+ * <p> <i>Normalization</i> is the process of removing unnecessary <tt>"."</tt>
169+ * and <tt>".."</tt> segments from the path component of a hierarchical URI.
170+ * Each <tt>"."</tt> segment is simply removed. A <tt>".."</tt> segment is
171+ * removed only if it is preceded by a non-<tt>".."</tt> segment.
172+ * Normalization has no effect upon opaque URIs.
173+ *
174+ * <p> <i>Resolution</i> is the process of resolving one URI against another,
175+ * <i>base</i> URI. The resulting URI is constructed from components of both
176+ * URIs in the manner specified by RFC&nbsp;2396, taking components from the
177+ * base URI for those not specified in the original. For hierarchical URIs,
178+ * the path of the original is resolved against the path of the base and then
179+ * normalized. The result, for example, of resolving
180+ *
181+ * <blockquote>
182+ * <tt>docs/guide/collections/designfaq.html#28&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt>(1)
183+ * </blockquote>
184+ *
185+ * against the base URI <tt>http://java.sun.com/j2se/1.3/</tt> is the result
186+ * URI
187+ *
188+ * <blockquote>
189+ * <tt>http://java.sun.com/j2se/1.3/docs/guide/collections/designfaq.html#28</tt>
190+ * </blockquote>
191+ *
192+ * Resolving the relative URI
193+ *
194+ * <blockquote>
195+ * <tt>../../../demo/jfc/SwingSet2/src/SwingSet2.java&nbsp;&nbsp;&nbsp;&nbsp;</tt>(2)
196+ * </blockquote>
197+ *
198+ * against this result yields, in turn,
199+ *
200+ * <blockquote>
201+ * <tt>http://java.sun.com/j2se/1.3/demo/jfc/SwingSet2/src/SwingSet2.java</tt>
202+ * </blockquote>
203+ *
204+ * Resolution of both absolute and relative URIs, and of both absolute and
205+ * relative paths in the case of hierarchical URIs, is supported. Resolving
206+ * the URI <tt>file:///~calendar</tt> against any other URI simply yields the
207+ * original URI, since it is absolute. Resolving the relative URI (2) above
208+ * against the relative base URI (1) yields the normalized, but still relative,
209+ * URI
210+ *
211+ * <blockquote>
212+ * <tt>demo/jfc/SwingSet2/src/SwingSet2.java</tt>
213+ * </blockquote>
214+ *
215+ * <p> <i>Relativization</i>, finally, is the inverse of resolution: For any
216+ * two normalized URIs <i>u</i> and&nbsp;<i>v</i>,
217+ *
218+ * <blockquote>
219+ * <i>u</i><tt>.relativize(</tt><i>u</i><tt>.resolve(</tt><i>v</i><tt>)).equals(</tt><i>v</i><tt>)</tt>&nbsp;&nbsp;and<br>
220+ * <i>u</i><tt>.resolve(</tt><i>u</i><tt>.relativize(</tt><i>v</i><tt>)).equals(</tt><i>v</i><tt>)</tt>&nbsp;&nbsp;.<br>
221+ * </blockquote>
222+ *
223+ * This operation is often useful when constructing a document containing URIs
224+ * that must be made relative to the base URI of the document wherever
225+ * possible. For example, relativizing the URI
226+ *
227+ * <blockquote>
228+ * <tt>http://java.sun.com/j2se/1.3/docs/guide/index.html</tt>
229+ * </blockquote>
230+ *
231+ * against the base URI
232+ *
233+ * <blockquote>
234+ * <tt>http://java.sun.com/j2se/1.3</tt>
235+ * </blockquote>
236+ *
237+ * yields the relative URI <tt>docs/guide/index.html</tt>.
238+ *
239+ *
240+ * <h4> Character categories </h4>
241+ *
242+ * RFC&nbsp;2396 specifies precisely which characters are permitted in the
243+ * various components of a URI reference. The following categories, most of
244+ * which are taken from that specification, are used below to describe these
245+ * constraints:
246+ *
247+ * <blockquote><table cellspacing=2 summary="Describes categories alpha,digit,alphanum,unreserved,punct,reserved,escaped,and other">
248+ * <tr><th valign=top><i>alpha</i></th>
249+ * <td>The US-ASCII alphabetic characters,
250+ * <tt>'A'</tt>&nbsp;through&nbsp;<tt>'Z'</tt>
251+ * and <tt>'a'</tt>&nbsp;through&nbsp;<tt>'z'</tt></td></tr>
252+ * <tr><th valign=top><i>digit</i></th>
253+ * <td>The US-ASCII decimal digit characters,
254+ * <tt>'0'</tt>&nbsp;through&nbsp;<tt>'9'</tt></td></tr>
255+ * <tr><th valign=top><i>alphanum</i></th>
256+ * <td>All <i>alpha</i> and <i>digit</i> characters</td></tr>
257+ * <tr><th valign=top><i>unreserved</i>&nbsp;&nbsp;&nbsp;&nbsp;</th>
258+ * <td>All <i>alphanum</i> characters together with those in the string
259+ * <tt>"_-!.~'()*"</tt></td></tr>
260+ * <tr><th valign=top><i>punct</i></th>
261+ * <td>The characters in the string <tt>",;:$&+="</tt></td></tr>
262+ * <tr><th valign=top><i>reserved</i></th>
263+ * <td>All <i>punct</i> characters together with those in the string
264+ * <tt>"?/[]@"</tt></td></tr>
265+ * <tr><th valign=top><i>escaped</i></th>
266+ * <td>Escaped octets, that is, triplets consisting of the percent
267+ * character (<tt>'%'</tt>) followed by two hexadecimal digits
268+ * (<tt>'0'</tt>-<tt>'9'</tt>, <tt>'A'</tt>-<tt>'F'</tt>, and
269+ * <tt>'a'</tt>-<tt>'f'</tt>)</td></tr>
270+ * <tr><th valign=top><i>other</i></th>
271+ * <td>The Unicode characters that are not in the US-ASCII character set,
272+ * are not control characters (according to the {@link
273+ * java.lang.Character#isISOControl(char) Character.isISOControl}
274+ * method), and are not space characters (according to the {@link
275+ * java.lang.Character#isSpaceChar(char) Character.isSpaceChar}
276+ * method)&nbsp;&nbsp;<i>(<b>Deviation from RFC 2396</b>, which is
277+ * limited to US-ASCII)</i></td></tr>
278+ * </table></blockquote>
279+ *
280+ * <p><a name="legal-chars"></a> The set of all legal URI characters consists of
281+ * the <i>unreserved</i>, <i>reserved</i>, <i>escaped</i>, and <i>other</i>
282+ * characters.
283+ *
284+ *
285+ * <h4> Escaped octets, quotation, encoding, and decoding </h4>
286+ *
287+ * RFC 2396 allows escaped octets to appear in the user-info, path, query, and
288+ * fragment components. Escaping serves two purposes in URIs:
289+ *
290+ * <ul>
291+ *
292+ * <li><p> To <i>encode</i> non-US-ASCII characters when a URI is required to
293+ * conform strictly to RFC&nbsp;2396 by not containing any <i>other</i>
294+ * characters. </p></li>
295+ *
296+ * <li><p> To <i>quote</i> characters that are otherwise illegal in a
297+ * component. The user-info, path, query, and fragment components differ
298+ * slightly in terms of which characters are considered legal and illegal.
299+ * </p></li>
300+ *
301+ * </ul>
302+ *
303+ * These purposes are served in this class by three related operations:
304+ *
305+ * <ul>
306+ *
307+ * <li><p><a name="encode"></a> A character is <i>encoded</i> by replacing it
308+ * with the sequence of escaped octets that represent that character in the
309+ * UTF-8 character set. The Euro currency symbol (<tt>'&#92;u20AC'</tt>),
310+ * for example, is encoded as <tt>"%E2%82%AC"</tt>. <i>(<b>Deviation from
311+ * RFC&nbsp;2396</b>, which does not specify any particular character
312+ * set.)</i> </p></li>
313+ *
314+ * <li><p><a name="quote"></a> An illegal character is <i>quoted</i> simply by
315+ * encoding it. The space character, for example, is quoted by replacing it
316+ * with <tt>"%20"</tt>. UTF-8 contains US-ASCII, hence for US-ASCII
317+ * characters this transformation has exactly the effect required by
318+ * RFC&nbsp;2396. </p></li>
319+ *
320+ * <li><p><a name="decode"></a>
321+ * A sequence of escaped octets is <i>decoded</i> by
322+ * replacing it with the sequence of characters that it represents in the
323+ * UTF-8 character set. UTF-8 contains US-ASCII, hence decoding has the
324+ * effect of de-quoting any quoted US-ASCII characters as well as that of
325+ * decoding any encoded non-US-ASCII characters. If a <a
326+ * href="../nio/charset/CharsetDecoder.html#ce">decoding error</a> occurs
327+ * when decoding the escaped octets then the erroneous octets are replaced by
328+ * <tt>'&#92;uFFFD'</tt>, the Unicode replacement character. </p></li>
329+ *
330+ * </ul>
331+ *
332+ * These operations are exposed in the constructors and methods of this class
333+ * as follows:
334+ *
335+ * <ul>
336+ *
337+ * <li><p> The {@link #URI(java.lang.String) <code>single-argument
338+ * constructor</code>} requires any illegal characters in its argument to be
339+ * quoted and preserves any escaped octets and <i>other</i> characters that
340+ * are present. </p></li>
341+ *
342+ * <li><p> The {@link
343+ * #URI(java.lang.String,java.lang.String,java.lang.String,int,java.lang.String,java.lang.String,java.lang.String)
344+ * <code>multi-argument constructors</code>} quote illegal characters as
345+ * required by the components in which they appear. The percent character
346+ * (<tt>'%'</tt>) is always quoted by these constructors. Any <i>other</i>
347+ * characters are preserved. </p></li>
348+ *
349+ * <li><p> The {@link #getRawUserInfo() getRawUserInfo}, {@link #getRawPath()
350+ * getRawPath}, {@link #getRawQuery() getRawQuery}, {@link #getRawFragment()
351+ * getRawFragment}, {@link #getRawAuthority() getRawAuthority}, and {@link
352+ * #getRawSchemeSpecificPart() getRawSchemeSpecificPart} methods return the
353+ * values of their corresponding components in raw form, without interpreting
354+ * any escaped octets. The strings returned by these methods may contain
355+ * both escaped octets and <i>other</i> characters, and will not contain any
356+ * illegal characters. </p></li>
357+ *
358+ * <li><p> The {@link #getUserInfo() getUserInfo}, {@link #getPath()
359+ * getPath}, {@link #getQuery() getQuery}, {@link #getFragment()
360+ * getFragment}, {@link #getAuthority() getAuthority}, and {@link
361+ * #getSchemeSpecificPart() getSchemeSpecificPart} methods decode any escaped
362+ * octets in their corresponding components. The strings returned by these
363+ * methods may contain both <i>other</i> characters and illegal characters,
364+ * and will not contain any escaped octets. </p></li>
365+ *
366+ * <li><p> The {@link #toString() toString} method returns a URI string with
367+ * all necessary quotation but which may contain <i>other</i> characters.
368+ * </p></li>
369+ *
370+ * <li><p> The {@link #toASCIIString() toASCIIString} method returns a fully
371+ * quoted and encoded URI string that does not contain any <i>other</i>
372+ * characters. </p></li>
373+ *
374+ * </ul>
375+ *
376+ *
377+ * <h4> Identities </h4>
378+ *
379+ * For any URI <i>u</i>, it is always the case that
380+ *
381+ * <blockquote>
382+ * <tt>new URI(</tt><i>u</i><tt>.toString()).equals(</tt><i>u</i><tt>)</tt>&nbsp;.
383+ * </blockquote>
384+ *
385+ * For any URI <i>u</i> that does not contain redundant syntax such as two
386+ * slashes before an empty authority (as in <tt>file:///tmp/</tt>&nbsp;) or a
387+ * colon following a host name but no port (as in
388+ * <tt>http://java.sun.com:</tt>&nbsp;), and that does not encode characters
389+ * except those that must be quoted, the following identities also hold:
390+ *
391+ * <blockquote>
392+ * <tt>new URI(</tt><i>u</i><tt>.getScheme(),<br>
393+ * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><i>u</i><tt>.getSchemeSpecificPart(),<br>
394+ * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><i>u</i><tt>.getFragment())<br>
395+ * .equals(</tt><i>u</i><tt>)</tt>
396+ * </blockquote>
397+ *
398+ * in all cases,
399+ *
400+ * <blockquote>
401+ * <tt>new URI(</tt><i>u</i><tt>.getScheme(),<br>
402+ * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><i>u</i><tt>.getUserInfo(),&nbsp;</tt><i>u</i><tt>.getAuthority(),<br>
403+ * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><i>u</i><tt>.getPath(),&nbsp;</tt><i>u</i><tt>.getQuery(),<br>
404+ * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><i>u</i><tt>.getFragment())<br>
405+ * .equals(</tt><i>u</i><tt>)</tt>
406+ * </blockquote>
407+ *
408+ * if <i>u</i> is hierarchical, and
409+ *
410+ * <blockquote>
411+ * <tt>new URI(</tt><i>u</i><tt>.getScheme(),<br>
412+ * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><i>u</i><tt>.getUserInfo(),&nbsp;</tt><i>u</i><tt>.getHost(),&nbsp;</tt><i>u</i><tt>.getPort(),<br>
413+ * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><i>u</i><tt>.getPath(),&nbsp;</tt><i>u</i><tt>.getQuery(),<br>
414+ * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><i>u</i><tt>.getFragment())<br>
415+ * .equals(</tt><i>u</i><tt>)</tt>
416+ * </blockquote>
417+ *
418+ * if <i>u</i> is hierarchical and has either no authority or a server-based
419+ * authority.
420+ *
421+ *
422+ * <h4> URIs, URLs, and URNs </h4>
423+ *
424+ * A URI is a uniform resource <i>identifier</i> while a URL is a uniform
425+ * resource <i>locator</i>. Hence every URL is a URI, abstractly speaking, but
426+ * not every URI is a URL. This is because there is another subcategory of
427+ * URIs, uniform resource <i>names</i> (URNs), which name resources but do not
428+ * specify how to locate them. The <tt>mailto</tt>, <tt>news</tt>, and
429+ * <tt>isbn</tt> URIs shown above are examples of URNs.
430+ *
431+ * <p> The conceptual distinction between URIs and URLs is reflected in the
432+ * differences between this class and the {@link URL} class.
433+ *
434+ * <p> An instance of this class represents a URI reference in the syntactic
435+ * sense defined by RFC&nbsp;2396. A URI may be either absolute or relative.
436+ * A URI string is parsed according to the generic syntax without regard to the
437+ * scheme, if any, that it specifies. No lookup of the host, if any, is
438+ * performed, and no scheme-dependent stream handler is constructed. Equality,
439+ * hashing, and comparison are defined strictly in terms of the character
440+ * content of the instance. In other words, a URI instance is little more than
441+ * a structured string that supports the syntactic, scheme-independent
442+ * operations of comparison, normalization, resolution, and relativization.
443+ *
444+ * <p> An instance of the {@link URL} class, by contrast, represents the
445+ * syntactic components of a URL together with some of the information required
446+ * to access the resource that it describes. A URL must be absolute, that is,
447+ * it must always specify a scheme. A URL string is parsed according to its
448+ * scheme. A stream handler is always established for a URL, and in fact it is
449+ * impossible to create a URL instance for a scheme for which no handler is
450+ * available. Equality and hashing depend upon both the scheme and the
451+ * Internet address of the host, if any; comparison is not defined. In other
452+ * words, a URL is a structured string that supports the syntactic operation of
453+ * resolution as well as the network I/O operations of looking up the host and
454+ * opening a connection to the specified resource.
455+ *
456+ *
457+ * @author Mark Reinhold
458+ * @since 1.4
459+ *
460+ * @see <a href="http://www.ietf.org/rfc/rfc2279.txt"><i>RFC&nbsp;2279: UTF-8, a
461+ * transformation format of ISO 10646</i></a>, <br><a
462+ * href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC&nbsp;2373: IPv6 Addressing
463+ * Architecture</i></a>, <br><a
464+ * href="http://www.ietf.org/rfc/rfc2396.txt"><i>RFC&nbsp;2396: Uniform
465+ * Resource Identifiers (URI): Generic Syntax</i></a>, <br><a
466+ * href="http://www.ietf.org/rfc/rfc2732.txt"><i>RFC&nbsp;2732: Format for
467+ * Literal IPv6 Addresses in URLs</i></a>, <br><a
468+ * href="URISyntaxException.html">URISyntaxException</a>
469+ */
470+
471+public final class URI
472+ implements Comparable<URI>, Serializable
473+{
474+
475+ // Note: Comments containing the word "ASSERT" indicate places where a
476+ // throw of an InternalError should be replaced by an appropriate assertion
477+ // statement once asserts are enabled in the build.
478+
479+ static final long serialVersionUID = -6052424284110960213L;
480+
481+
482+ // -- Properties and components of this instance --
483+
484+ // Components of all URIs: [<scheme>:]<scheme-specific-part>[#<fragment>]
485+ private transient String scheme; // null ==> relative URI
486+ private transient String fragment;
487+
488+ // Hierarchical URI components: [//<authority>]<path>[?<query>]
489+ private transient String authority; // Registry or server
490+
491+ // Server-based authority: [<userInfo>@]<host>[:<port>]
492+ private transient String userInfo;
493+ private transient String host; // null ==> registry-based
494+ private transient int port = -1; // -1 ==> undefined
495+
496+ // Remaining components of hierarchical URIs
497+ private transient String path; // null ==> opaque
498+ private transient String query;
499+
500+ // The remaining fields may be computed on demand
501+
502+ private volatile transient String schemeSpecificPart;
503+ private volatile transient int hash; // Zero ==> undefined
504+
505+ private volatile transient String decodedUserInfo = null;
506+ private volatile transient String decodedAuthority = null;
507+ private volatile transient String decodedPath = null;
508+ private volatile transient String decodedQuery = null;
509+ private volatile transient String decodedFragment = null;
510+ private volatile transient String decodedSchemeSpecificPart = null;
511+
512+ /**
513+ * The string form of this URI.
514+ *
515+ * @serial
516+ */
517+ private volatile String string; // The only serializable field
518+
519+
520+
521+ // -- Constructors and factories --
522+
523+ private URI() { } // Used internally
524+
525+ /**
526+ * Constructs a URI by parsing the given string.
527+ *
528+ * <p> This constructor parses the given string exactly as specified by the
529+ * grammar in <a
530+ * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
531+ * Appendix&nbsp;A, <b><i>except for the following deviations:</i></b> </p>
532+ *
533+ * <ul type=disc>
534+ *
535+ * <li><p> An empty authority component is permitted as long as it is
536+ * followed by a non-empty path, a query component, or a fragment
537+ * component. This allows the parsing of URIs such as
538+ * <tt>"file:///foo/bar"</tt>, which seems to be the intent of
539+ * RFC&nbsp;2396 although the grammar does not permit it. If the
540+ * authority component is empty then the user-information, host, and port
541+ * components are undefined. </p></li>
542+ *
543+ * <li><p> Empty relative paths are permitted; this seems to be the
544+ * intent of RFC&nbsp;2396 although the grammar does not permit it. The
545+ * primary consequence of this deviation is that a standalone fragment
546+ * such as <tt>"#foo"</tt> parses as a relative URI with an empty path
547+ * and the given fragment, and can be usefully <a
548+ * href="#resolve-frag">resolved</a> against a base URI.
549+ *
550+ * <li><p> IPv4 addresses in host components are parsed rigorously, as
551+ * specified by <a
552+ * href="http://www.ietf.org/rfc/rfc2732.txt">RFC&nbsp;2732</a>: Each
553+ * element of a dotted-quad address must contain no more than three
554+ * decimal digits. Each element is further constrained to have a value
555+ * no greater than 255. </p></li>
556+ *
557+ * <li> <p> Hostnames in host components that comprise only a single
558+ * domain label are permitted to start with an <i>alphanum</i>
559+ * character. This seems to be the intent of <a
560+ * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>
561+ * section&nbsp;3.2.2 although the grammar does not permit it. The
562+ * consequence of this deviation is that the authority component of a
563+ * hierarchical URI such as <tt>s://123</tt>, will parse as a server-based
564+ * authority. </p></li>
565+ *
566+ * <li><p> IPv6 addresses are permitted for the host component. An IPv6
567+ * address must be enclosed in square brackets (<tt>'['</tt> and
568+ * <tt>']'</tt>) as specified by <a
569+ * href="http://www.ietf.org/rfc/rfc2732.txt">RFC&nbsp;2732</a>. The
570+ * IPv6 address itself must parse according to <a
571+ * href="http://www.ietf.org/rfc/rfc2373.txt">RFC&nbsp;2373</a>. IPv6
572+ * addresses are further constrained to describe no more than sixteen
573+ * bytes of address information, a constraint implicit in RFC&nbsp;2373
574+ * but not expressible in the grammar. </p></li>
575+ *
576+ * <li><p> Characters in the <i>other</i> category are permitted wherever
577+ * RFC&nbsp;2396 permits <i>escaped</i> octets, that is, in the
578+ * user-information, path, query, and fragment components, as well as in
579+ * the authority component if the authority is registry-based. This
580+ * allows URIs to contain Unicode characters beyond those in the US-ASCII
581+ * character set. </p></li>
582+ *
583+ * </ul>
584+ *
585+ * @param str The string to be parsed into a URI
586+ *
587+ * @throws NullPointerException
588+ * If <tt>str</tt> is <tt>null</tt>
589+ *
590+ * @throws URISyntaxException
591+ * If the given string violates RFC&nbsp;2396, as augmented
592+ * by the above deviations
593+ */
594+ public URI(String str) throws URISyntaxException {
595+ new Parser(str).parse(false);
596+ }
597+
598+ /**
599+ * Constructs a hierarchical URI from the given components.
600+ *
601+ * <p> If a scheme is given then the path, if also given, must either be
602+ * empty or begin with a slash character (<tt>'/'</tt>). Otherwise a
603+ * component of the new URI may be left undefined by passing <tt>null</tt>
604+ * for the corresponding parameter or, in the case of the <tt>port</tt>
605+ * parameter, by passing <tt>-1</tt>.
606+ *
607+ * <p> This constructor first builds a URI string from the given components
608+ * according to the rules specified in <a
609+ * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
610+ * section&nbsp;5.2, step&nbsp;7: </p>
611+ *
612+ * <ol>
613+ *
614+ * <li><p> Initially, the result string is empty. </p></li>
615+ *
616+ * <li><p> If a scheme is given then it is appended to the result,
617+ * followed by a colon character (<tt>':'</tt>). </p></li>
618+ *
619+ * <li><p> If user information, a host, or a port are given then the
620+ * string <tt>"//"</tt> is appended. </p></li>
621+ *
622+ * <li><p> If user information is given then it is appended, followed by
623+ * a commercial-at character (<tt>'@'</tt>). Any character not in the
624+ * <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, or <i>other</i>
625+ * categories is <a href="#quote">quoted</a>. </p></li>
626+ *
627+ * <li><p> If a host is given then it is appended. If the host is a
628+ * literal IPv6 address but is not enclosed in square brackets
629+ * (<tt>'['</tt> and <tt>']'</tt>) then the square brackets are added.
630+ * </p></li>
631+ *
632+ * <li><p> If a port number is given then a colon character
633+ * (<tt>':'</tt>) is appended, followed by the port number in decimal.
634+ * </p></li>
635+ *
636+ * <li><p> If a path is given then it is appended. Any character not in
637+ * the <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, or <i>other</i>
638+ * categories, and not equal to the slash character (<tt>'/'</tt>) or the
639+ * commercial-at character (<tt>'@'</tt>), is quoted. </p></li>
640+ *
641+ * <li><p> If a query is given then a question-mark character
642+ * (<tt>'?'</tt>) is appended, followed by the query. Any character that
643+ * is not a <a href="#legal-chars">legal URI character</a> is quoted.
644+ * </p></li>
645+ *
646+ * <li><p> Finally, if a fragment is given then a hash character
647+ * (<tt>'#'</tt>) is appended, followed by the fragment. Any character
648+ * that is not a legal URI character is quoted. </p></li>
649+ *
650+ * </ol>
651+ *
652+ * <p> The resulting URI string is then parsed as if by invoking the {@link
653+ * #URI(String)} constructor and then invoking the {@link
654+ * #parseServerAuthority()} method upon the result; this may cause a {@link
655+ * URISyntaxException} to be thrown. </p>
656+ *
657+ * @param scheme Scheme name
658+ * @param userInfo User name and authorization information
659+ * @param host Host name
660+ * @param port Port number
661+ * @param path Path
662+ * @param query Query
663+ * @param fragment Fragment
664+ *
665+ * @throws URISyntaxException
666+ * If both a scheme and a path are given but the path is relative,
667+ * if the URI string constructed from the given components violates
668+ * RFC&nbsp;2396, or if the authority component of the string is
669+ * present but cannot be parsed as a server-based authority
670+ */
671+ public URI(String scheme,
672+ String userInfo, String host, int port,
673+ String path, String query, String fragment)
674+ throws URISyntaxException
675+ {
676+ String s = toString(scheme, null,
677+ null, userInfo, host, port,
678+ path, query, fragment);
679+ checkPath(s, scheme, path);
680+ new Parser(s).parse(true);
681+ }
682+
683+ /**
684+ * Constructs a hierarchical URI from the given components.
685+ *
686+ * <p> If a scheme is given then the path, if also given, must either be
687+ * empty or begin with a slash character (<tt>'/'</tt>). Otherwise a
688+ * component of the new URI may be left undefined by passing <tt>null</tt>
689+ * for the corresponding parameter.
690+ *
691+ * <p> This constructor first builds a URI string from the given components
692+ * according to the rules specified in <a
693+ * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
694+ * section&nbsp;5.2, step&nbsp;7: </p>
695+ *
696+ * <ol>
697+ *
698+ * <li><p> Initially, the result string is empty. </p></li>
699+ *
700+ * <li><p> If a scheme is given then it is appended to the result,
701+ * followed by a colon character (<tt>':'</tt>). </p></li>
702+ *
703+ * <li><p> If an authority is given then the string <tt>"//"</tt> is
704+ * appended, followed by the authority. If the authority contains a
705+ * literal IPv6 address then the address must be enclosed in square
706+ * brackets (<tt>'['</tt> and <tt>']'</tt>). Any character not in the
707+ * <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, or <i>other</i>
708+ * categories, and not equal to the commercial-at character
709+ * (<tt>'@'</tt>), is <a href="#quote">quoted</a>. </p></li>
710+ *
711+ * <li><p> If a path is given then it is appended. Any character not in
712+ * the <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, or <i>other</i>
713+ * categories, and not equal to the slash character (<tt>'/'</tt>) or the
714+ * commercial-at character (<tt>'@'</tt>), is quoted. </p></li>
715+ *
716+ * <li><p> If a query is given then a question-mark character
717+ * (<tt>'?'</tt>) is appended, followed by the query. Any character that
718+ * is not a <a href="#legal-chars">legal URI character</a> is quoted.
719+ * </p></li>
720+ *
721+ * <li><p> Finally, if a fragment is given then a hash character
722+ * (<tt>'#'</tt>) is appended, followed by the fragment. Any character
723+ * that is not a legal URI character is quoted. </p></li>
724+ *
725+ * </ol>
726+ *
727+ * <p> The resulting URI string is then parsed as if by invoking the {@link
728+ * #URI(String)} constructor and then invoking the {@link
729+ * #parseServerAuthority()} method upon the result; this may cause a {@link
730+ * URISyntaxException} to be thrown. </p>
731+ *
732+ * @param scheme Scheme name
733+ * @param authority Authority
734+ * @param path Path
735+ * @param query Query
736+ * @param fragment Fragment
737+ *
738+ * @throws URISyntaxException
739+ * If both a scheme and a path are given but the path is relative,
740+ * if the URI string constructed from the given components violates
741+ * RFC&nbsp;2396, or if the authority component of the string is
742+ * present but cannot be parsed as a server-based authority
743+ */
744+ public URI(String scheme,
745+ String authority,
746+ String path, String query, String fragment)
747+ throws URISyntaxException
748+ {
749+ String s = toString(scheme, null,
750+ authority, null, null, -1,
751+ path, query, fragment);
752+ checkPath(s, scheme, path);
753+ new Parser(s).parse(false);
754+ }
755+
756+ /**
757+ * Constructs a hierarchical URI from the given components.
758+ *
759+ * <p> A component may be left undefined by passing <tt>null</tt>.
760+ *
761+ * <p> This convenience constructor works as if by invoking the
762+ * seven-argument constructor as follows:
763+ *
764+ * <blockquote><tt>
765+ * new&nbsp;{@link #URI(String, String, String, int, String, String, String)
766+ * URI}(scheme,&nbsp;null,&nbsp;host,&nbsp;-1,&nbsp;path,&nbsp;null,&nbsp;fragment);
767+ * </tt></blockquote>
768+ *
769+ * @param scheme Scheme name
770+ * @param host Host name
771+ * @param path Path
772+ * @param fragment Fragment
773+ *
774+ * @throws URISyntaxException
775+ * If the URI string constructed from the given components
776+ * violates RFC&nbsp;2396
777+ */
778+ public URI(String scheme, String host, String path, String fragment)
779+ throws URISyntaxException
780+ {
781+ this(scheme, null, host, -1, path, null, fragment);
782+ }
783+
784+ /**
785+ * Constructs a URI from the given components.
786+ *
787+ * <p> A component may be left undefined by passing <tt>null</tt>.
788+ *
789+ * <p> This constructor first builds a URI in string form using the given
790+ * components as follows: </p>
791+ *
792+ * <ol>
793+ *
794+ * <li><p> Initially, the result string is empty. </p></li>
795+ *
796+ * <li><p> If a scheme is given then it is appended to the result,
797+ * followed by a colon character (<tt>':'</tt>). </p></li>
798+ *
799+ * <li><p> If a scheme-specific part is given then it is appended. Any
800+ * character that is not a <a href="#legal-chars">legal URI character</a>
801+ * is <a href="#quote">quoted</a>. </p></li>
802+ *
803+ * <li><p> Finally, if a fragment is given then a hash character
804+ * (<tt>'#'</tt>) is appended to the string, followed by the fragment.
805+ * Any character that is not a legal URI character is quoted. </p></li>
806+ *
807+ * </ol>
808+ *
809+ * <p> The resulting URI string is then parsed in order to create the new
810+ * URI instance as if by invoking the {@link #URI(String)} constructor;
811+ * this may cause a {@link URISyntaxException} to be thrown. </p>
812+ *
813+ * @param scheme Scheme name
814+ * @param ssp Scheme-specific part
815+ * @param fragment Fragment
816+ *
817+ * @throws URISyntaxException
818+ * If the URI string constructed from the given components
819+ * violates RFC&nbsp;2396
820+ */
821+ public URI(String scheme, String ssp, String fragment)
822+ throws URISyntaxException
823+ {
824+ new Parser(toString(scheme, ssp,
825+ null, null, null, -1,
826+ null, null, fragment))
827+ .parse(false);
828+ }
829+
830+ /**
831+ * Creates a URI by parsing the given string.
832+ *
833+ * <p> This convenience factory method works as if by invoking the {@link
834+ * #URI(String)} constructor; any {@link URISyntaxException} thrown by the
835+ * constructor is caught and wrapped in a new {@link
836+ * IllegalArgumentException} object, which is then thrown.
837+ *
838+ * <p> This method is provided for use in situations where it is known that
839+ * the given string is a legal URI, for example for URI constants declared
840+ * within in a program, and so it would be considered a programming error
841+ * for the string not to parse as such. The constructors, which throw
842+ * {@link URISyntaxException} directly, should be used situations where a
843+ * URI is being constructed from user input or from some other source that
844+ * may be prone to errors. </p>
845+ *
846+ * @param str The string to be parsed into a URI
847+ * @return The new URI
848+ *
849+ * @throws NullPointerException
850+ * If <tt>str</tt> is <tt>null</tt>
851+ *
852+ * @throws IllegalArgumentException
853+ * If the given string violates RFC&nbsp;2396
854+ */
855+ public static URI create(String str) {
856+ try {
857+ return new URI(str);
858+ } catch (URISyntaxException x) {
859+ throw new IllegalArgumentException(x.getMessage(), x);
860+ }
861+ }
862+
863+
864+ // -- Operations --
865+
866+ /**
867+ * Attempts to parse this URI's authority component, if defined, into
868+ * user-information, host, and port components.
869+ *
870+ * <p> If this URI's authority component has already been recognized as
871+ * being server-based then it will already have been parsed into
872+ * user-information, host, and port components. In this case, or if this
873+ * URI has no authority component, this method simply returns this URI.
874+ *
875+ * <p> Otherwise this method attempts once more to parse the authority
876+ * component into user-information, host, and port components, and throws
877+ * an exception describing why the authority component could not be parsed
878+ * in that way.
879+ *
880+ * <p> This method is provided because the generic URI syntax specified in
881+ * <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>
882+ * cannot always distinguish a malformed server-based authority from a
883+ * legitimate registry-based authority. It must therefore treat some
884+ * instances of the former as instances of the latter. The authority
885+ * component in the URI string <tt>"//foo:bar"</tt>, for example, is not a
886+ * legal server-based authority but it is legal as a registry-based
887+ * authority.
888+ *
889+ * <p> In many common situations, for example when working URIs that are
890+ * known to be either URNs or URLs, the hierarchical URIs being used will
891+ * always be server-based. They therefore must either be parsed as such or
892+ * treated as an error. In these cases a statement such as
893+ *
894+ * <blockquote>
895+ * <tt>URI </tt><i>u</i><tt> = new URI(str).parseServerAuthority();</tt>
896+ * </blockquote>
897+ *
898+ * <p> can be used to ensure that <i>u</i> always refers to a URI that, if
899+ * it has an authority component, has a server-based authority with proper
900+ * user-information, host, and port components. Invoking this method also
901+ * ensures that if the authority could not be parsed in that way then an
902+ * appropriate diagnostic message can be issued based upon the exception
903+ * that is thrown. </p>
904+ *
905+ * @return A URI whose authority field has been parsed
906+ * as a server-based authority
907+ *
908+ * @throws URISyntaxException
909+ * If the authority component of this URI is defined
910+ * but cannot be parsed as a server-based authority
911+ * according to RFC&nbsp;2396
912+ */
913+ public URI parseServerAuthority()
914+ throws URISyntaxException
915+ {
916+ // We could be clever and cache the error message and index from the
917+ // exception thrown during the original parse, but that would require
918+ // either more fields or a more-obscure representation.
919+ if ((host != null) || (authority == null))
920+ return this;
921+ defineString();
922+ new Parser(string).parse(true);
923+ return this;
924+ }
925+
926+ /**
927+ * Normalizes this URI's path.
928+ *
929+ * <p> If this URI is opaque, or if its path is already in normal form,
930+ * then this URI is returned. Otherwise a new URI is constructed that is
931+ * identical to this URI except that its path is computed by normalizing
932+ * this URI's path in a manner consistent with <a
933+ * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
934+ * section&nbsp;5.2, step&nbsp;6, sub-steps&nbsp;c through&nbsp;f; that is:
935+ * </p>
936+ *
937+ * <ol>
938+ *
939+ * <li><p> All <tt>"."</tt> segments are removed. </p></li>
940+ *
941+ * <li><p> If a <tt>".."</tt> segment is preceded by a non-<tt>".."</tt>
942+ * segment then both of these segments are removed. This step is
943+ * repeated until it is no longer applicable. </p></li>
944+ *
945+ * <li><p> If the path is relative, and if its first segment contains a
946+ * colon character (<tt>':'</tt>), then a <tt>"."</tt> segment is
947+ * prepended. This prevents a relative URI with a path such as
948+ * <tt>"a:b/c/d"</tt> from later being re-parsed as an opaque URI with a
949+ * scheme of <tt>"a"</tt> and a scheme-specific part of <tt>"b/c/d"</tt>.
950+ * <b><i>(Deviation from RFC&nbsp;2396)</i></b> </p></li>
951+ *
952+ * </ol>
953+ *
954+ * <p> A normalized path will begin with one or more <tt>".."</tt> segments
955+ * if there were insufficient non-<tt>".."</tt> segments preceding them to
956+ * allow their removal. A normalized path will begin with a <tt>"."</tt>
957+ * segment if one was inserted by step 3 above. Otherwise, a normalized
958+ * path will not contain any <tt>"."</tt> or <tt>".."</tt> segments. </p>
959+ *
960+ * @return A URI equivalent to this URI,
961+ * but whose path is in normal form
962+ */
963+ public URI normalize() {
964+ return normalize(this);
965+ }
966+
967+ /**
968+ * Resolves the given URI against this URI.
969+ *
970+ * <p> If the given URI is already absolute, or if this URI is opaque, then
971+ * the given URI is returned.
972+ *
973+ * <p><a name="resolve-frag"></a> If the given URI's fragment component is
974+ * defined, its path component is empty, and its scheme, authority, and
975+ * query components are undefined, then a URI with the given fragment but
976+ * with all other components equal to those of this URI is returned. This
977+ * allows a URI representing a standalone fragment reference, such as
978+ * <tt>"#foo"</tt>, to be usefully resolved against a base URI.
979+ *
980+ * <p> Otherwise this method constructs a new hierarchical URI in a manner
981+ * consistent with <a
982+ * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
983+ * section&nbsp;5.2; that is: </p>
984+ *
985+ * <ol>
986+ *
987+ * <li><p> A new URI is constructed with this URI's scheme and the given
988+ * URI's query and fragment components. </p></li>
989+ *
990+ * <li><p> If the given URI has an authority component then the new URI's
991+ * authority and path are taken from the given URI. </p></li>
992+ *
993+ * <li><p> Otherwise the new URI's authority component is copied from
994+ * this URI, and its path is computed as follows: </p>
995+ *
996+ * <ol type=a>
997+ *
998+ * <li><p> If the given URI's path is absolute then the new URI's path
999+ * is taken from the given URI. </p></li>
1000+ *
1001+ * <li><p> Otherwise the given URI's path is relative, and so the new
1002+ * URI's path is computed by resolving the path of the given URI
1003+ * against the path of this URI. This is done by concatenating all but
1004+ * the last segment of this URI's path, if any, with the given URI's
1005+ * path and then normalizing the result as if by invoking the {@link
1006+ * #normalize() normalize} method. </p></li>
1007+ *
1008+ * </ol></li>
1009+ *
1010+ * </ol>
1011+ *
1012+ * <p> The result of this method is absolute if, and only if, either this
1013+ * URI is absolute or the given URI is absolute. </p>
1014+ *
1015+ * @param uri The URI to be resolved against this URI
1016+ * @return The resulting URI
1017+ *
1018+ * @throws NullPointerException
1019+ * If <tt>uri</tt> is <tt>null</tt>
1020+ */
1021+ public URI resolve(URI uri) {
1022+ return resolve(this, uri);
1023+ }
1024+
1025+ /**
1026+ * Constructs a new URI by parsing the given string and then resolving it
1027+ * against this URI.
1028+ *
1029+ * <p> This convenience method works as if invoking it were equivalent to
1030+ * evaluating the expression <tt>{@link #resolve(java.net.URI)
1031+ * resolve}(URI.{@link #create(String) create}(str))</tt>. </p>
1032+ *
1033+ * @param str The string to be parsed into a URI
1034+ * @return The resulting URI
1035+ *
1036+ * @throws NullPointerException
1037+ * If <tt>str</tt> is <tt>null</tt>
1038+ *
1039+ * @throws IllegalArgumentException
1040+ * If the given string violates RFC&nbsp;2396
1041+ */
1042+ public URI resolve(String str) {
1043+ return resolve(URI.create(str));
1044+ }
1045+
1046+ /**
1047+ * Relativizes the given URI against this URI.
1048+ *
1049+ * <p> The relativization of the given URI against this URI is computed as
1050+ * follows: </p>
1051+ *
1052+ * <ol>
1053+ *
1054+ * <li><p> If either this URI or the given URI are opaque, or if the
1055+ * scheme and authority components of the two URIs are not identical, or
1056+ * if the path of this URI is not a prefix of the path of the given URI,
1057+ * then the given URI is returned. </p></li>
1058+ *
1059+ * <li><p> Otherwise a new relative hierarchical URI is constructed with
1060+ * query and fragment components taken from the given URI and with a path
1061+ * component computed by removing this URI's path from the beginning of
1062+ * the given URI's path. </p></li>
1063+ *
1064+ * </ol>
1065+ *
1066+ * @param uri The URI to be relativized against this URI
1067+ * @return The resulting URI
1068+ *
1069+ * @throws NullPointerException
1070+ * If <tt>uri</tt> is <tt>null</tt>
1071+ */
1072+ public URI relativize(URI uri) {
1073+ return relativize(this, uri);
1074+ }
1075+
1076+ /**
1077+ * Constructs a URL from this URI.
1078+ *
1079+ * <p> This convenience method works as if invoking it were equivalent to
1080+ * evaluating the expression <tt>new&nbsp;URL(this.toString())</tt> after
1081+ * first checking that this URI is absolute. </p>
1082+ *
1083+ * @return A URL constructed from this URI
1084+ *
1085+ * @throws IllegalArgumentException
1086+ * If this URL is not absolute
1087+ *
1088+ * @throws MalformedURLException
1089+ * If a protocol handler for the URL could not be found,
1090+ * or if some other error occurred while constructing the URL
1091+ */
1092+ public URL toURL()
1093+ throws MalformedURLException {
1094+ if (!isAbsolute())
1095+ throw new IllegalArgumentException("URI is not absolute");
1096+ return new URL(toString());
1097+ }
1098+
1099+ // -- Component access methods --
1100+
1101+ /**
1102+ * Returns the scheme component of this URI.
1103+ *
1104+ * <p> The scheme component of a URI, if defined, only contains characters
1105+ * in the <i>alphanum</i> category and in the string <tt>"-.+"</tt>. A
1106+ * scheme always starts with an <i>alpha</i> character. <p>
1107+ *
1108+ * The scheme component of a URI cannot contain escaped octets, hence this
1109+ * method does not perform any decoding.
1110+ *
1111+ * @return The scheme component of this URI,
1112+ * or <tt>null</tt> if the scheme is undefined
1113+ */
1114+ public String getScheme() {
1115+ return scheme;
1116+ }
1117+
1118+ /**
1119+ * Tells whether or not this URI is absolute.
1120+ *
1121+ * <p> A URI is absolute if, and only if, it has a scheme component. </p>
1122+ *
1123+ * @return <tt>true</tt> if, and only if, this URI is absolute
1124+ */
1125+ public boolean isAbsolute() {
1126+ return scheme != null;
1127+ }
1128+
1129+ /**
1130+ * Tells whether or not this URI is opaque.
1131+ *
1132+ * <p> A URI is opaque if, and only if, it is absolute and its
1133+ * scheme-specific part does not begin with a slash character ('/').
1134+ * An opaque URI has a scheme, a scheme-specific part, and possibly
1135+ * a fragment; all other components are undefined. </p>
1136+ *
1137+ * @return <tt>true</tt> if, and only if, this URI is opaque
1138+ */
1139+ public boolean isOpaque() {
1140+ return path == null;
1141+ }
1142+
1143+ /**
1144+ * Returns the raw scheme-specific part of this URI. The scheme-specific
1145+ * part is never undefined, though it may be empty.
1146+ *
1147+ * <p> The scheme-specific part of a URI only contains legal URI
1148+ * characters. </p>
1149+ *
1150+ * @return The raw scheme-specific part of this URI
1151+ * (never <tt>null</tt>)
1152+ */
1153+ public String getRawSchemeSpecificPart() {
1154+ defineSchemeSpecificPart();
1155+ return schemeSpecificPart;
1156+ }
1157+
1158+ /**
1159+ * Returns the decoded scheme-specific part of this URI.
1160+ *
1161+ * <p> The string returned by this method is equal to that returned by the
1162+ * {@link #getRawSchemeSpecificPart() getRawSchemeSpecificPart} method
1163+ * except that all sequences of escaped octets are <a
1164+ * href="#decode">decoded</a>. </p>
1165+ *
1166+ * @return The decoded scheme-specific part of this URI
1167+ * (never <tt>null</tt>)
1168+ */
1169+ public String getSchemeSpecificPart() {
1170+ if (decodedSchemeSpecificPart == null)
1171+ decodedSchemeSpecificPart = decode(getRawSchemeSpecificPart());
1172+ return decodedSchemeSpecificPart;
1173+ }
1174+
1175+ /**
1176+ * Returns the raw authority component of this URI.
1177+ *
1178+ * <p> The authority component of a URI, if defined, only contains the
1179+ * commercial-at character (<tt>'@'</tt>) and characters in the
1180+ * <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, and <i>other</i>
1181+ * categories. If the authority is server-based then it is further
1182+ * constrained to have valid user-information, host, and port
1183+ * components. </p>
1184+ *
1185+ * @return The raw authority component of this URI,
1186+ * or <tt>null</tt> if the authority is undefined
1187+ */
1188+ public String getRawAuthority() {
1189+ return authority;
1190+ }
1191+
1192+ /**
1193+ * Returns the decoded authority component of this URI.
1194+ *
1195+ * <p> The string returned by this method is equal to that returned by the
1196+ * {@link #getRawAuthority() getRawAuthority} method except that all
1197+ * sequences of escaped octets are <a href="#decode">decoded</a>. </p>
1198+ *
1199+ * @return The decoded authority component of this URI,
1200+ * or <tt>null</tt> if the authority is undefined
1201+ */
1202+ public String getAuthority() {
1203+ if (decodedAuthority == null)
1204+ decodedAuthority = decode(authority);
1205+ return decodedAuthority;
1206+ }
1207+
1208+ /**
1209+ * Returns the raw user-information component of this URI.
1210+ *
1211+ * <p> The user-information component of a URI, if defined, only contains
1212+ * characters in the <i>unreserved</i>, <i>punct</i>, <i>escaped</i>, and
1213+ * <i>other</i> categories. </p>
1214+ *
1215+ * @return The raw user-information component of this URI,
1216+ * or <tt>null</tt> if the user information is undefined
1217+ */
1218+ public String getRawUserInfo() {
1219+ return userInfo;
1220+ }
1221+
1222+ /**
1223+ * Returns the decoded user-information component of this URI.
1224+ *
1225+ * <p> The string returned by this method is equal to that returned by the
1226+ * {@link #getRawUserInfo() getRawUserInfo} method except that all
1227+ * sequences of escaped octets are <a href="#decode">decoded</a>. </p>
1228+ *
1229+ * @return The decoded user-information component of this URI,
1230+ * or <tt>null</tt> if the user information is undefined
1231+ */
1232+ public String getUserInfo() {
1233+ if ((decodedUserInfo == null) && (userInfo != null))
1234+ decodedUserInfo = decode(userInfo);
1235+ return decodedUserInfo;
1236+ }
1237+
1238+ /**
1239+ * Returns the host component of this URI.
1240+ *
1241+ * <p> The host component of a URI, if defined, will have one of the
1242+ * following forms: </p>
1243+ *
1244+ * <ul type=disc>
1245+ *
1246+ * <li><p> A domain name consisting of one or more <i>labels</i>
1247+ * separated by period characters (<tt>'.'</tt>), optionally followed by
1248+ * a period character. Each label consists of <i>alphanum</i> characters
1249+ * as well as hyphen characters (<tt>'-'</tt>), though hyphens never
1250+ * occur as the first or last characters in a label. The rightmost
1251+ * label of a domain name consisting of two or more labels, begins
1252+ * with an <i>alpha</i> character. </li>
1253+ *
1254+ * <li><p> A dotted-quad IPv4 address of the form
1255+ * <i>digit</i><tt>+.</tt><i>digit</i><tt>+.</tt><i>digit</i><tt>+.</tt><i>digit</i><tt>+</tt>,
1256+ * where no <i>digit</i> sequence is longer than three characters and no
1257+ * sequence has a value larger than 255. </p></li>
1258+ *
1259+ * <li><p> An IPv6 address enclosed in square brackets (<tt>'['</tt> and
1260+ * <tt>']'</tt>) and consisting of hexadecimal digits, colon characters
1261+ * (<tt>':'</tt>), and possibly an embedded IPv4 address. The full
1262+ * syntax of IPv6 addresses is specified in <a
1263+ * href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC&nbsp;2373: IPv6
1264+ * Addressing Architecture</i></a>. </p></li>
1265+ *
1266+ * </ul>
1267+ *
1268+ * The host component of a URI cannot contain escaped octets, hence this
1269+ * method does not perform any decoding.
1270+ *
1271+ * @return The host component of this URI,
1272+ * or <tt>null</tt> if the host is undefined
1273+ */
1274+ public String getHost() {
1275+ return host;
1276+ }
1277+
1278+ /**
1279+ * Returns the port number of this URI.
1280+ *
1281+ * <p> The port component of a URI, if defined, is a non-negative
1282+ * integer. </p>
1283+ *
1284+ * @return The port component of this URI,
1285+ * or <tt>-1</tt> if the port is undefined
1286+ */
1287+ public int getPort() {
1288+ return port;
1289+ }
1290+
1291+ /**
1292+ * Returns the raw path component of this URI.
1293+ *
1294+ * <p> The path component of a URI, if defined, only contains the slash
1295+ * character (<tt>'/'</tt>), the commercial-at character (<tt>'@'</tt>),
1296+ * and characters in the <i>unreserved</i>, <i>punct</i>, <i>escaped</i>,
1297+ * and <i>other</i> categories. </p>
1298+ *
1299+ * @return The path component of this URI,
1300+ * or <tt>null</tt> if the path is undefined
1301+ */
1302+ public String getRawPath() {
1303+ return path;
1304+ }
1305+
1306+ /**
1307+ * Returns the decoded path component of this URI.
1308+ *
1309+ * <p> The string returned by this method is equal to that returned by the
1310+ * {@link #getRawPath() getRawPath} method except that all sequences of
1311+ * escaped octets are <a href="#decode">decoded</a>. </p>
1312+ *
1313+ * @return The decoded path component of this URI,
1314+ * or <tt>null</tt> if the path is undefined
1315+ */
1316+ public String getPath() {
1317+ if ((decodedPath == null) && (path != null))
1318+ decodedPath = decode(path);
1319+ return decodedPath;
1320+ }
1321+
1322+ /**
1323+ * Returns the raw query component of this URI.
1324+ *
1325+ * <p> The query component of a URI, if defined, only contains legal URI
1326+ * characters. </p>
1327+ *
1328+ * @return The raw query component of this URI,
1329+ * or <tt>null</tt> if the query is undefined
1330+ */
1331+ public String getRawQuery() {
1332+ return query;
1333+ }
1334+
1335+ /**
1336+ * Returns the decoded query component of this URI.
1337+ *
1338+ * <p> The string returned by this method is equal to that returned by the
1339+ * {@link #getRawQuery() getRawQuery} method except that all sequences of
1340+ * escaped octets are <a href="#decode">decoded</a>. </p>
1341+ *
1342+ * @return The decoded query component of this URI,
1343+ * or <tt>null</tt> if the query is undefined
1344+ */
1345+ public String getQuery() {
1346+ if ((decodedQuery == null) && (query != null))
1347+ decodedQuery = decode(query);
1348+ return decodedQuery;
1349+ }
1350+
1351+ /**
1352+ * Returns the raw fragment component of this URI.
1353+ *
1354+ * <p> The fragment component of a URI, if defined, only contains legal URI
1355+ * characters. </p>
1356+ *
1357+ * @return The raw fragment component of this URI,
1358+ * or <tt>null</tt> if the fragment is undefined
1359+ */
1360+ public String getRawFragment() {
1361+ return fragment;
1362+ }
1363+
1364+ /**
1365+ * Returns the decoded fragment component of this URI.
1366+ *
1367+ * <p> The string returned by this method is equal to that returned by the
1368+ * {@link #getRawFragment() getRawFragment} method except that all
1369+ * sequences of escaped octets are <a href="#decode">decoded</a>. </p>
1370+ *
1371+ * @return The decoded fragment component of this URI,
1372+ * or <tt>null</tt> if the fragment is undefined
1373+ */
1374+ public String getFragment() {
1375+ if ((decodedFragment == null) && (fragment != null))
1376+ decodedFragment = decode(fragment);
1377+ return decodedFragment;
1378+ }
1379+
1380+
1381+ // -- Equality, comparison, hash code, toString, and serialization --
1382+
1383+ /**
1384+ * Tests this URI for equality with another object.
1385+ *
1386+ * <p> If the given object is not a URI then this method immediately
1387+ * returns <tt>false</tt>.
1388+ *
1389+ * <p> For two URIs to be considered equal requires that either both are
1390+ * opaque or both are hierarchical. Their schemes must either both be
1391+ * undefined or else be equal without regard to case. Their fragments
1392+ * must either both be undefined or else be equal.
1393+ *
1394+ * <p> For two opaque URIs to be considered equal, their scheme-specific
1395+ * parts must be equal.
1396+ *
1397+ * <p> For two hierarchical URIs to be considered equal, their paths must
1398+ * be equal and their queries must either both be undefined or else be
1399+ * equal. Their authorities must either both be undefined, or both be
1400+ * registry-based, or both be server-based. If their authorities are
1401+ * defined and are registry-based, then they must be equal. If their
1402+ * authorities are defined and are server-based, then their hosts must be
1403+ * equal without regard to case, their port numbers must be equal, and
1404+ * their user-information components must be equal.
1405+ *
1406+ * <p> When testing the user-information, path, query, fragment, authority,
1407+ * or scheme-specific parts of two URIs for equality, the raw forms rather
1408+ * than the encoded forms of these components are compared and the
1409+ * hexadecimal digits of escaped octets are compared without regard to
1410+ * case.
1411+ *
1412+ * <p> This method satisfies the general contract of the {@link
1413+ * java.lang.Object#equals(Object) Object.equals} method. </p>
1414+ *
1415+ * @param ob The object to which this object is to be compared
1416+ *
1417+ * @return <tt>true</tt> if, and only if, the given object is a URI that
1418+ * is identical to this URI
1419+ */
1420+ public boolean equals(Object ob) {
1421+ if (ob == this)
1422+ return true;
1423+ if (!(ob instanceof URI))
1424+ return false;
1425+ URI that = (URI)ob;
1426+ if (this.isOpaque() != that.isOpaque()) return false;
1427+ if (!equalIgnoringCase(this.scheme, that.scheme)) return false;
1428+ if (!equal(this.fragment, that.fragment)) return false;
1429+
1430+ // Opaque
1431+ if (this.isOpaque())
1432+ return equal(this.schemeSpecificPart, that.schemeSpecificPart);
1433+
1434+ // Hierarchical
1435+ if (!equal(this.path, that.path)) return false;
1436+ if (!equal(this.query, that.query)) return false;
1437+
1438+ // Authorities
1439+ if (this.authority == that.authority) return true;
1440+ if (this.host != null) {
1441+ // Server-based
1442+ if (!equal(this.userInfo, that.userInfo)) return false;
1443+ if (!equalIgnoringCase(this.host, that.host)) return false;
1444+ if (this.port != that.port) return false;
1445+ } else if (this.authority != null) {
1446+ // Registry-based
1447+ if (!equal(this.authority, that.authority)) return false;
1448+ } else if (this.authority != that.authority) {
1449+ return false;
1450+ }
1451+
1452+ return true;
1453+ }
1454+
1455+ /**
1456+ * Returns a hash-code value for this URI. The hash code is based upon all
1457+ * of the URI's components, and satisfies the general contract of the
1458+ * {@link java.lang.Object#hashCode() Object.hashCode} method.
1459+ *
1460+ * @return A hash-code value for this URI
1461+ */
1462+ public int hashCode() {
1463+ if (hash != 0)
1464+ return hash;
1465+ int h = hashIgnoringCase(0, scheme);
1466+ h = hash(h, fragment);
1467+ if (isOpaque()) {
1468+ h = hash(h, schemeSpecificPart);
1469+ } else {
1470+ h = hash(h, path);
1471+ h = hash(h, query);
1472+ if (host != null) {
1473+ h = hash(h, userInfo);
1474+ h = hashIgnoringCase(h, host);
1475+ h += 1949 * port;
1476+ } else {
1477+ h = hash(h, authority);
1478+ }
1479+ }
1480+ hash = h;
1481+ return h;
1482+ }
1483+
1484+ /**
1485+ * Compares this URI to another object, which must be a URI.
1486+ *
1487+ * <p> When comparing corresponding components of two URIs, if one
1488+ * component is undefined but the other is defined then the first is
1489+ * considered to be less than the second. Unless otherwise noted, string
1490+ * components are ordered according to their natural, case-sensitive
1491+ * ordering as defined by the {@link java.lang.String#compareTo(Object)
1492+ * String.compareTo} method. String components that are subject to
1493+ * encoding are compared by comparing their raw forms rather than their
1494+ * encoded forms.
1495+ *
1496+ * <p> The ordering of URIs is defined as follows: </p>
1497+ *
1498+ * <ul type=disc>
1499+ *
1500+ * <li><p> Two URIs with different schemes are ordered according the
1501+ * ordering of their schemes, without regard to case. </p></li>
1502+ *
1503+ * <li><p> A hierarchical URI is considered to be less than an opaque URI
1504+ * with an identical scheme. </p></li>
1505+ *
1506+ * <li><p> Two opaque URIs with identical schemes are ordered according
1507+ * to the ordering of their scheme-specific parts. </p></li>
1508+ *
1509+ * <li><p> Two opaque URIs with identical schemes and scheme-specific
1510+ * parts are ordered according to the ordering of their
1511+ * fragments. </p></li>
1512+ *
1513+ * <li><p> Two hierarchical URIs with identical schemes are ordered
1514+ * according to the ordering of their authority components: </p>
1515+ *
1516+ * <ul type=disc>
1517+ *
1518+ * <li><p> If both authority components are server-based then the URIs
1519+ * are ordered according to their user-information components; if these
1520+ * components are identical then the URIs are ordered according to the
1521+ * ordering of their hosts, without regard to case; if the hosts are
1522+ * identical then the URIs are ordered according to the ordering of
1523+ * their ports. </p></li>
1524+ *
1525+ * <li><p> If one or both authority components are registry-based then
1526+ * the URIs are ordered according to the ordering of their authority
1527+ * components. </p></li>
1528+ *
1529+ * </ul></li>
1530+ *
1531+ * <li><p> Finally, two hierarchical URIs with identical schemes and
1532+ * authority components are ordered according to the ordering of their
1533+ * paths; if their paths are identical then they are ordered according to
1534+ * the ordering of their queries; if the queries are identical then they
1535+ * are ordered according to the order of their fragments. </p></li>
1536+ *
1537+ * </ul>
1538+ *
1539+ * <p> This method satisfies the general contract of the {@link
1540+ * java.lang.Comparable#compareTo(Object) Comparable.compareTo}
1541+ * method. </p>
1542+ *
1543+ * @param that
1544+ * The object to which this URI is to be compared
1545+ *
1546+ * @return A negative integer, zero, or a positive integer as this URI is
1547+ * less than, equal to, or greater than the given URI
1548+ *
1549+ * @throws ClassCastException
1550+ * If the given object is not a URI
1551+ */
1552+ public int compareTo(URI that) {
1553+ int c;
1554+
1555+ if ((c = compareIgnoringCase(this.scheme, that.scheme)) != 0)
1556+ return c;
1557+
1558+ if (this.isOpaque()) {
1559+ if (that.isOpaque()) {
1560+ // Both opaque
1561+ if ((c = compare(this.schemeSpecificPart,
1562+ that.schemeSpecificPart)) != 0)
1563+ return c;
1564+ return compare(this.fragment, that.fragment);
1565+ }
1566+ return +1; // Opaque > hierarchical
1567+ } else if (that.isOpaque()) {
1568+ return -1; // Hierarchical < opaque
1569+ }
1570+
1571+ // Hierarchical
1572+ if ((this.host != null) && (that.host != null)) {
1573+ // Both server-based
1574+ if ((c = compare(this.userInfo, that.userInfo)) != 0)
1575+ return c;
1576+ if ((c = compareIgnoringCase(this.host, that.host)) != 0)
1577+ return c;
1578+ if ((c = this.port - that.port) != 0)
1579+ return c;
1580+ } else {
1581+ // If one or both authorities are registry-based then we simply
1582+ // compare them in the usual, case-sensitive way. If one is
1583+ // registry-based and one is server-based then the strings are
1584+ // guaranteed to be unequal, hence the comparison will never return
1585+ // zero and the compareTo and equals methods will remain
1586+ // consistent.
1587+ if ((c = compare(this.authority, that.authority)) != 0) return c;
1588+ }
1589+
1590+ if ((c = compare(this.path, that.path)) != 0) return c;
1591+ if ((c = compare(this.query, that.query)) != 0) return c;
1592+ return compare(this.fragment, that.fragment);
1593+ }
1594+
1595+ /**
1596+ * Returns the content of this URI as a string.
1597+ *
1598+ * <p> If this URI was created by invoking one of the constructors in this
1599+ * class then a string equivalent to the original input string, or to the
1600+ * string computed from the originally-given components, as appropriate, is
1601+ * returned. Otherwise this URI was created by normalization, resolution,
1602+ * or relativization, and so a string is constructed from this URI's
1603+ * components according to the rules specified in <a
1604+ * href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a>,
1605+ * section&nbsp;5.2, step&nbsp;7. </p>
1606+ *
1607+ * @return The string form of this URI
1608+ */
1609+ public String toString() {
1610+ defineString();
1611+ return string;
1612+ }
1613+
1614+ /**
1615+ * Returns the content of this URI as a US-ASCII string.
1616+ *
1617+ * <p> If this URI does not contain any characters in the <i>other</i>
1618+ * category then an invocation of this method will return the same value as
1619+ * an invocation of the {@link #toString() toString} method. Otherwise
1620+ * this method works as if by invoking that method and then <a
1621+ * href="#encode">encoding</a> the result. </p>
1622+ *
1623+ * @return The string form of this URI, encoded as needed
1624+ * so that it only contains characters in the US-ASCII
1625+ * charset
1626+ */
1627+ public String toASCIIString() {
1628+ defineString();
1629+ return encode(string);
1630+ }
1631+
1632+
1633+ // -- Serialization support --
1634+
1635+ /**
1636+ * Saves the content of this URI to the given serial stream.
1637+ *
1638+ * <p> The only serializable field of a URI instance is its <tt>string</tt>
1639+ * field. That field is given a value, if it does not have one already,
1640+ * and then the {@link java.io.ObjectOutputStream#defaultWriteObject()}
1641+ * method of the given object-output stream is invoked. </p>
1642+ *
1643+ * @param os The object-output stream to which this object
1644+ * is to be written
1645+ */
1646+ private void writeObject(ObjectOutputStream os)
1647+ throws IOException
1648+ {
1649+ defineString();
1650+ os.defaultWriteObject(); // Writes the string field only
1651+ }
1652+
1653+ /**
1654+ * Reconstitutes a URI from the given serial stream.
1655+ *
1656+ * <p> The {@link java.io.ObjectInputStream#defaultReadObject()} method is
1657+ * invoked to read the value of the <tt>string</tt> field. The result is
1658+ * then parsed in the usual way.
1659+ *
1660+ * @param is The object-input stream from which this object
1661+ * is being read
1662+ */
1663+ private void readObject(ObjectInputStream is)
1664+ throws ClassNotFoundException, IOException
1665+ {
1666+ port = -1; // Argh
1667+ is.defaultReadObject();
1668+ try {
1669+ new Parser(string).parse(false);
1670+ } catch (URISyntaxException x) {
1671+ IOException y = new InvalidObjectException("Invalid URI");
1672+ y.initCause(x);
1673+ throw y;
1674+ }
1675+ }
1676+
1677+
1678+ // -- End of public methods --
1679+
1680+
1681+ // -- Utility methods for string-field comparison and hashing --
1682+
1683+ // These methods return appropriate values for null string arguments,
1684+ // thereby simplifying the equals, hashCode, and compareTo methods.
1685+ //
1686+ // The case-ignoring methods should only be applied to strings whose
1687+ // characters are all known to be US-ASCII. Because of this restriction,
1688+ // these methods are faster than the similar methods in the String class.
1689+
1690+ // US-ASCII only
1691+ private static int toLower(char c) {
1692+ if ((c >= 'A') && (c <= 'Z'))
1693+ return c + ('a' - 'A');
1694+ return c;
1695+ }
1696+
1697+ private static boolean equal(String s, String t) {
1698+ if (s == t) return true;
1699+ if ((s != null) && (t != null)) {
1700+ if (s.length() != t.length())
1701+ return false;
1702+ if (s.indexOf('%') < 0)
1703+ return s.equals(t);
1704+ int n = s.length();
1705+ for (int i = 0; i < n;) {
1706+ char c = s.charAt(i);
1707+ char d = t.charAt(i);
1708+ if (c != '%') {
1709+ if (c != d)
1710+ return false;
1711+ i++;
1712+ continue;
1713+ }
1714+ i++;
1715+ if (toLower(s.charAt(i)) != toLower(t.charAt(i)))
1716+ return false;
1717+ i++;
1718+ if (toLower(s.charAt(i)) != toLower(t.charAt(i)))
1719+ return false;
1720+ i++;
1721+ }
1722+ return true;
1723+ }
1724+ return false;
1725+ }
1726+
1727+ // US-ASCII only
1728+ private static boolean equalIgnoringCase(String s, String t) {
1729+ if (s == t) return true;
1730+ if ((s != null) && (t != null)) {
1731+ int n = s.length();
1732+ if (t.length() != n)
1733+ return false;
1734+ for (int i = 0; i < n; i++) {
1735+ if (toLower(s.charAt(i)) != toLower(t.charAt(i)))
1736+ return false;
1737+ }
1738+ return true;
1739+ }
1740+ return false;
1741+ }
1742+
1743+ private static int hash(int hash, String s) {
1744+ if (s == null) return hash;
1745+ return hash * 127 + s.hashCode();
1746+ }
1747+
1748+ // US-ASCII only
1749+ private static int hashIgnoringCase(int hash, String s) {
1750+ if (s == null) return hash;
1751+ int h = hash;
1752+ int n = s.length();
1753+ for (int i = 0; i < n; i++)
1754+ h = 31 * h + toLower(s.charAt(i));
1755+ return h;
1756+ }
1757+
1758+ private static int compare(String s, String t) {
1759+ if (s == t) return 0;
1760+ if (s != null) {
1761+ if (t != null)
1762+ return s.compareTo(t);
1763+ else
1764+ return +1;
1765+ } else {
1766+ return -1;
1767+ }
1768+ }
1769+
1770+ // US-ASCII only
1771+ private static int compareIgnoringCase(String s, String t) {
1772+ if (s == t) return 0;
1773+ if (s != null) {
1774+ if (t != null) {
1775+ int sn = s.length();
1776+ int tn = t.length();
1777+ int n = sn < tn ? sn : tn;
1778+ for (int i = 0; i < n; i++) {
1779+ int c = toLower(s.charAt(i)) - toLower(t.charAt(i));
1780+ if (c != 0)
1781+ return c;
1782+ }
1783+ return sn - tn;
1784+ }
1785+ return +1;
1786+ } else {
1787+ return -1;
1788+ }
1789+ }
1790+
1791+
1792+ // -- String construction --
1793+
1794+ // If a scheme is given then the path, if given, must be absolute
1795+ //
1796+ private static void checkPath(String s, String scheme, String path)
1797+ throws URISyntaxException
1798+ {
1799+ if (scheme != null) {
1800+ if ((path != null)
1801+ && ((path.length() > 0) && (path.charAt(0) != '/')))
1802+ throw new URISyntaxException(s,
1803+ "Relative path in absolute URI");
1804+ }
1805+ }
1806+
1807+ private void appendAuthority(StringBuffer sb,
1808+ String authority,
1809+ String userInfo,
1810+ String host,
1811+ int port)
1812+ {
1813+ if (host != null) {
1814+ sb.append("//");
1815+ if (userInfo != null) {
1816+ sb.append(quote(userInfo, L_USERINFO, H_USERINFO));
1817+ sb.append('@');
1818+ }
1819+ boolean needBrackets = ((host.indexOf(':') >= 0)
1820+ && !host.startsWith("[")
1821+ && !host.endsWith("]"));
1822+ if (needBrackets) sb.append('[');
1823+ sb.append(host);
1824+ if (needBrackets) sb.append(']');
1825+ if (port != -1) {
1826+ sb.append(':');
1827+ sb.append(port);
1828+ }
1829+ } else if (authority != null) {
1830+ sb.append("//");
1831+ if (authority.startsWith("[")) {
1832+ // authority should (but may not) contain an embedded IPv6 address
1833+ int end = authority.indexOf("]");
1834+ String doquote = authority, dontquote = "";
1835+ if (end != -1 && authority.indexOf(":") != -1) {
1836+ // the authority contains an IPv6 address
1837+ if (end == authority.length()) {
1838+ dontquote = authority;
1839+ doquote = "";
1840+ } else {
1841+ dontquote = authority.substring(0 , end + 1);
1842+ doquote = authority.substring(end + 1);
1843+ }
1844+ }
1845+ sb.append(dontquote);
1846+ sb.append(quote(doquote,
1847+ L_REG_NAME | L_SERVER,
1848+ H_REG_NAME | H_SERVER));
1849+ } else {
1850+ sb.append(quote(authority,
1851+ L_REG_NAME | L_SERVER,
1852+ H_REG_NAME | H_SERVER));
1853+ }
1854+ }
1855+ }
1856+
1857+ private void appendSchemeSpecificPart(StringBuffer sb,
1858+ String opaquePart,
1859+ String authority,
1860+ String userInfo,
1861+ String host,
1862+ int port,
1863+ String path,
1864+ String query)
1865+ {
1866+ if (opaquePart != null) {
1867+ /* check if SSP begins with an IPv6 address
1868+ * because we must not quote a literal IPv6 address
1869+ */
1870+ if (opaquePart.startsWith("//[")) {
1871+ int end = opaquePart.indexOf("]");
1872+ if (end != -1 && opaquePart.indexOf(":")!=-1) {
1873+ String doquote, dontquote;
1874+ if (end == opaquePart.length()) {
1875+ dontquote = opaquePart;
1876+ doquote = "";
1877+ } else {
1878+ dontquote = opaquePart.substring(0,end+1);
1879+ doquote = opaquePart.substring(end+1);
1880+ }
1881+ sb.append (dontquote);
1882+ sb.append(quote(doquote, L_URIC, H_URIC));
1883+ }
1884+ } else {
1885+ sb.append(quote(opaquePart, L_URIC, H_URIC));
1886+ }
1887+ } else {
1888+ appendAuthority(sb, authority, userInfo, host, port);
1889+ if (path != null)
1890+ sb.append(quote(path, L_PATH, H_PATH));
1891+ if (query != null) {
1892+ sb.append('?');
1893+ sb.append(quote(query, L_URIC, H_URIC));
1894+ }
1895+ }
1896+ }
1897+
1898+ private void appendFragment(StringBuffer sb, String fragment) {
1899+ if (fragment != null) {
1900+ sb.append('#');
1901+ sb.append(quote(fragment, L_URIC, H_URIC));
1902+ }
1903+ }
1904+
1905+ private String toString(String scheme,
1906+ String opaquePart,
1907+ String authority,
1908+ String userInfo,
1909+ String host,
1910+ int port,
1911+ String path,
1912+ String query,
1913+ String fragment)
1914+ {
1915+ StringBuffer sb = new StringBuffer();
1916+ if (scheme != null) {
1917+ sb.append(scheme);
1918+ sb.append(':');
1919+ }
1920+ appendSchemeSpecificPart(sb, opaquePart,
1921+ authority, userInfo, host, port,
1922+ path, query);
1923+ appendFragment(sb, fragment);
1924+ return sb.toString();
1925+ }
1926+
1927+ private void defineSchemeSpecificPart() {
1928+ if (schemeSpecificPart != null) return;
1929+ StringBuffer sb = new StringBuffer();
1930+ appendSchemeSpecificPart(sb, null, getAuthority(), getUserInfo(),
1931+ host, port, getPath(), getQuery());
1932+ if (sb.length() == 0) return;
1933+ schemeSpecificPart = sb.toString();
1934+ }
1935+
1936+ private void defineString() {
1937+ if (string != null) return;
1938+
1939+ StringBuffer sb = new StringBuffer();
1940+ if (scheme != null) {
1941+ sb.append(scheme);
1942+ sb.append(':');
1943+ }
1944+ if (isOpaque()) {
1945+ sb.append(schemeSpecificPart);
1946+ } else {
1947+ if (host != null) {
1948+ sb.append("//");
1949+ if (userInfo != null) {
1950+ sb.append(userInfo);
1951+ sb.append('@');
1952+ }
1953+ boolean needBrackets = ((host.indexOf(':') >= 0)
1954+ && !host.startsWith("[")
1955+ && !host.endsWith("]"));
1956+ if (needBrackets) sb.append('[');
1957+ sb.append(host);
1958+ if (needBrackets) sb.append(']');
1959+ if (port != -1) {
1960+ sb.append(':');
1961+ sb.append(port);
1962+ }
1963+ } else if (authority != null) {
1964+ sb.append("//");
1965+ sb.append(authority);
1966+ }
1967+ if (path != null)
1968+ sb.append(path);
1969+ if (query != null) {
1970+ sb.append('?');
1971+ sb.append(query);
1972+ }
1973+ }
1974+ if (fragment != null) {
1975+ sb.append('#');
1976+ sb.append(fragment);
1977+ }
1978+ string = sb.toString();
1979+ }
1980+
1981+
1982+ // -- Normalization, resolution, and relativization --
1983+
1984+ // RFC2396 5.2 (6)
1985+ private static String resolvePath(String base, String child,
1986+ boolean absolute)
1987+ {
1988+ int i = base.lastIndexOf('/');
1989+ int cn = child.length();
1990+ String path = "";
1991+
1992+ if (cn == 0) {
1993+ // 5.2 (6a)
1994+ if (i >= 0)
1995+ path = base.substring(0, i + 1);
1996+ } else {
1997+ StringBuffer sb = new StringBuffer(base.length() + cn);
1998+ // 5.2 (6a)
1999+ if (i >= 0)
2000+ sb.append(base.substring(0, i + 1));
2001+ // 5.2 (6b)
2002+ sb.append(child);
2003+ path = sb.toString();
2004+ }
2005+
2006+ // 5.2 (6c-f)
2007+ String np = normalize(path);
2008+
2009+ // 5.2 (6g): If the result is absolute but the path begins with "../",
2010+ // then we simply leave the path as-is
2011+
2012+ return np;
2013+ }
2014+
2015+ // RFC2396 5.2
2016+ private static URI resolve(URI base, URI child) {
2017+ // check if child if opaque first so that NPE is thrown
2018+ // if child is null.
2019+ if (child.isOpaque() || base.isOpaque())
2020+ return child;
2021+
2022+ // 5.2 (2): Reference to current document (lone fragment)
2023+ if ((child.scheme == null) && (child.authority == null)
2024+ && child.path.equals("") && (child.fragment != null)
2025+ && (child.query == null)) {
2026+ if ((base.fragment != null)
2027+ && child.fragment.equals(base.fragment)) {
2028+ return base;
2029+ }
2030+ URI ru = new URI();
2031+ ru.scheme = base.scheme;
2032+ ru.authority = base.authority;
2033+ ru.userInfo = base.userInfo;
2034+ ru.host = base.host;
2035+ ru.port = base.port;
2036+ ru.path = base.path;
2037+ ru.fragment = child.fragment;
2038+ ru.query = base.query;
2039+ return ru;
2040+ }
2041+
2042+ // 5.2 (3): Child is absolute
2043+ if (child.scheme != null)
2044+ return child;
2045+
2046+ URI ru = new URI(); // Resolved URI
2047+ ru.scheme = base.scheme;
2048+ ru.query = child.query;
2049+ ru.fragment = child.fragment;
2050+
2051+ // 5.2 (4): Authority
2052+ if (child.authority == null) {
2053+ ru.authority = base.authority;
2054+ ru.host = base.host;
2055+ ru.userInfo = base.userInfo;
2056+ ru.port = base.port;
2057+
2058+ String cp = (child.path == null) ? "" : child.path;
2059+ if ((cp.length() > 0) && (cp.charAt(0) == '/')) {
2060+ // 5.2 (5): Child path is absolute
2061+ ru.path = child.path;
2062+ } else {
2063+ // 5.2 (6): Resolve relative path
2064+ ru.path = resolvePath(base.path, cp, base.isAbsolute());
2065+ }
2066+ } else {
2067+ ru.authority = child.authority;
2068+ ru.host = child.host;
2069+ ru.userInfo = child.userInfo;
2070+ ru.host = child.host;
2071+ ru.port = child.port;
2072+ ru.path = child.path;
2073+ }
2074+
2075+ // 5.2 (7): Recombine (nothing to do here)
2076+ return ru;
2077+ }
2078+
2079+ // If the given URI's path is normal then return the URI;
2080+ // o.w., return a new URI containing the normalized path.
2081+ //
2082+ private static URI normalize(URI u) {
2083+ if (u.isOpaque() || (u.path == null) || (u.path.length() == 0))
2084+ return u;
2085+
2086+ String np = normalize(u.path);
2087+ if (np == u.path)
2088+ return u;
2089+
2090+ URI v = new URI();
2091+ v.scheme = u.scheme;
2092+ v.fragment = u.fragment;
2093+ v.authority = u.authority;
2094+ v.userInfo = u.userInfo;
2095+ v.host = u.host;
2096+ v.port = u.port;
2097+ v.path = np;
2098+ v.query = u.query;
2099+ return v;
2100+ }
2101+
2102+ // If both URIs are hierarchical, their scheme and authority components are
2103+ // identical, and the base path is a prefix of the child's path, then
2104+ // return a relative URI that, when resolved against the base, yields the
2105+ // child; otherwise, return the child.
2106+ //
2107+ private static URI relativize(URI base, URI child) {
2108+ // check if child if opaque first so that NPE is thrown
2109+ // if child is null.
2110+ if (child.isOpaque() || base.isOpaque())
2111+ return child;
2112+ if (!equalIgnoringCase(base.scheme, child.scheme)
2113+ || !equal(base.authority, child.authority))
2114+ return child;
2115+
2116+ String bp = normalize(base.path);
2117+ String cp = normalize(child.path);
2118+ if (!bp.equals(cp)) {
2119+ if (!bp.endsWith("/"))
2120+ bp = bp + "/";
2121+ if (!cp.startsWith(bp))
2122+ return child;
2123+ }
2124+
2125+ URI v = new URI();
2126+ v.path = cp.substring(bp.length());
2127+ v.query = child.query;
2128+ v.fragment = child.fragment;
2129+ return v;
2130+ }
2131+
2132+
2133+
2134+ // -- Path normalization --
2135+
2136+ // The following algorithm for path normalization avoids the creation of a
2137+ // string object for each segment, as well as the use of a string buffer to
2138+ // compute the final result, by using a single char array and editing it in
2139+ // place. The array is first split into segments, replacing each slash
2140+ // with '\0' and creating a segment-index array, each element of which is
2141+ // the index of the first char in the corresponding segment. We then walk
2142+ // through both arrays, removing ".", "..", and other segments as necessary
2143+ // by setting their entries in the index array to -1. Finally, the two
2144+ // arrays are used to rejoin the segments and compute the final result.
2145+ //
2146+ // This code is based upon src/solaris/native/java/io/canonicalize_md.c
2147+
2148+
2149+ // Check the given path to see if it might need normalization. A path
2150+ // might need normalization if it contains duplicate slashes, a "."
2151+ // segment, or a ".." segment. Return -1 if no further normalization is
2152+ // possible, otherwise return the number of segments found.
2153+ //
2154+ // This method takes a string argument rather than a char array so that
2155+ // this test can be performed without invoking path.toCharArray().
2156+ //
2157+ static private int needsNormalization(String path) {
2158+ boolean normal = true;
2159+ int ns = 0; // Number of segments
2160+ int end = path.length() - 1; // Index of last char in path
2161+ int p = 0; // Index of next char in path
2162+
2163+ // Skip initial slashes
2164+ while (p <= end) {
2165+ if (path.charAt(p) != '/') break;
2166+ p++;
2167+ }
2168+ if (p > 1) normal = false;
2169+
2170+ // Scan segments
2171+ while (p <= end) {
2172+
2173+ // Looking at "." or ".." ?
2174+ if ((path.charAt(p) == '.')
2175+ && ((p == end)
2176+ || ((path.charAt(p + 1) == '/')
2177+ || ((path.charAt(p + 1) == '.')
2178+ && ((p + 1 == end)
2179+ || (path.charAt(p + 2) == '/')))))) {
2180+ normal = false;
2181+ }
2182+ ns++;
2183+
2184+ // Find beginning of next segment
2185+ while (p <= end) {
2186+ if (path.charAt(p++) != '/')
2187+ continue;
2188+
2189+ // Skip redundant slashes
2190+ while (p <= end) {
2191+ if (path.charAt(p) != '/') break;
2192+ normal = false;
2193+ p++;
2194+ }
2195+
2196+ break;
2197+ }
2198+ }
2199+
2200+ return normal ? -1 : ns;
2201+ }
2202+
2203+
2204+ // Split the given path into segments, replacing slashes with nulls and
2205+ // filling in the given segment-index array.
2206+ //
2207+ // Preconditions:
2208+ // segs.length == Number of segments in path
2209+ //
2210+ // Postconditions:
2211+ // All slashes in path replaced by '\0'
2212+ // segs[i] == Index of first char in segment i (0 <= i < segs.length)
2213+ //
2214+ static private void split(char[] path, int[] segs) {
2215+ int end = path.length - 1; // Index of last char in path
2216+ int p = 0; // Index of next char in path
2217+ int i = 0; // Index of current segment
2218+
2219+ // Skip initial slashes
2220+ while (p <= end) {
2221+ if (path[p] != '/') break;
2222+ path[p] = '\0';
2223+ p++;
2224+ }
2225+
2226+ while (p <= end) {
2227+
2228+ // Note start of segment
2229+ segs[i++] = p++;
2230+
2231+ // Find beginning of next segment
2232+ while (p <= end) {
2233+ if (path[p++] != '/')
2234+ continue;
2235+ path[p - 1] = '\0';
2236+
2237+ // Skip redundant slashes
2238+ while (p <= end) {
2239+ if (path[p] != '/') break;
2240+ path[p++] = '\0';
2241+ }
2242+ break;
2243+ }
2244+ }
2245+
2246+ if (i != segs.length)
2247+ throw new InternalError(); // ASSERT
2248+ }
2249+
2250+
2251+ // Join the segments in the given path according to the given segment-index
2252+ // array, ignoring those segments whose index entries have been set to -1,
2253+ // and inserting slashes as needed. Return the length of the resulting
2254+ // path.
2255+ //
2256+ // Preconditions:
2257+ // segs[i] == -1 implies segment i is to be ignored
2258+ // path computed by split, as above, with '\0' having replaced '/'
2259+ //
2260+ // Postconditions:
2261+ // path[0] .. path[return value] == Resulting path
2262+ //
2263+ static private int join(char[] path, int[] segs) {
2264+ int ns = segs.length; // Number of segments
2265+ int end = path.length - 1; // Index of last char in path
2266+ int p = 0; // Index of next path char to write
2267+
2268+ if (path[p] == '\0') {
2269+ // Restore initial slash for absolute paths
2270+ path[p++] = '/';
2271+ }
2272+
2273+ for (int i = 0; i < ns; i++) {
2274+ int q = segs[i]; // Current segment
2275+ if (q == -1)
2276+ // Ignore this segment
2277+ continue;
2278+
2279+ if (p == q) {
2280+ // We're already at this segment, so just skip to its end
2281+ while ((p <= end) && (path[p] != '\0'))
2282+ p++;
2283+ if (p <= end) {
2284+ // Preserve trailing slash
2285+ path[p++] = '/';
2286+ }
2287+ } else if (p < q) {
2288+ // Copy q down to p
2289+ while ((q <= end) && (path[q] != '\0'))
2290+ path[p++] = path[q++];
2291+ if (q <= end) {
2292+ // Preserve trailing slash
2293+ path[p++] = '/';
2294+ }
2295+ } else
2296+ throw new InternalError(); // ASSERT false
2297+ }
2298+
2299+ return p;
2300+ }
2301+
2302+
2303+ // Remove "." segments from the given path, and remove segment pairs
2304+ // consisting of a non-".." segment followed by a ".." segment.
2305+ //
2306+ private static void removeDots(char[] path, int[] segs) {
2307+ int ns = segs.length;
2308+ int end = path.length - 1;
2309+
2310+ for (int i = 0; i < ns; i++) {
2311+ int dots = 0; // Number of dots found (0, 1, or 2)
2312+
2313+ // Find next occurrence of "." or ".."
2314+ do {
2315+ int p = segs[i];
2316+ if (path[p] == '.') {
2317+ if (p == end) {
2318+ dots = 1;
2319+ break;
2320+ } else if (path[p + 1] == '\0') {
2321+ dots = 1;
2322+ break;
2323+ } else if ((path[p + 1] == '.')
2324+ && ((p + 1 == end)
2325+ || (path[p + 2] == '\0'))) {
2326+ dots = 2;
2327+ break;
2328+ }
2329+ }
2330+ i++;
2331+ } while (i < ns);
2332+ if ((i > ns) || (dots == 0))
2333+ break;
2334+
2335+ if (dots == 1) {
2336+ // Remove this occurrence of "."
2337+ segs[i] = -1;
2338+ } else {
2339+ // If there is a preceding non-".." segment, remove both that
2340+ // segment and this occurrence of ".."; otherwise, leave this
2341+ // ".." segment as-is.
2342+ int j;
2343+ for (j = i - 1; j >= 0; j--) {
2344+ if (segs[j] != -1) break;
2345+ }
2346+ if (j >= 0) {
2347+ int q = segs[j];
2348+ if (!((path[q] == '.')
2349+ && (path[q + 1] == '.')
2350+ && (path[q + 2] == '\0'))) {
2351+ segs[i] = -1;
2352+ segs[j] = -1;
2353+ }
2354+ }
2355+ }
2356+ }
2357+ }
2358+
2359+
2360+ // DEVIATION: If the normalized path is relative, and if the first
2361+ // segment could be parsed as a scheme name, then prepend a "." segment
2362+ //
2363+ private static void maybeAddLeadingDot(char[] path, int[] segs) {
2364+
2365+ if (path[0] == '\0')
2366+ // The path is absolute
2367+ return;
2368+
2369+ int ns = segs.length;
2370+ int f = 0; // Index of first segment
2371+ while (f < ns) {
2372+ if (segs[f] >= 0)
2373+ break;
2374+ f++;
2375+ }
2376+ if ((f >= ns) || (f == 0))
2377+ // The path is empty, or else the original first segment survived,
2378+ // in which case we already know that no leading "." is needed
2379+ return;
2380+
2381+ int p = segs[f];
2382+ while ((p < path.length) && (path[p] != ':') && (path[p] != '\0')) p++;
2383+ if (p >= path.length || path[p] == '\0')
2384+ // No colon in first segment, so no "." needed
2385+ return;
2386+
2387+ // At this point we know that the first segment is unused,
2388+ // hence we can insert a "." segment at that position
2389+ path[0] = '.';
2390+ path[1] = '\0';
2391+ segs[0] = 0;
2392+ }
2393+
2394+
2395+ // Normalize the given path string. A normal path string has no empty
2396+ // segments (i.e., occurrences of "//"), no segments equal to ".", and no
2397+ // segments equal to ".." that are preceded by a segment not equal to "..".
2398+ // In contrast to Unix-style pathname normalization, for URI paths we
2399+ // always retain trailing slashes.
2400+ //
2401+ private static String normalize(String ps) {
2402+
2403+ // Does this path need normalization?
2404+ int ns = needsNormalization(ps); // Number of segments
2405+ if (ns < 0)
2406+ // Nope -- just return it
2407+ return ps;
2408+
2409+ char[] path = ps.toCharArray(); // Path in char-array form
2410+
2411+ // Split path into segments
2412+ int[] segs = new int[ns]; // Segment-index array
2413+ split(path, segs);
2414+
2415+ // Remove dots
2416+ removeDots(path, segs);
2417+
2418+ // Prevent scheme-name confusion
2419+ maybeAddLeadingDot(path, segs);
2420+
2421+ // Join the remaining segments and return the result
2422+ String s = new String(path, 0, join(path, segs));
2423+ if (s.equals(ps)) {
2424+ // string was already normalized
2425+ return ps;
2426+ }
2427+ return s;
2428+ }
2429+
2430+
2431+
2432+ // -- Character classes for parsing --
2433+
2434+ // RFC2396 precisely specifies which characters in the US-ASCII charset are
2435+ // permissible in the various components of a URI reference. We here
2436+ // define a set of mask pairs to aid in enforcing these restrictions. Each
2437+ // mask pair consists of two longs, a low mask and a high mask. Taken
2438+ // together they represent a 128-bit mask, where bit i is set iff the
2439+ // character with value i is permitted.
2440+ //
2441+ // This approach is more efficient than sequentially searching arrays of
2442+ // permitted characters. It could be made still more efficient by
2443+ // precompiling the mask information so that a character's presence in a
2444+ // given mask could be determined by a single table lookup.
2445+
2446+ // Compute the low-order mask for the characters in the given string
2447+ private static long lowMask(String chars) {
2448+ int n = chars.length();
2449+ long m = 0;
2450+ for (int i = 0; i < n; i++) {
2451+ char c = chars.charAt(i);
2452+ if (c < 64)
2453+ m |= (1L << c);
2454+ }
2455+ return m;
2456+ }
2457+
2458+ // Compute the high-order mask for the characters in the given string
2459+ private static long highMask(String chars) {
2460+ int n = chars.length();
2461+ long m = 0;
2462+ for (int i = 0; i < n; i++) {
2463+ char c = chars.charAt(i);
2464+ if ((c >= 64) && (c < 128))
2465+ m |= (1L << (c - 64));
2466+ }
2467+ return m;
2468+ }
2469+
2470+ // Compute a low-order mask for the characters
2471+ // between first and last, inclusive
2472+ private static long lowMask(char first, char last) {
2473+ long m = 0;
2474+ int f = Math.max(Math.min(first, 63), 0);
2475+ int l = Math.max(Math.min(last, 63), 0);
2476+ for (int i = f; i <= l; i++)
2477+ m |= 1L << i;
2478+ return m;
2479+ }
2480+
2481+ // Compute a high-order mask for the characters
2482+ // between first and last, inclusive
2483+ private static long highMask(char first, char last) {
2484+ long m = 0;
2485+ int f = Math.max(Math.min(first, 127), 64) - 64;
2486+ int l = Math.max(Math.min(last, 127), 64) - 64;
2487+ for (int i = f; i <= l; i++)
2488+ m |= 1L << i;
2489+ return m;
2490+ }
2491+
2492+ // Tell whether the given character is permitted by the given mask pair
2493+ private static boolean match(char c, long lowMask, long highMask) {
2494+ if (c == 0) // 0 doesn't have a slot in the mask. So, it never matches.
2495+ return false;
2496+ if (c < 64)
2497+ return ((1L << c) & lowMask) != 0;
2498+ if (c < 128)
2499+ return ((1L << (c - 64)) & highMask) != 0;
2500+ return false;
2501+ }
2502+
2503+ // Character-class masks, in reverse order from RFC2396 because
2504+ // initializers for static fields cannot make forward references.
2505+
2506+ // digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
2507+ // "8" | "9"
2508+ private static final long L_DIGIT = lowMask('0', '9');
2509+ private static final long H_DIGIT = 0L;
2510+
2511+ // upalpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" |
2512+ // "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" |
2513+ // "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
2514+ private static final long L_UPALPHA = 0L;
2515+ private static final long H_UPALPHA = highMask('A', 'Z');
2516+
2517+ // lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" |
2518+ // "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" |
2519+ // "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"
2520+ private static final long L_LOWALPHA = 0L;
2521+ private static final long H_LOWALPHA = highMask('a', 'z');
2522+
2523+ // alpha = lowalpha | upalpha
2524+ private static final long L_ALPHA = L_LOWALPHA | L_UPALPHA;
2525+ private static final long H_ALPHA = H_LOWALPHA | H_UPALPHA;
2526+
2527+ // alphanum = alpha | digit
2528+ private static final long L_ALPHANUM = L_DIGIT | L_ALPHA;
2529+ private static final long H_ALPHANUM = H_DIGIT | H_ALPHA;
2530+
2531+ // hex = digit | "A" | "B" | "C" | "D" | "E" | "F" |
2532+ // "a" | "b" | "c" | "d" | "e" | "f"
2533+ private static final long L_HEX = L_DIGIT;
2534+ private static final long H_HEX = highMask('A', 'F') | highMask('a', 'f');
2535+
2536+ // mark = "-" | "_" | "." | "!" | "~" | "*" | "'" |
2537+ // "(" | ")"
2538+ private static final long L_MARK = lowMask("-_.!~*'()");
2539+ private static final long H_MARK = highMask("-_.!~*'()");
2540+
2541+ // unreserved = alphanum | mark
2542+ private static final long L_UNRESERVED = L_ALPHANUM | L_MARK;
2543+ private static final long H_UNRESERVED = H_ALPHANUM | H_MARK;
2544+
2545+ // reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" |
2546+ // "$" | "," | "[" | "]"
2547+ // Added per RFC2732: "[", "]"
2548+ private static final long L_RESERVED = lowMask(";/?:@&=+$,[]");
2549+ private static final long H_RESERVED = highMask(";/?:@&=+$,[]");
2550+
2551+ // The zero'th bit is used to indicate that escape pairs and non-US-ASCII
2552+ // characters are allowed; this is handled by the scanEscape method below.
2553+ private static final long L_ESCAPED = 1L;
2554+ private static final long H_ESCAPED = 0L;
2555+
2556+ // uric = reserved | unreserved | escaped
2557+ private static final long L_URIC = L_RESERVED | L_UNRESERVED | L_ESCAPED;
2558+ private static final long H_URIC = H_RESERVED | H_UNRESERVED | H_ESCAPED;
2559+
2560+ // pchar = unreserved | escaped |
2561+ // ":" | "@" | "&" | "=" | "+" | "$" | ","
2562+ private static final long L_PCHAR
2563+ = L_UNRESERVED | L_ESCAPED | lowMask(":@&=+$,");
2564+ private static final long H_PCHAR
2565+ = H_UNRESERVED | H_ESCAPED | highMask(":@&=+$,");
2566+
2567+ // All valid path characters
2568+ private static final long L_PATH = L_PCHAR | lowMask(";/");
2569+ private static final long H_PATH = H_PCHAR | highMask(";/");
2570+
2571+ // Dash, for use in domainlabel and toplabel
2572+ private static final long L_DASH = lowMask("-");
2573+ private static final long H_DASH = highMask("-");
2574+
2575+ // Dot, for use in hostnames
2576+ private static final long L_DOT = lowMask(".");
2577+ private static final long H_DOT = highMask(".");
2578+
2579+ // userinfo = *( unreserved | escaped |
2580+ // ";" | ":" | "&" | "=" | "+" | "$" | "," )
2581+ private static final long L_USERINFO
2582+ = L_UNRESERVED | L_ESCAPED | lowMask(";:&=+$,");
2583+ private static final long H_USERINFO
2584+ = H_UNRESERVED | H_ESCAPED | highMask(";:&=+$,");
2585+
2586+ // reg_name = 1*( unreserved | escaped | "$" | "," |
2587+ // ";" | ":" | "@" | "&" | "=" | "+" )
2588+ private static final long L_REG_NAME
2589+ = L_UNRESERVED | L_ESCAPED | lowMask("$,;:@&=+");
2590+ private static final long H_REG_NAME
2591+ = H_UNRESERVED | H_ESCAPED | highMask("$,;:@&=+");
2592+
2593+ // All valid characters for server-based authorities
2594+ private static final long L_SERVER
2595+ = L_USERINFO | L_ALPHANUM | L_DASH | lowMask(".:@[]");
2596+ private static final long H_SERVER
2597+ = H_USERINFO | H_ALPHANUM | H_DASH | highMask(".:@[]");
2598+
2599+ // Special case of server authority that represents an IPv6 address
2600+ // In this case, a % does not signify an escape sequence
2601+ private static final long L_SERVER_PERCENT
2602+ = L_SERVER | lowMask("%");
2603+ private static final long H_SERVER_PERCENT
2604+ = H_SERVER | highMask("%");
2605+ private static final long L_LEFT_BRACKET = lowMask("[");
2606+ private static final long H_LEFT_BRACKET = highMask("[");
2607+
2608+ // scheme = alpha *( alpha | digit | "+" | "-" | "." )
2609+ private static final long L_SCHEME = L_ALPHA | L_DIGIT | lowMask("+-.");
2610+ private static final long H_SCHEME = H_ALPHA | H_DIGIT | highMask("+-.");
2611+
2612+ // uric_no_slash = unreserved | escaped | ";" | "?" | ":" | "@" |
2613+ // "&" | "=" | "+" | "$" | ","
2614+ private static final long L_URIC_NO_SLASH
2615+ = L_UNRESERVED | L_ESCAPED | lowMask(";?:@&=+$,");
2616+ private static final long H_URIC_NO_SLASH
2617+ = H_UNRESERVED | H_ESCAPED | highMask(";?:@&=+$,");
2618+
2619+
2620+ // -- Escaping and encoding --
2621+
2622+ private final static char[] hexDigits = {
2623+ '0', '1', '2', '3', '4', '5', '6', '7',
2624+ '8', '9', 'A', 'B', 'C', 'D', 'E', 'F'
2625+ };
2626+
2627+ private static void appendEscape(StringBuffer sb, byte b) {
2628+ sb.append('%');
2629+ sb.append(hexDigits[(b >> 4) & 0x0f]);
2630+ sb.append(hexDigits[(b >> 0) & 0x0f]);
2631+ }
2632+
2633+ private static void appendEncoded(StringBuffer sb, char c) {
2634+ ByteBuffer bb = null;
2635+ try {
2636+ bb = ThreadLocalCoders.encoderFor("UTF-8")
2637+ .encode(CharBuffer.wrap("" + c));
2638+ } catch (CharacterCodingException x) {
2639+ assert false;
2640+ }
2641+ while (bb.hasRemaining()) {
2642+ int b = bb.get() & 0xff;
2643+ if (b >= 0x80)
2644+ appendEscape(sb, (byte)b);
2645+ else
2646+ sb.append((char)b);
2647+ }
2648+ }
2649+
2650+ // Quote any characters in s that are not permitted
2651+ // by the given mask pair
2652+ //
2653+ private static String quote(String s, long lowMask, long highMask) {
2654+ int n = s.length();
2655+ StringBuffer sb = null;
2656+ boolean allowNonASCII = ((lowMask & L_ESCAPED) != 0);
2657+ for (int i = 0; i < s.length(); i++) {
2658+ char c = s.charAt(i);
2659+ if (c < '\u0080') {
2660+ if (!match(c, lowMask, highMask)) {
2661+ if (sb == null) {
2662+ sb = new StringBuffer();
2663+ sb.append(s.substring(0, i));
2664+ }
2665+ appendEscape(sb, (byte)c);
2666+ } else {
2667+ if (sb != null)
2668+ sb.append(c);
2669+ }
2670+ } else if (allowNonASCII
2671+ && (Character.isSpaceChar(c)
2672+ || Character.isISOControl(c))) {
2673+ if (sb == null) {
2674+ sb = new StringBuffer();
2675+ sb.append(s.substring(0, i));
2676+ }
2677+ appendEncoded(sb, c);
2678+ } else {
2679+ if (sb != null)
2680+ sb.append(c);
2681+ }
2682+ }
2683+ return (sb == null) ? s : sb.toString();
2684+ }
2685+
2686+ // Encodes all characters >= \u0080 into escaped, normalized UTF-8 octets,
2687+ // assuming that s is otherwise legal
2688+ //
2689+ private static String encode(String s) {
2690+ int n = s.length();
2691+ if (n == 0)
2692+ return s;
2693+
2694+ // First check whether we actually need to encode
2695+ for (int i = 0;;) {
2696+ if (s.charAt(i) >= '\u0080')
2697+ break;
2698+ if (++i >= n)
2699+ return s;
2700+ }
2701+
2702+ String ns = Normalizer.normalize(s, Normalizer.Form.NFC);
2703+ ByteBuffer bb = null;
2704+ try {
2705+ bb = ThreadLocalCoders.encoderFor("UTF-8")
2706+ .encode(CharBuffer.wrap(ns));
2707+ } catch (CharacterCodingException x) {
2708+ assert false;
2709+ }
2710+
2711+ StringBuffer sb = new StringBuffer();
2712+ while (bb.hasRemaining()) {
2713+ int b = bb.get() & 0xff;
2714+ if (b >= 0x80)
2715+ appendEscape(sb, (byte)b);
2716+ else
2717+ sb.append((char)b);
2718+ }
2719+ return sb.toString();
2720+ }
2721+
2722+ private static int decode(char c) {
2723+ if ((c >= '0') && (c <= '9'))
2724+ return c - '0';
2725+ if ((c >= 'a') && (c <= 'f'))
2726+ return c - 'a' + 10;
2727+ if ((c >= 'A') && (c <= 'F'))
2728+ return c - 'A' + 10;
2729+ assert false;
2730+ return -1;
2731+ }
2732+
2733+ private static byte decode(char c1, char c2) {
2734+ return (byte)( ((decode(c1) & 0xf) << 4)
2735+ | ((decode(c2) & 0xf) << 0));
2736+ }
2737+
2738+ // Evaluates all escapes in s, applying UTF-8 decoding if needed. Assumes
2739+ // that escapes are well-formed syntactically, i.e., of the form %XX. If a
2740+ // sequence of escaped octets is not valid UTF-8 then the erroneous octets
2741+ // are replaced with '\uFFFD'.
2742+ // Exception: any "%" found between "[]" is left alone. It is an IPv6 literal
2743+ // with a scope_id
2744+ //
2745+ private static String decode(String s) {
2746+ if (s == null)
2747+ return s;
2748+ int n = s.length();
2749+ if (n == 0)
2750+ return s;
2751+ if (s.indexOf('%') < 0)
2752+ return s;
2753+
2754+ StringBuffer sb = new StringBuffer(n);
2755+ ByteBuffer bb = ByteBuffer.allocate(n);
2756+ CharBuffer cb = CharBuffer.allocate(n);
2757+ CharsetDecoder dec = ThreadLocalCoders.decoderFor("UTF-8")
2758+ .onMalformedInput(CodingErrorAction.REPLACE)
2759+ .onUnmappableCharacter(CodingErrorAction.REPLACE);
2760+
2761+ // This is not horribly efficient, but it will do for now
2762+ char c = s.charAt(0);
2763+ boolean betweenBrackets = false;
2764+
2765+ for (int i = 0; i < n;) {
2766+ assert c == s.charAt(i); // Loop invariant
2767+ if (c == '[') {
2768+ betweenBrackets = true;
2769+ } else if (betweenBrackets && c == ']') {
2770+ betweenBrackets = false;
2771+ }
2772+ if (c != '%' || betweenBrackets) {
2773+ sb.append(c);
2774+ if (++i >= n)
2775+ break;
2776+ c = s.charAt(i);
2777+ continue;
2778+ }
2779+ bb.clear();
2780+ int ui = i;
2781+ for (;;) {
2782+ assert (n - i >= 2);
2783+ bb.put(decode(s.charAt(++i), s.charAt(++i)));
2784+ if (++i >= n)
2785+ break;
2786+ c = s.charAt(i);
2787+ if (c != '%')
2788+ break;
2789+ }
2790+ bb.flip();
2791+ cb.clear();
2792+ dec.reset();
2793+ CoderResult cr = dec.decode(bb, cb, true);
2794+ assert cr.isUnderflow();
2795+ cr = dec.flush(cb);
2796+ assert cr.isUnderflow();
2797+ sb.append(cb.flip().toString());
2798+ }
2799+
2800+ return sb.toString();
2801+ }
2802+
2803+
2804+ // -- Parsing --
2805+
2806+ // For convenience we wrap the input URI string in a new instance of the
2807+ // following internal class. This saves always having to pass the input
2808+ // string as an argument to each internal scan/parse method.
2809+
2810+ private class Parser {
2811+
2812+ private String input; // URI input string
2813+ private boolean requireServerAuthority = false;
2814+
2815+ Parser(String s) {
2816+ input = s;
2817+ string = s;
2818+ }
2819+
2820+ // -- Methods for throwing URISyntaxException in various ways --
2821+
2822+ private void fail(String reason) throws URISyntaxException {
2823+ throw new URISyntaxException(input, reason);
2824+ }
2825+
2826+ private void fail(String reason, int p) throws URISyntaxException {
2827+ throw new URISyntaxException(input, reason, p);
2828+ }
2829+
2830+ private void failExpecting(String expected, int p)
2831+ throws URISyntaxException
2832+ {
2833+ fail("Expected " + expected, p);
2834+ }
2835+
2836+ private void failExpecting(String expected, String prior, int p)
2837+ throws URISyntaxException
2838+ {
2839+ fail("Expected " + expected + " following " + prior, p);
2840+ }
2841+
2842+
2843+ // -- Simple access to the input string --
2844+
2845+ // Return a substring of the input string
2846+ //
2847+ private String substring(int start, int end) {
2848+ return input.substring(start, end);
2849+ }
2850+
2851+ // Return the char at position p,
2852+ // assuming that p < input.length()
2853+ //
2854+ private char charAt(int p) {
2855+ return input.charAt(p);
2856+ }
2857+
2858+ // Tells whether start < end and, if so, whether charAt(start) == c
2859+ //
2860+ private boolean at(int start, int end, char c) {
2861+ return (start < end) && (charAt(start) == c);
2862+ }
2863+
2864+ // Tells whether start + s.length() < end and, if so,
2865+ // whether the chars at the start position match s exactly
2866+ //
2867+ private boolean at(int start, int end, String s) {
2868+ int p = start;
2869+ int sn = s.length();
2870+ if (sn > end - p)
2871+ return false;
2872+ int i = 0;
2873+ while (i < sn) {
2874+ if (charAt(p++) != s.charAt(i)) {
2875+ break;
2876+ }
2877+ i++;
2878+ }
2879+ return (i == sn);
2880+ }
2881+
2882+
2883+ // -- Scanning --
2884+
2885+ // The various scan and parse methods that follow use a uniform
2886+ // convention of taking the current start position and end index as
2887+ // their first two arguments. The start is inclusive while the end is
2888+ // exclusive, just as in the String class, i.e., a start/end pair
2889+ // denotes the left-open interval [start, end) of the input string.
2890+ //
2891+ // These methods never proceed past the end position. They may return
2892+ // -1 to indicate outright failure, but more often they simply return
2893+ // the position of the first char after the last char scanned. Thus
2894+ // a typical idiom is
2895+ //
2896+ // int p = start;
2897+ // int q = scan(p, end, ...);
2898+ // if (q > p)
2899+ // // We scanned something
2900+ // ...;
2901+ // else if (q == p)
2902+ // // We scanned nothing
2903+ // ...;
2904+ // else if (q == -1)
2905+ // // Something went wrong
2906+ // ...;
2907+
2908+
2909+ // Scan a specific char: If the char at the given start position is
2910+ // equal to c, return the index of the next char; otherwise, return the
2911+ // start position.
2912+ //
2913+ private int scan(int start, int end, char c) {
2914+ if ((start < end) && (charAt(start) == c))
2915+ return start + 1;
2916+ return start;
2917+ }
2918+
2919+ // Scan forward from the given start position. Stop at the first char
2920+ // in the err string (in which case -1 is returned), or the first char
2921+ // in the stop string (in which case the index of the preceding char is
2922+ // returned), or the end of the input string (in which case the length
2923+ // of the input string is returned). May return the start position if
2924+ // nothing matches.
2925+ //
2926+ private int scan(int start, int end, String err, String stop) {
2927+ int p = start;
2928+ while (p < end) {
2929+ char c = charAt(p);
2930+ if (err.indexOf(c) >= 0)
2931+ return -1;
2932+ if (stop.indexOf(c) >= 0)
2933+ break;
2934+ p++;
2935+ }
2936+ return p;
2937+ }
2938+
2939+ // Scan a potential escape sequence, starting at the given position,
2940+ // with the given first char (i.e., charAt(start) == c).
2941+ //
2942+ // This method assumes that if escapes are allowed then visible
2943+ // non-US-ASCII chars are also allowed.
2944+ //
2945+ private int scanEscape(int start, int n, char first)
2946+ throws URISyntaxException
2947+ {
2948+ int p = start;
2949+ char c = first;
2950+ if (c == '%') {
2951+ // Process escape pair
2952+ if ((p + 3 <= n)
2953+ && match(charAt(p + 1), L_HEX, H_HEX)
2954+ && match(charAt(p + 2), L_HEX, H_HEX)) {
2955+ return p + 3;
2956+ }
2957+ fail("Malformed escape pair", p);
2958+ } else if ((c > 128)
2959+ && !Character.isSpaceChar(c)
2960+ && !Character.isISOControl(c)) {
2961+ // Allow unescaped but visible non-US-ASCII chars
2962+ return p + 1;
2963+ }
2964+ return p;
2965+ }
2966+
2967+ // Scan chars that match the given mask pair
2968+ //
2969+ private int scan(int start, int n, long lowMask, long highMask)
2970+ throws URISyntaxException
2971+ {
2972+ int p = start;
2973+ while (p < n) {
2974+ char c = charAt(p);
2975+ if (match(c, lowMask, highMask)) {
2976+ p++;
2977+ continue;
2978+ }
2979+ if ((lowMask & L_ESCAPED) != 0) {
2980+ int q = scanEscape(p, n, c);
2981+ if (q > p) {
2982+ p = q;
2983+ continue;
2984+ }
2985+ }
2986+ break;
2987+ }
2988+ return p;
2989+ }
2990+
2991+ // Check that each of the chars in [start, end) matches the given mask
2992+ //
2993+ private void checkChars(int start, int end,
2994+ long lowMask, long highMask,
2995+ String what)
2996+ throws URISyntaxException
2997+ {
2998+ int p = scan(start, end, lowMask, highMask);
2999+ if (p < end)
3000+ fail("Illegal character in " + what, p);
3001+ }
3002+
3003+ // Check that the char at position p matches the given mask
3004+ //
3005+ private void checkChar(int p,
3006+ long lowMask, long highMask,
3007+ String what)
3008+ throws URISyntaxException
3009+ {
3010+ checkChars(p, p + 1, lowMask, highMask, what);
3011+ }
3012+
3013+
3014+ // -- Parsing --
3015+
3016+ // [<scheme>:]<scheme-specific-part>[#<fragment>]
3017+ //
3018+ void parse(boolean rsa) throws URISyntaxException {
3019+ requireServerAuthority = rsa;
3020+ int ssp; // Start of scheme-specific part
3021+ int n = input.length();
3022+ int p = scan(0, n, "/?#", ":");
3023+ if ((p >= 0) && at(p, n, ':')) {
3024+ if (p == 0)
3025+ failExpecting("scheme name", 0);
3026+ checkChar(0, L_ALPHA, H_ALPHA, "scheme name");
3027+ checkChars(1, p, L_SCHEME, H_SCHEME, "scheme name");
3028+ scheme = substring(0, p);
3029+ p++; // Skip ':'
3030+ ssp = p;
3031+ if (at(p, n, '/')) {
3032+ p = parseHierarchical(p, n);
3033+ } else {
3034+ int q = scan(p, n, "", "#");
3035+ if (q <= p)
3036+ failExpecting("scheme-specific part", p);
3037+ checkChars(p, q, L_URIC, H_URIC, "opaque part");
3038+ p = q;
3039+ }
3040+ } else {
3041+ ssp = 0;
3042+ p = parseHierarchical(0, n);
3043+ }
3044+ schemeSpecificPart = substring(ssp, p);
3045+ if (at(p, n, '#')) {
3046+ checkChars(p + 1, n, L_URIC, H_URIC, "fragment");
3047+ fragment = substring(p + 1, n);
3048+ p = n;
3049+ }
3050+ if (p < n)
3051+ fail("end of URI", p);
3052+ }
3053+
3054+ // [//authority]<path>[?<query>]
3055+ //
3056+ // DEVIATION from RFC2396: We allow an empty authority component as
3057+ // long as it's followed by a non-empty path, query component, or
3058+ // fragment component. This is so that URIs such as "file:///foo/bar"
3059+ // will parse. This seems to be the intent of RFC2396, though the
3060+ // grammar does not permit it. If the authority is empty then the
3061+ // userInfo, host, and port components are undefined.
3062+ //
3063+ // DEVIATION from RFC2396: We allow empty relative paths. This seems
3064+ // to be the intent of RFC2396, but the grammar does not permit it.
3065+ // The primary consequence of this deviation is that "#f" parses as a
3066+ // relative URI with an empty path.
3067+ //
3068+ private int parseHierarchical(int start, int n)
3069+ throws URISyntaxException
3070+ {
3071+ int p = start;
3072+ if (at(p, n, '/') && at(p + 1, n, '/')) {
3073+ p += 2;
3074+ int q = scan(p, n, "", "/?#");
3075+ if (q > p) {
3076+ p = parseAuthority(p, q);
3077+ } else if (q < n) {
3078+ // DEVIATION: Allow empty authority prior to non-empty
3079+ // path, query component or fragment identifier
3080+ } else
3081+ failExpecting("authority", p);
3082+ }
3083+ int q = scan(p, n, "", "?#"); // DEVIATION: May be empty
3084+ checkChars(p, q, L_PATH, H_PATH, "path");
3085+ path = substring(p, q);
3086+ p = q;
3087+ if (at(p, n, '?')) {
3088+ p++;
3089+ q = scan(p, n, "", "#");
3090+ checkChars(p, q, L_URIC, H_URIC, "query");
3091+ query = substring(p, q);
3092+ p = q;
3093+ }
3094+ return p;
3095+ }
3096+
3097+ // authority = server | reg_name
3098+ //
3099+ // Ambiguity: An authority that is a registry name rather than a server
3100+ // might have a prefix that parses as a server. We use the fact that
3101+ // the authority component is always followed by '/' or the end of the
3102+ // input string to resolve this: If the complete authority did not
3103+ // parse as a server then we try to parse it as a registry name.
3104+ //
3105+ private int parseAuthority(int start, int n)
3106+ throws URISyntaxException
3107+ {
3108+ int p = start;
3109+ int q = p;
3110+ URISyntaxException ex = null;
3111+
3112+ boolean serverChars;
3113+ boolean regChars;
3114+
3115+ if (scan(p, n, "", "]") > p) {
3116+ // contains a literal IPv6 address, therefore % is allowed
3117+ serverChars = (scan(p, n, L_SERVER_PERCENT, H_SERVER_PERCENT) == n);
3118+ } else {
3119+ serverChars = (scan(p, n, L_SERVER, H_SERVER) == n);
3120+ }
3121+ regChars = (scan(p, n, L_REG_NAME, H_REG_NAME) == n);
3122+
3123+ if (regChars && !serverChars) {
3124+ // Must be a registry-based authority
3125+ authority = substring(p, n);
3126+ return n;
3127+ }
3128+
3129+ if (serverChars) {
3130+ // Might be (probably is) a server-based authority, so attempt
3131+ // to parse it as such. If the attempt fails, try to treat it
3132+ // as a registry-based authority.
3133+ try {
3134+ q = parseServer(p, n);
3135+ if (q < n)
3136+ failExpecting("end of authority", q);
3137+ authority = substring(p, n);
3138+ } catch (URISyntaxException x) {
3139+ // Undo results of failed parse
3140+ userInfo = null;
3141+ host = null;
3142+ port = -1;
3143+ if (requireServerAuthority) {
3144+ // If we're insisting upon a server-based authority,
3145+ // then just re-throw the exception
3146+ throw x;
3147+ } else {
3148+ // Save the exception in case it doesn't parse as a
3149+ // registry either
3150+ ex = x;
3151+ q = p;
3152+ }
3153+ }
3154+ }
3155+
3156+ if (q < n) {
3157+ if (regChars) {
3158+ // Registry-based authority
3159+ authority = substring(p, n);
3160+ } else if (ex != null) {
3161+ // Re-throw exception; it was probably due to
3162+ // a malformed IPv6 address
3163+ throw ex;
3164+ } else {
3165+ fail("Illegal character in authority", q);
3166+ }
3167+ }
3168+
3169+ return n;
3170+ }
3171+
3172+
3173+ // [<userinfo>@]<host>[:<port>]
3174+ //
3175+ private int parseServer(int start, int n)
3176+ throws URISyntaxException
3177+ {
3178+ int p = start;
3179+ int q;
3180+
3181+ // userinfo
3182+ q = scan(p, n, "/?#", "@");
3183+ if ((q >= p) && at(q, n, '@')) {
3184+ checkChars(p, q, L_USERINFO, H_USERINFO, "user info");
3185+ userInfo = substring(p, q);
3186+ p = q + 1; // Skip '@'
3187+ }
3188+
3189+ // hostname, IPv4 address, or IPv6 address
3190+ if (at(p, n, '[')) {
3191+ // DEVIATION from RFC2396: Support IPv6 addresses, per RFC2732
3192+ p++;
3193+ q = scan(p, n, "/?#", "]");
3194+ if ((q > p) && at(q, n, ']')) {
3195+ // look for a "%" scope id
3196+ int r = scan (p, q, "", "%");
3197+ if (r > p) {
3198+ parseIPv6Reference(p, r);
3199+ if (r+1 == q) {
3200+ fail ("scope id expected");
3201+ }
3202+ checkChars (r+1, q, L_ALPHANUM, H_ALPHANUM,
3203+ "scope id");
3204+ } else {
3205+ parseIPv6Reference(p, q);
3206+ }
3207+ host = substring(p-1, q+1);
3208+ p = q + 1;
3209+ } else {
3210+ failExpecting("closing bracket for IPv6 address", q);
3211+ }
3212+ } else {
3213+ q = parseIPv4Address(p, n);
3214+ if (q <= p)
3215+ q = parseHostname(p, n);
3216+ p = q;
3217+ }
3218+
3219+ // port
3220+ if (at(p, n, ':')) {
3221+ p++;
3222+ q = scan(p, n, "", "/");
3223+ if (q > p) {
3224+ checkChars(p, q, L_DIGIT, H_DIGIT, "port number");
3225+ try {
3226+ port = Integer.parseInt(substring(p, q));
3227+ } catch (NumberFormatException x) {
3228+ fail("Malformed port number", p);
3229+ }
3230+ p = q;
3231+ }
3232+ }
3233+ if (p < n)
3234+ failExpecting("port number", p);
3235+
3236+ return p;
3237+ }
3238+
3239+ // Scan a string of decimal digits whose value fits in a byte
3240+ //
3241+ private int scanByte(int start, int n)
3242+ throws URISyntaxException
3243+ {
3244+ int p = start;
3245+ int q = scan(p, n, L_DIGIT, H_DIGIT);
3246+ if (q <= p) return q;
3247+ if (Integer.parseInt(substring(p, q)) > 255) return p;
3248+ return q;
3249+ }
3250+
3251+ // Scan an IPv4 address.
3252+ //
3253+ // If the strict argument is true then we require that the given
3254+ // interval contain nothing besides an IPv4 address; if it is false
3255+ // then we only require that it start with an IPv4 address.
3256+ //
3257+ // If the interval does not contain or start with (depending upon the
3258+ // strict argument) a legal IPv4 address characters then we return -1
3259+ // immediately; otherwise we insist that these characters parse as a
3260+ // legal IPv4 address and throw an exception on failure.
3261+ //
3262+ // We assume that any string of decimal digits and dots must be an IPv4
3263+ // address. It won't parse as a hostname anyway, so making that
3264+ // assumption here allows more meaningful exceptions to be thrown.
3265+ //
3266+ private int scanIPv4Address(int start, int n, boolean strict)
3267+ throws URISyntaxException
3268+ {
3269+ int p = start;
3270+ int q;
3271+ int m = scan(p, n, L_DIGIT | L_DOT, H_DIGIT | H_DOT);
3272+ if ((m <= p) || (strict && (m != n)))
3273+ return -1;
3274+ for (;;) {
3275+ // Per RFC2732: At most three digits per byte
3276+ // Further constraint: Each element fits in a byte
3277+ if ((q = scanByte(p, m)) <= p) break; p = q;
3278+ if ((q = scan(p, m, '.')) <= p) break; p = q;
3279+ if ((q = scanByte(p, m)) <= p) break; p = q;
3280+ if ((q = scan(p, m, '.')) <= p) break; p = q;
3281+ if ((q = scanByte(p, m)) <= p) break; p = q;
3282+ if ((q = scan(p, m, '.')) <= p) break; p = q;
3283+ if ((q = scanByte(p, m)) <= p) break; p = q;
3284+ if (q < m) break;
3285+ return q;
3286+ }
3287+ fail("Malformed IPv4 address", q);
3288+ return -1;
3289+ }
3290+
3291+ // Take an IPv4 address: Throw an exception if the given interval
3292+ // contains anything except an IPv4 address
3293+ //
3294+ private int takeIPv4Address(int start, int n, String expected)
3295+ throws URISyntaxException
3296+ {
3297+ int p = scanIPv4Address(start, n, true);
3298+ if (p <= start)
3299+ failExpecting(expected, start);
3300+ return p;
3301+ }
3302+
3303+ // Attempt to parse an IPv4 address, returning -1 on failure but
3304+ // allowing the given interval to contain [:<characters>] after
3305+ // the IPv4 address.
3306+ //
3307+ private int parseIPv4Address(int start, int n) {
3308+ int p;
3309+
3310+ try {
3311+ p = scanIPv4Address(start, n, false);
3312+ } catch (URISyntaxException x) {
3313+ return -1;
3314+ } catch (NumberFormatException nfe) {
3315+ return -1;
3316+ }
3317+
3318+ if (p > start && p < n) {
3319+ // IPv4 address is followed by something - check that
3320+ // it's a ":" as this is the only valid character to
3321+ // follow an address.
3322+ if (charAt(p) != ':') {
3323+ p = -1;
3324+ }
3325+ }
3326+
3327+ if (p > start)
3328+ host = substring(start, p);
3329+
3330+ return p;
3331+ }
3332+
3333+ // hostname = domainlabel [ "." ] | 1*( domainlabel "." ) toplabel [ "." ]
3334+ // domainlabel = alphanum | alphanum *( alphanum | "-" ) alphanum
3335+ // toplabel = alpha | alpha *( alphanum | "-" ) alphanum
3336+ //
3337+ private int parseHostname(int start, int n)
3338+ throws URISyntaxException
3339+ {
3340+ int p = start;
3341+ int q;
3342+ int l = -1; // Start of last parsed label
3343+
3344+ do {
3345+ // domainlabel = alphanum [ *( alphanum | "-" ) alphanum ]
3346+ q = scan(p, n, L_ALPHANUM, H_ALPHANUM);
3347+ if (q <= p)
3348+ break;
3349+ l = p;
3350+ if (q > p) {
3351+ p = q;
3352+ q = scan(p, n, L_ALPHANUM | L_DASH, H_ALPHANUM | H_DASH);
3353+ if (q > p) {
3354+ if (charAt(q - 1) == '-')
3355+ fail("Illegal character in hostname", q - 1);
3356+ p = q;
3357+ }
3358+ }
3359+ q = scan(p, n, '.');
3360+ if (q <= p)
3361+ break;
3362+ p = q;
3363+ } while (p < n);
3364+
3365+ if ((p < n) && !at(p, n, ':'))
3366+ fail("Illegal character in hostname", p);
3367+
3368+ if (l < 0)
3369+ failExpecting("hostname", start);
3370+
3371+ // for a fully qualified hostname check that the rightmost
3372+ // label starts with an alpha character.
3373+ if (l > start && !match(charAt(l), L_ALPHA, H_ALPHA)) {
3374+ fail("Illegal character in hostname", l);
3375+ }
3376+
3377+ host = substring(start, p);
3378+ return p;
3379+ }
3380+
3381+
3382+ // IPv6 address parsing, from RFC2373: IPv6 Addressing Architecture
3383+ //
3384+ // Bug: The grammar in RFC2373 Appendix B does not allow addresses of
3385+ // the form ::12.34.56.78, which are clearly shown in the examples
3386+ // earlier in the document. Here is the original grammar:
3387+ //
3388+ // IPv6address = hexpart [ ":" IPv4address ]
3389+ // hexpart = hexseq | hexseq "::" [ hexseq ] | "::" [ hexseq ]
3390+ // hexseq = hex4 *( ":" hex4)
3391+ // hex4 = 1*4HEXDIG
3392+ //
3393+ // We therefore use the following revised grammar:
3394+ //
3395+ // IPv6address = hexseq [ ":" IPv4address ]
3396+ // | hexseq [ "::" [ hexpost ] ]
3397+ // | "::" [ hexpost ]
3398+ // hexpost = hexseq | hexseq ":" IPv4address | IPv4address
3399+ // hexseq = hex4 *( ":" hex4)
3400+ // hex4 = 1*4HEXDIG
3401+ //
3402+ // This covers all and only the following cases:
3403+ //
3404+ // hexseq
3405+ // hexseq : IPv4address
3406+ // hexseq ::
3407+ // hexseq :: hexseq
3408+ // hexseq :: hexseq : IPv4address
3409+ // hexseq :: IPv4address
3410+ // :: hexseq
3411+ // :: hexseq : IPv4address
3412+ // :: IPv4address
3413+ // ::
3414+ //
3415+ // Additionally we constrain the IPv6 address as follows :-
3416+ //
3417+ // i. IPv6 addresses without compressed zeros should contain
3418+ // exactly 16 bytes.
3419+ //
3420+ // ii. IPv6 addresses with compressed zeros should contain
3421+ // less than 16 bytes.
3422+
3423+ private int ipv6byteCount = 0;
3424+
3425+ private int parseIPv6Reference(int start, int n)
3426+ throws URISyntaxException
3427+ {
3428+ int p = start;
3429+ int q;
3430+ boolean compressedZeros = false;
3431+
3432+ q = scanHexSeq(p, n);
3433+
3434+ if (q > p) {
3435+ p = q;
3436+ if (at(p, n, "::")) {
3437+ compressedZeros = true;
3438+ p = scanHexPost(p + 2, n);
3439+ } else if (at(p, n, ':')) {
3440+ p = takeIPv4Address(p + 1, n, "IPv4 address");
3441+ ipv6byteCount += 4;
3442+ }
3443+ } else if (at(p, n, "::")) {
3444+ compressedZeros = true;
3445+ p = scanHexPost(p + 2, n);
3446+ }
3447+ if (p < n)
3448+ fail("Malformed IPv6 address", start);
3449+ if (ipv6byteCount > 16)
3450+ fail("IPv6 address too long", start);
3451+ if (!compressedZeros && ipv6byteCount < 16)
3452+ fail("IPv6 address too short", start);
3453+ if (compressedZeros && ipv6byteCount == 16)
3454+ fail("Malformed IPv6 address", start);
3455+
3456+ return p;
3457+ }
3458+
3459+ private int scanHexPost(int start, int n)
3460+ throws URISyntaxException
3461+ {
3462+ int p = start;
3463+ int q;
3464+
3465+ if (p == n)
3466+ return p;
3467+
3468+ q = scanHexSeq(p, n);
3469+ if (q > p) {
3470+ p = q;
3471+ if (at(p, n, ':')) {
3472+ p++;
3473+ p = takeIPv4Address(p, n, "hex digits or IPv4 address");
3474+ ipv6byteCount += 4;
3475+ }
3476+ } else {
3477+ p = takeIPv4Address(p, n, "hex digits or IPv4 address");
3478+ ipv6byteCount += 4;
3479+ }
3480+ return p;
3481+ }
3482+
3483+ // Scan a hex sequence; return -1 if one could not be scanned
3484+ //
3485+ private int scanHexSeq(int start, int n)
3486+ throws URISyntaxException
3487+ {
3488+ int p = start;
3489+ int q;
3490+
3491+ q = scan(p, n, L_HEX, H_HEX);
3492+ if (q <= p)
3493+ return -1;
3494+ if (at(q, n, '.')) // Beginning of IPv4 address
3495+ return -1;
3496+ if (q > p + 4)
3497+ fail("IPv6 hexadecimal digit sequence too long", p);
3498+ ipv6byteCount += 2;
3499+ p = q;
3500+ while (p < n) {
3501+ if (!at(p, n, ':'))
3502+ break;
3503+ if (at(p + 1, n, ':'))
3504+ break; // "::"
3505+ p++;
3506+ q = scan(p, n, L_HEX, H_HEX);
3507+ if (q <= p)
3508+ failExpecting("digits for an IPv6 address", p);
3509+ if (at(q, n, '.')) { // Beginning of IPv4 address
3510+ p--;
3511+ break;
3512+ }
3513+ if (q > p + 4)
3514+ fail("IPv6 hexadecimal digit sequence too long", p);
3515+ ipv6byteCount += 2;
3516+ p = q;
3517+ }
3518+
3519+ return p;
3520+ }
3521+
3522+ }
3523+
3524+}