Summary

Correct the description of the relationship between relativize and resolve methods in the documentation of URI class.

Problem

The current documentation of URI class reads that both u.relativize(u.resolve(v)).equals(v) and u.resolve(u.relativize(v)).equals(v) are true for any two normalized URIs u and v. However, according to the specifications of the two methods, there are cases where the described identities do not hold. For example,

1. Assume u is "http://a/b" and v is "c/d", both u.relativize(u.resolve(v)) and u.resolve(u.relativize(v)) equal to "http://a/c/d"
2. Assume u is "http://a/b/" and v is "http://a/b/c/d", u.relativize(u.resolve(v)) equals to "c/d"
3. Assume u is "http://a/b/" and v is "c/d", u.resolve(u.relativize(v)) equals to "http://a/b/c/d"

Solution

Describe the relationship between relativize and resolve methods by imposing some conditions of URIs.

Specification

The relationship between relativize and resolve methods is described as follows:

diff --git a/src/java.base/share/classes/java/net/URI.java b/src/java.base/share/classes/java/net/URI.java
index 46476e9ca77..c56613707e6 100644
--- a/src/java.base/share/classes/java/net/URI.java
+++ b/src/java.base/share/classes/java/net/URI.java
@@ -219,12 +219,20 @@ import sun.nio.cs.UTF_8;
  * {@code demo/b/index.html}
  * </blockquote>
  *
- * <p> <i>Relativization</i>, finally, is the inverse of resolution: For any
- * two normalized URIs <i>u</i> and&nbsp;<i>v</i>,
+ * <p> <i>Relativization</i>, finally, can be regarded as the inverse of resolution.
+ * Let <i>u</i> be any normalized absolute URI ending with a slash character ({@code '/'})
+ * and <i>v</i> be any normalized relative URI not beginning with a period character ({@code '.'})
+ * or slash character ({@code '/'}). Then, the following statement is true:
  *
  * <blockquote>
- *   <i>u</i>{@code .relativize(}<i>u</i>{@code .resolve(}<i>v</i>{@code )).equals(}<i>v</i>{@code )}&nbsp;&nbsp;and<br>
- *   <i>u</i>{@code .resolve(}<i>u</i>{@code .relativize(}<i>v</i>{@code )).equals(}<i>v</i>{@code )}&nbsp;&nbsp;.<br>
+ *   <i>u</i>{@code .relativize(}<i>u</i>{@code .resolve(}<i>v</i>{@code )).equals(}<i>v</i>{@code )}
+ * </blockquote>
+ * 
+ * Let <i>u</i> be any normalized absolute URI ending with a slash character ({@code '/'})
+ * and <i>v</i> be any normalized absolute URI. Then, the following statement is true:
+ * 
+ * <blockquote>
+ *   <i>u</i>{@code .resolve(}<i>u</i>{@code .relativize(}<i>v</i>{@code )).equals(}<i>v</i>{@code )}
  * </blockquote>
  *
  * This operation is often useful when constructing a document containing URIs