|
22 | 22 | import java.net.internal.UrlUtils; |
23 | 23 | import java.util.Locale; |
24 | 24 |
|
25 | | -/** |
26 | | - * A Uniform Resource Identifier that identifies an abstract or physical |
27 | | - * resource, as specified by <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC |
28 | | - * 2396</a>. |
29 | | - * |
30 | | - * <h3>Parts of a URI</h3> |
31 | | - * A URI is composed of many parts. This class can both parse URI strings into |
32 | | - * parts and compose URI strings from parts. For example, consider the parts of |
33 | | - * this URI: |
34 | | - * {@code http://username:password@host:8080/directory/file?query#fragment} |
35 | | - * <table> |
36 | | - * <tr><th>Component </th><th>Example value </th><th>Also known as</th></tr> |
37 | | - * <tr><td>{@link #getScheme() Scheme} </td><td>{@code http} </td><td>protocol</td></tr> |
38 | | - * <tr><td>{@link #getSchemeSpecificPart() Scheme-specific part}</td><td>{@code //username:password@host:8080/directory/file?query#fragment}</td><td></td></tr> |
39 | | - * <tr><td>{@link #getAuthority() Authority} </td><td>{@code username:password@host:8080} </td><td></td></tr> |
40 | | - * <tr><td>{@link #getUserInfo() User Info} </td><td>{@code username:password} </td><td></td></tr> |
41 | | - * <tr><td>{@link #getHost() Host} </td><td>{@code host} </td><td></td></tr> |
42 | | - * <tr><td>{@link #getPort() Port} </td><td>{@code 8080} </td><td></td></tr> |
43 | | - * <tr><td>{@link #getPath() Path} </td><td>{@code /directory/file} </td><td></td></tr> |
44 | | - * <tr><td>{@link #getQuery() Query} </td><td>{@code query} </td><td></td></tr> |
45 | | - * <tr><td>{@link #getFragment() Fragment} </td><td>{@code fragment} </td><td>ref</td></tr> |
46 | | - * </table> |
47 | | - * |
48 | | - * <h3>Absolute vs. Relative URIs</h3> |
49 | | - * URIs are either {@link #isAbsolute() absolute or relative}. |
50 | | - * <ul> |
51 | | - * <li><strong>Absolute:</strong> {@code http://android.com/robots.txt} |
52 | | - * <li><strong>Relative:</strong> {@code robots.txt} |
53 | | - * </ul> |
54 | | - * |
55 | | - * <p>Absolute URIs always have a scheme. If its scheme is supported by {@link |
56 | | - * URL}, you can use {@link #toURL} to convert an absolute URI to a URL. |
57 | | - * |
58 | | - * <p>Relative URIs do not have a scheme and cannot be converted to URLs. If you |
59 | | - * have the absolute URI that a relative URI is relative to, you can use {@link |
60 | | - * #resolve} to compute the referenced absolute URI. Symmetrically, you can use |
61 | | - * {@link #relativize} to compute the relative URI from one URI to another. |
62 | | - * <pre> {@code |
63 | | - * URI absolute = new URI("http://android.com/"); |
64 | | - * URI relative = new URI("robots.txt"); |
65 | | - * URI resolved = new URI("http://android.com/robots.txt"); |
66 | | - * |
67 | | - * // print "http://android.com/robots.txt" |
68 | | - * System.out.println(absolute.resolve(relative)); |
69 | | - * |
70 | | - * // print "robots.txt" |
71 | | - * System.out.println(absolute.relativize(resolved)); |
72 | | - * }</pre> |
73 | | - * |
74 | | - * <h3>Opaque vs. Hierarchical URIs</h3> |
75 | | - * Absolute URIs are either {@link #isOpaque() opaque or hierarchical}. Relative |
76 | | - * URIs are always hierarchical. |
77 | | - * <ul> |
78 | | - * <li><strong>Hierarchical:</strong> {@code http://android.com/robots.txt} |
79 | | - * <li><strong>Opaque:</strong> {@code mailto:robots@example.com} |
80 | | - * </ul> |
81 | | - * |
82 | | - * <p>Opaque URIs have both a scheme and a scheme-specific part that does not |
83 | | - * begin with the slash character: {@code /}. The contents of the |
84 | | - * scheme-specific part of an opaque URI is not parsed so an opaque URI never |
85 | | - * has an authority, user info, host, port, path or query. An opaque URIs may |
86 | | - * have a fragment, however. A typical opaque URI is |
87 | | - * {@code mailto:robots@example.com}. |
88 | | - * <table> |
89 | | - * <tr><th>Component </th><th>Example value </th></tr> |
90 | | - * <tr><td>Scheme </td><td>{@code mailto} </td></tr> |
91 | | - * <tr><td>Scheme-specific part</td><td>{@code robots@example.com}</td></tr> |
92 | | - * <tr><td>Fragment </td><td> </td></tr> |
93 | | - * </table> |
94 | | - * <p>Hierarchical URIs may have values for any URL component. They always |
95 | | - * have a non-null path, though that path may be the empty string. |
96 | | - * |
97 | | - * <h3>Encoding and Decoding URI Components</h3> |
98 | | - * Each component of a URI permits a limited set of legal characters. Other |
99 | | - * characters must first be <i>encoded</i> before they can be embedded in a URI. |
100 | | - * To recover the original characters from a URI, they may be <i>decoded</i>. |
101 | | - * <strong>Contrary to what you might expect,</strong> this class uses the |
102 | | - * term <i>raw</i> to refer to encoded strings. The non-<i>raw</i> accessors |
103 | | - * return decoded strings. For example, consider how this URI is decoded: |
104 | | - * {@code http://user:pa55w%3Frd@host:80/doc%7Csearch?q=green%20robots#over%206%22} |
105 | | - * <table> |
106 | | - * <tr><th>Component </th><th>Legal Characters </th><th>Other Constraints </th><th>Raw Value </th><th>Value</th></tr> |
107 | | - * <tr><td>Scheme </td><td>{@code 0-9}, {@code a-z}, {@code A-Z}, {@code +-.} </td><td>First character must be in {@code a-z}, {@code A-Z}</td><td> </td><td>{@code http}</td></tr> |
108 | | - * <tr><td>Scheme-specific part</td><td>{@code 0-9}, {@code a-z}, {@code A-Z}, {@code _-!.~'()*,;:$&+=?/[]@}</td><td>Non-ASCII characters okay </td><td>{@code //user:pa55w%3Frd@host:80/doc%7Csearch?q=green%20robots}</td><td>{@code //user:pa55w?rd@host:80/doc|search?q=green robots}</td></tr> |
109 | | - * <tr><td>Authority </td><td>{@code 0-9}, {@code a-z}, {@code A-Z}, {@code _-!.~'()*,;:$&+=@[]} </td><td>Non-ASCII characters okay </td><td>{@code user:pa55w%3Frd@host:80} </td><td>{@code user:pa55w?rd@host:80}</td></tr> |
110 | | - * <tr><td>User Info </td><td>{@code 0-9}, {@code a-z}, {@code A-Z}, {@code _-!.~'()*,;:$&+=} </td><td>Non-ASCII characters okay </td><td>{@code user:pa55w%3Frd} </td><td>{@code user:pa55w?rd}</td></tr> |
111 | | - * <tr><td>Host </td><td>{@code 0-9}, {@code a-z}, {@code A-Z}, {@code -.[]} </td><td>Domain name, IPv4 address or [IPv6 address] </td><td> </td><td>host</td></tr> |
112 | | - * <tr><td>Port </td><td>{@code 0-9} </td><td> </td><td> </td><td>{@code 80}</td></tr> |
113 | | - * <tr><td>Path </td><td>{@code 0-9}, {@code a-z}, {@code A-Z}, {@code _-!.~'()*,;:$&+=/@} </td><td>Non-ASCII characters okay </td><td>{@code /doc%7Csearch} </td><td>{@code /doc|search}</td></tr> |
114 | | - * <tr><td>Query </td><td>{@code 0-9}, {@code a-z}, {@code A-Z}, {@code _-!.~'()*,;:$&+=?/[]@}</td><td>Non-ASCII characters okay </td><td>{@code q=green%20robots} </td><td>{@code q=green robots}</td></tr> |
115 | | - * <tr><td>Fragment </td><td>{@code 0-9}, {@code a-z}, {@code A-Z}, {@code _-!.~'()*,;:$&+=?/[]@}</td><td>Non-ASCII characters okay </td><td>{@code over%206%22} </td><td>{@code over 6"}</td></tr> |
116 | | - * </table> |
117 | | - * A URI's host, port and scheme are not eligible for encoding and must not |
118 | | - * contain illegal characters. |
119 | | - * |
120 | | - * <p>To encode a URI, invoke any of the multiple-parameter constructors of this |
121 | | - * class. These constructors accept your original strings and encode them into |
122 | | - * their raw form. |
123 | | - * |
124 | | - * <p>To decode a URI, invoke the single-string constructor, and then use the |
125 | | - * appropriate accessor methods to get the decoded components. |
126 | | - * |
127 | | - * <p>The {@link URL} class can be used to retrieve resources by their URI. |
128 | | - */ |
129 | 25 | @SuppressWarnings("all") |
130 | 26 | public final class URI implements Comparable<URI>, Serializable { |
131 | 27 |
|
|
0 commit comments