Lines Matching defs:URI
48 * Represents a Uniform Resource Identifier (URI) reference.
51 * class represents a URI reference as defined by
53 * Resource Identifiers (URI): Generic Syntax</i></a>, amended by <a
58 * This class provides constructors for creating URI instances from
61 * and relativizing URI instances. Instances of this class are immutable.
64 * <h4> URI syntax and components </h4>
66 * At the highest level a URI reference (hereinafter simply "URI") in string
76 * <p> An <i>absolute</i> URI specifies a scheme; a URI that is not absolute is
80 * <p> An <i>opaque</i> URI is an absolute URI whose scheme-specific part does
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
102 * <p> A hierarchical URI is subject to further parsing according to the syntax
110 * scheme-specific part of a hierarchical URI consists of the characters
113 * <p> The authority component of a hierarchical URI is, if specified, either
122 * themselves. Nearly all URI schemes currently in use are server-based. An
126 * <p> The path component of a hierarchical URI is itself said to be absolute
128 * relative. The path of a hierarchical URI that is either absolute or
131 * <p> All told, then, a URI instance has the following nine components:
133 * <blockquote><table summary="Describes the components of a URI:scheme,scheme-specific-part,authority,user-info,host,port,path,query,fragment">
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
163 * <h4> Operations on URI instances </h4>
169 * and <tt>".."</tt> segments from the path component of a hierarchical URI.
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
177 * base URI for those not specified in the original. For hierarchical URIs,
185 * against the base URI <tt>http://java.sun.com/j2se/1.3/</tt> is the result
186 * URI
192 * Resolving the relative URI
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
224 * that must be made relative to the base URI of the document wherever
225 * possible. For example, relativizing the URI
231 * against the base URI
237 * yields the relative URI <tt>docs/guide/index.html</tt>.
243 * various components of a URI reference. The following categories, most of
280 * <p><a name="legal-chars"></a> The set of all legal URI characters consists of
292 * <li><p> To <i>encode</i> non-US-ASCII characters when a URI is required to
337 * <li><p> The {@link #URI(java.lang.String) <code>single-argument
343 * #URI(java.lang.String,java.lang.String,java.lang.String,int,java.lang.String,java.lang.String,java.lang.String)
366 * <li><p> The {@link #toString() toString} method returns a URI string with
371 * quoted and encoded URI string that does not contain any <i>other</i>
379 * For any URI <i>u</i>, it is always the case that
382 * <tt>new URI(</tt><i>u</i><tt>.toString()).equals(</tt><i>u</i><tt>)</tt> .
385 * For any URI <i>u</i> that does not contain redundant syntax such as two
392 * <tt>new URI(</tt><i>u</i><tt>.getScheme(),<br>
401 * <tt>new URI(</tt><i>u</i><tt>.getScheme(),<br>
411 * <tt>new URI(</tt><i>u</i><tt>.getScheme(),<br>
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
434 * <p> An instance of this class represents a URI reference in the syntactic
435 * sense defined by RFC 2396. A URI may be either absolute or relative.
436 * A URI string is parsed according to the generic syntax without regard to the
440 * content of the instance. In other words, a URI instance is little more than
465 * Resource Identifiers (URI): Generic Syntax</i></a>, <br><a
471 public final class URI
472 implements Comparable<URI>, Serializable
485 private transient String scheme; // null ==> relative URI
488 // Hierarchical URI components: [//<authority>]<path>[?<query>]
513 * The string form of this URI.
523 private URI() { } // Used internally
526 * Constructs a URI by parsing the given string.
546 * such as <tt>"#foo"</tt> parses as a relative URI with an empty path
548 * href="#resolve-frag">resolved</a> against a base URI.
563 * hierarchical URI such as <tt>s://123</tt>, will parse as a server-based
585 * @param str The string to be parsed into a URI
594 public URI(String str) throws URISyntaxException {
599 * Constructs a hierarchical URI from the given components.
603 * component of the new URI may be left undefined by passing <tt>null</tt>
607 * <p> This constructor first builds a URI string from the given components
643 * is not a <a href="#legal-chars">legal URI character</a> is quoted.
648 * that is not a legal URI character is quoted. </p></li>
652 * <p> The resulting URI string is then parsed as if by invoking the {@link
653 * #URI(String)} constructor and then invoking the {@link
667 * if the URI string constructed from the given components violates
671 public URI(String scheme,
684 * Constructs a hierarchical URI from the given components.
688 * component of the new URI may be left undefined by passing <tt>null</tt>
691 * <p> This constructor first builds a URI string from the given components
718 * is not a <a href="#legal-chars">legal URI character</a> is quoted.
723 * that is not a legal URI character is quoted. </p></li>
727 * <p> The resulting URI string is then parsed as if by invoking the {@link
728 * #URI(String)} constructor and then invoking the {@link
740 * if the URI string constructed from the given components violates
744 public URI(String scheme,
757 * Constructs a hierarchical URI from the given components.
765 * new {@link #URI(String, String, String, int, String, String, String)
766 * URI}(scheme, null, host, -1, path, null, fragment);
775 * If the URI string constructed from the given components
778 public URI(String scheme, String host, String path, String fragment)
785 * Constructs a URI from the given components.
789 * <p> This constructor first builds a URI in string form using the given
800 * character that is not a <a href="#legal-chars">legal URI character</a>
805 * Any character that is not a legal URI character is quoted. </p></li>
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;
818 * If the URI string constructed from the given components
821 public URI(String scheme, String ssp, String fragment)
831 * Creates a URI by parsing the given string.
834 * #URI(String)} constructor; any {@link URISyntaxException} thrown by the
839 * the given string is a legal URI, for example for URI constants declared
843 * URI is being constructed from user input or from some other source that
846 * @param str The string to be parsed into a URI
847 * @return The new URI
855 public static URI create(String str) {
857 return new URI(str);
867 * Attempts to parse this URI's authority component, if defined, into
870 * <p> If this URI's authority component has already been recognized as
873 * URI has no authority component, this method simply returns this URI.
880 * <p> This method is provided because the generic URI syntax specified in
885 * component in the URI string <tt>"//foo:bar"</tt>, for example, is not a
895 * <tt>URI </tt><i>u</i><tt> = new URI(str).parseServerAuthority();</tt>
898 * <p> can be used to ensure that <i>u</i> always refers to a URI that, if
905 * @return A URI whose authority field has been parsed
909 * If the authority component of this URI is defined
913 public URI parseServerAuthority()
927 * Normalizes this URI's path.
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
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
960 * @return A URI equivalent to this URI,
963 public URI normalize() {
968 * Resolves the given URI against this URI.
970 * <p> If the given URI is already absolute, or if this URI is opaque, then
971 * the given URI is returned.
973 * <p><a name="resolve-frag"></a> If the given URI's fragment component is
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.
980 * <p> Otherwise this method constructs a new hierarchical URI in a manner
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>
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>
993 * <li><p> Otherwise the new URI's authority component is copied from
994 * this URI, and its path is computed as follows: </p>
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>
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
1013 * URI is absolute or the given URI is absolute. </p>
1015 * @param uri The URI to be resolved against this URI
1016 * @return The resulting URI
1021 public URI resolve(URI uri) {
1026 * Constructs a new URI by parsing the given string and then resolving it
1027 * against this URI.
1030 * evaluating the expression <tt>{@link #resolve(java.net.URI)
1031 * resolve}(URI.{@link #create(String) create}(str))</tt>. </p>
1033 * @param str The string to be parsed into a URI
1034 * @return The resulting URI
1042 public URI resolve(String str) {
1043 return resolve(URI.create(str));
1047 * Relativizes the given URI against this URI.
1049 * <p> The relativization of the given URI against this URI is computed as
1054 * <li><p> If either this URI or the given URI are opaque, or if the
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>
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>
1066 * @param uri The URI to be relativized against this URI
1067 * @return The resulting URI
1072 public URI relativize(URI uri) {
1077 * Constructs a URL from this URI.
1081 * first checking that this URI is absolute. </p>
1083 * @return A URL constructed from this URI
1095 throw new IllegalArgumentException("URI is not absolute");
1102 * Returns the scheme component of this URI.
1104 * <p> The scheme component of a URI, if defined, only contains characters
1108 * The scheme component of a URI cannot contain escaped octets, hence this
1111 * @return The scheme component of this URI,
1119 * Tells whether or not this URI is absolute.
1121 * <p> A URI is absolute if, and only if, it has a scheme component. </p>
1123 * @return <tt>true</tt> if, and only if, this URI is absolute
1130 * Tells whether or not this URI is opaque.
1132 * <p> A URI is opaque if, and only if, it is absolute and its
1134 * An opaque URI has a scheme, a scheme-specific part, and possibly
1137 * @return <tt>true</tt> if, and only if, this URI is opaque
1144 * Returns the raw scheme-specific part of this URI. The scheme-specific
1147 * <p> The scheme-specific part of a URI only contains legal URI
1150 * @return The raw scheme-specific part of this URI
1159 * Returns the decoded scheme-specific part of this URI.
1166 * @return The decoded scheme-specific part of this URI
1176 * Returns the raw authority component of this URI.
1178 * <p> The authority component of a URI, if defined, only contains the
1185 * @return The raw authority component of this URI,
1193 * Returns the decoded authority component of this URI.
1199 * @return The decoded authority component of this URI,
1209 * Returns the raw user-information component of this URI.
1211 * <p> The user-information component of a URI, if defined, only contains
1215 * @return The raw user-information component of this URI,
1223 * Returns the decoded user-information component of this URI.
1229 * @return The decoded user-information component of this URI,
1239 * Returns the host component of this URI.
1241 * <p> The host component of a URI, if defined, will have one of the
1268 * The host component of a URI cannot contain escaped octets, hence this
1271 * @return The host component of this URI,
1279 * Returns the port number of this URI.
1281 * <p> The port component of a URI, if defined, is a non-negative
1284 * @return The port component of this URI,
1292 * Returns the raw path component of this URI.
1294 * <p> The path component of a URI, if defined, only contains the slash
1299 * @return The path component of this URI,
1307 * Returns the decoded path component of this URI.
1313 * @return The decoded path component of this URI,
1323 * Returns the raw query component of this URI.
1325 * <p> The query component of a URI, if defined, only contains legal URI
1328 * @return The raw query component of this URI,
1336 * Returns the decoded query component of this URI.
1342 * @return The decoded query component of this URI,
1352 * Returns the raw fragment component of this URI.
1354 * <p> The fragment component of a URI, if defined, only contains legal URI
1357 * @return The raw fragment component of this URI,
1365 * Returns the decoded fragment component of this URI.
1371 * @return The decoded fragment component of this URI,
1384 * Tests this URI for equality with another object.
1386 * <p> If the given object is not a URI then this method immediately
1417 * @return <tt>true</tt> if, and only if, the given object is a URI that
1418 * is identical to this URI
1423 if (!(ob instanceof URI))
1425 URI that = (URI)ob;
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
1460 * @return A hash-code value for this URI
1485 * Compares this URI to another object, which must be a URI.
1503 * <li><p> A hierarchical URI is considered to be less than an opaque URI
1544 * The object to which this URI is to be compared
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
1550 * If the given object is not a URI
1552 public int compareTo(URI that) {
1596 * Returns the content of this URI as a string.
1598 * <p> If this URI was created by invoking one of the constructors in this
1601 * returned. Otherwise this URI was created by normalization, resolution,
1602 * or relativization, and so a string is constructed from this URI's
1607 * @return The string form of this URI
1615 * Returns the content of this URI as a US-ASCII string.
1617 * <p> If this URI does not contain any characters in the <i>other</i>
1623 * @return The string form of this URI, encoded as needed
1636 * Saves the content of this URI to the given serial stream.
1638 * <p> The only serializable field of a URI instance is its <tt>string</tt>
1654 * Reconstitutes a URI from the given serial stream.
1671 IOException y = new InvalidObjectException("Invalid URI");
1805 "Relative path in absolute URI");
2018 private static URI resolve(URI base, URI child) {
2032 URI ru = new URI();
2048 URI ru = new URI(); // Resolved URI
2081 // If the given URI's path is normal then return the URI;
2082 // o.w., return a new URI containing the normalized path.
2084 private static URI normalize(URI u) {
2092 URI v = new URI();
2106 // return a relative URI that, when resolved against the base, yields the
2109 private static URI relativize(URI base, URI child) {
2127 URI v = new URI();
2400 // In contrast to Unix-style pathname normalization, for URI paths we
2437 // permissible in the various components of a URI reference. We here
2808 // For convenience we wrap the input URI string in a new instance of the
2814 private String input; // URI input string
3053 fail("end of URI", p);
3068 // relative URI with an empty path.