summaryrefslogtreecommitdiffstats
path: root/luni
diff options
context:
space:
mode:
authorJesse Wilson <jessewilson@google.com>2011-05-27 12:40:32 -0700
committerJesse Wilson <jessewilson@google.com>2011-05-27 15:28:30 -0700
commitecf950e56b55f95a960f151268286576159c6530 (patch)
tree15ec4d0ea84f343676f71f7bc1f8f4844e094aa2 /luni
parent254e9ffacc68159537a8aa2bc3d7799f1375c7b7 (diff)
downloadlibcore-ecf950e56b55f95a960f151268286576159c6530.zip
libcore-ecf950e56b55f95a960f151268286576159c6530.tar.gz
libcore-ecf950e56b55f95a960f151268286576159c6530.tar.bz2
Relative/absolute and opaque/hierarchical docs for java.net.URI.
Change-Id: I5ec2e1dd10a3c676441caf56838433fffa316a59 http://b/2753295
Diffstat (limited to 'luni')
-rw-r--r--luni/src/main/java/java/net/URI.java63
-rw-r--r--luni/src/test/java/libcore/java/net/URITest.java19
2 files changed, 74 insertions, 8 deletions
diff --git a/luni/src/main/java/java/net/URI.java b/luni/src/main/java/java/net/URI.java
index 4df73c1..6b7b1da 100644
--- a/luni/src/main/java/java/net/URI.java
+++ b/luni/src/main/java/java/net/URI.java
@@ -48,12 +48,62 @@ import libcore.net.url.UrlUtils;
* <tr><td>{@link #getFragment() Fragment} </td><td>{@code fragment} </td><td>ref</td></tr>
* </table>
*
+ * <h3>Absolute vs. Relative URIs</h3>
+ * URIs are either {@link #isAbsolute() absolute or relative}.
+ * <ul>
+ * <li><strong>Absolute:</strong> {@code http://android.com/robots.txt}
+ * <li><strong>Relative:</strong> {@code robots.txt}
+ * </ul>
+ *
+ * <p>Absolute URIs always have a scheme. If its scheme is supported by {@link
+ * URL}, you can use {@link #toURL} to convert an absolute URI to a URL.
+ *
+ * <p>Relative URIs do not have a scheme and cannot be converted to URLs. If you
+ * have the absolute URI that a relative URI is relative to, you can use {@link
+ * #resolve} to compute the referenced absolute URI. Symmetrically, you can use
+ * {@link #relativize} to compute the relative URI from one URI to another.
+ * <pre> {@code
+ * URI absolute = new URI("http://android.com/");
+ * URI relative = new URI("robots.txt");
+ * URI resolved = new URI("http://android.com/robots.txt");
+ *
+ * // print "http://android.com/robots.txt"
+ * System.out.println(absolute.resolve(relative));
+ *
+ * // print "robots.txt"
+ * System.out.println(absolute.relativize(resolved));
+ * }</pre>
+ *
+ * <h3>Opaque vs. Hierarchical URIs</h3>
+ * Absolute URIs are either {@link #isOpaque() opaque or hierarchical}. Relative
+ * URIs are always hierarchical.
+ * <ul>
+ * <li><strong>Hierarchical:</strong> {@code http://android.com/robots.txt}
+ * <li><strong>Opaque:</strong> {@code mailto:robots@example.com}
+ * </ul>
+ *
+ * <p>Opaque URIs have both a scheme and a scheme-specific part that does not
+ * begin with the slash character: {@code /}. The contents of the
+ * scheme-specific part of an opaque URI is not parsed so an opaque URI never
+ * has an authority, user info, host, port, path or query. An opaque URIs may
+ * have a fragment, however. A typical opaque URI is
+ * {@code mailto:robots@example.com}.
+ * <table>
+ * <tr><th>Component </th><th>Example value </th></tr>
+ * <tr><td>Scheme </td><td>{@code mailto} </td></tr>
+ * <tr><td>Scheme-specific part</td><td>{@code robots@example.com}</td></tr>
+ * <tr><td>Fragment </td><td> </td></tr>
+ * </table>
+ * <p>Hierarchical URIs may have values for any URL component. They always
+ * have a non-null path, though that path may be the empty string.
+ *
* <h3>Encoding and Decoding URI Components</h3>
* Each component of a URI permits a limited set of legal characters. Other
* characters must first be <i>encoded</i> before they can be embedded in a URI.
* To recover the original characters from a URI, they may be <i>decoded</i>.
- * This class refers to encoded strings as <string>raw</string> strings. For
- * example, consider how this URI is decoded:
+ * <strong>Contrary to what you might expect,</strong> this class uses the
+ * term <i>raw</i> to refer to encoded strings. The non-<i>raw</i> accessors
+ * return decoded strings. For example, consider how this URI is decoded:
* {@code http://user:pa55w%3Frd@host:80/doc%7Csearch?q=green%20robots#over%206%22}
* <table>
* <tr><th>Component </th><th>Legal Characters </th><th>Other Constraints </th><th>Raw Value </th><th>Value</th></tr>
@@ -74,14 +124,11 @@ import libcore.net.url.UrlUtils;
* class. These constructors accept your original strings and encode them into
* their raw form.
*
- * <p>To decode a URI, invoke the single-string constructor, and then the
- * appropriate <code>get<i>Component()</i></code> methods to get the decoded
- * components.
+ * <p>To decode a URI, invoke the single-string constructor, and then use the
+ * appropriate accessor methods to get the decoded components.
*
* <p>The {@link URL} class can be used to retrieve resources by their URI.
*/
-// TODO: document relative URIs
-// TODO: document opaque URIs
public final class URI implements Comparable<URI>, Serializable {
private static final long serialVersionUID = -6052424284110960213l;
@@ -932,7 +979,7 @@ public final class URI implements Comparable<URI>, Serializable {
}
/**
- * Gets the encoded path of this URI, or null if this URI has no path.
+ * Returns the encoded path of this URI, or null if this URI has no path.
*/
public String getRawPath() {
return path;
diff --git a/luni/src/test/java/libcore/java/net/URITest.java b/luni/src/test/java/libcore/java/net/URITest.java
index 9ff8543..d45facc 100644
--- a/luni/src/test/java/libcore/java/net/URITest.java
+++ b/luni/src/test/java/libcore/java/net/URITest.java
@@ -602,5 +602,24 @@ public final class URITest extends TestCase {
assertEquals("", new URI("http", null, "host", -1, "", null, null).getPath());
}
+ public void testResolveRelativeAndAbsolute() throws Exception {
+ URI absolute = new URI("http://android.com/");
+ URI relative = new URI("robots.txt");
+ assertEquals(absolute, absolute.resolve(absolute));
+ assertEquals(new URI("http://android.com/robots.txt"), absolute.resolve(relative));
+ assertEquals(absolute, relative.resolve(absolute));
+ assertEquals(relative, relative.resolve(relative));
+ }
+
+ public void testRelativizeRelativeAndAbsolute() throws Exception {
+ URI absolute = new URI("http://android.com/");
+ URI relative = new URI("robots.txt");
+ assertEquals(relative, absolute.relativize(new URI("http://android.com/robots.txt")));
+ assertEquals(new URI(""), absolute.relativize(absolute));
+ assertEquals(relative, absolute.relativize(relative));
+ assertEquals(absolute, relative.relativize(absolute));
+ assertEquals(new URI(""), relative.relativize(relative));
+ }
+
// Adding a new test? Consider adding an equivalent test to URLTest.java
}