Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8291462

Invariants about java.net.URI resolve and relativize are wrong

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P4 P4
    • 20
    • core-libs
    • None
    • minimal
    • API documentation change only
    • Java API
    • SE

      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

            tkiriyama Takuya Kiriyama
            webbuggrp Webbug Group
            Daniel Fuchs
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Resolved: