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

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

    XMLWordPrintable

Details

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

    Description

      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

      Attachments

        Issue Links

          Activity

            People

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

              Dates

                Created:
                Updated:
                Resolved: