api: Add newNameResolver() overload and default, best-effort impl.

Author: jdcormie

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

@@ -158,13 +158,48 @@ public abstract static class Factory {
      * cannot be resolved by this factory. The decision should be solely based on the scheme of the
      * URI.
      *
+     * <p>This method will eventually be deprecated and removed as part of a migration from {@code
+     * java.net.URI} to {@code io.grpc.Uri}. Implementations will override {@link
+     * #newNameResolver(Uri, Args)} instead.
+     *
      * @param targetUri the target URI to be resolved, whose scheme must not be {@code null}
      * @param args other information that may be useful
      *
      * @since 1.21.0
      */
     public abstract NameResolver newNameResolver(URI targetUri, final Args args);
 
+    /**
+     * Creates a {@link NameResolver} for the given target URI.
+     *
+     * <p>Implementations return {@code null} if 'targetUri' cannot be resolved by this factory. The
+     * decision should be solely based on the target's scheme.
+     *
+     * <p>All {@link NameResolver.Factory} implementations should override this method, as it will
+     * eventually replace {@link #newNameResolver(URI, Args)}. For backwards compatibility, this
+     * default implementation delegates to {@link #newNameResolver(URI, Args)} if 'targetUri' can be
+     * converted to a java.net.URI.
+     *
+     * <p>NB: Conversion is not always possible, for example {@code scheme:#frag} is a valid {@link
+     * Uri} but not a valid {@link URI} because its path is empty. The default implementation throws
+     * IllegalArgumentException in these cases.
+     *
+     * @param targetUri the target URI to be resolved
+     * @param args other information that may be useful
+     * @throws IllegalArgumentException if targetUri does not have the expected form
+     * @since 1.79
+     */
+    public NameResolver newNameResolver(Uri targetUri, final Args args) {
+      // Not every io.grpc.Uri can be converted but in the ordinary ManagedChannel creation flow,
+      // any IllegalArgumentException thrown here would happened anyway, just earlier. That's
+      // because parse/toString is transparent so java.net.URI#create here sees the original target
+      // string just like it did before the io.grpc.Uri migration.
+      //
+      // Throwing IAE shouldn't surprise non-framework callers either. After all, many existing
+      // Factory impls are picky about targetUri and throw IAE when it doesn't look how they expect.
+      return newNameResolver(URI.create(targetUri.toString()), args);
+    }
+
     /**
      * Returns the default scheme, which will be used to construct a URI when {@link
      * ManagedChannelBuilder#forTarget(String)} is given an authority string instead of a compliant