api: Highlight a bug in java.net.URI for those migrating.

Consider:
URI uri = URI.create("file://?#");

// These getters distinguish null from empty, as documented.
assertThat(uri.getPath()).isEqualTo("");
assertThat(uri.getQuery()).isEqualTo("");
assertThat(uri.getFragment()).isEqualTo("");

// These getters do not, unfortunately.
assertThat(uri.getAuthority()).isNull();
assertThat(uri.getHost()).isNull();

Author: jdcormie

api/src/main/java/io/grpc/Uri.java

@@ -148,6 +148,15 @@
  * itself. RFC 9844 claims to obsolete RFC 6874 because web browsers would not support it. This
  * class implements RFC 6874 anyway, mostly to avoid creating a barrier to migration away from
  * {@link java.net.URI}.
+ *
+ * <p>Some URI components, e.g. scheme, are required while others may or may not be present, e.g.
+ * authority. {@link Uri} is careful to preserve the distinction between an absent string component
+ * (getter returns null) and one with an empty value (getter returns ""). {@link java.net.URI} makes
+ * this distinction too, *except* when it comes to the authority and host components: {@link
+ * java.net.URI#getAuthority()} and {@link java.net.URI#getHost()} return null when an authority is
+ * absent, e.g. <code>file:/path</code> as expected. But these methods surprisingly also return null
+ * when the authority is the empty string, e.g.<code>file:///path</code>. {@link Uri}'s getters
+ * correctly return null and "" in these cases, respectively, as one would expect.
  */
 @Internal
 public final class Uri {

api/src/test/java/io/grpc/UriTest.java

@@ -161,6 +161,30 @@ public void parse_emptyPath() throws URISyntaxException {
     assertThat(uri.isPathRootless()).isFalse();
   }
 
+  @Test
+  public void parse_emptyQuery() {
+    Uri uri = Uri.create("scheme:?");
+    assertThat(uri.getScheme()).isEqualTo("scheme");
+    assertThat(uri.getQuery()).isEmpty();
+  }
+
+  @Test
+  public void parse_emptyFragment() {
+    Uri uri = Uri.create("scheme:#");
+    assertThat(uri.getScheme()).isEqualTo("scheme");
+    assertThat(uri.getFragment()).isEmpty();
+  }
+
+  @Test
+  public void parse_emptyUserInfo() {
+    Uri uri = Uri.create("scheme://@host");
+    assertThat(uri.getScheme()).isEqualTo("scheme");
+    assertThat(uri.getAuthority()).isEqualTo("@host");
+    assertThat(uri.getHost()).isEqualTo("host");
+    assertThat(uri.getUserInfo()).isEmpty();
+    assertThat(uri.toString()).isEqualTo("scheme://@host");
+  }
+
   @Test
   public void parse_invalidScheme_throws() {
     URISyntaxException e =