Be more strict in the NameResolver.Factory javadocs

[ST-DDT]

Is your feature request related to a problem?

It's related to a problem/change of behavior of the NameResolverRegistry introduced in #8323
Due to that change the NameResolvers will only be invoked if their getDefaultScheme() matches the specified scheme.
I previously watched for/used both the "default" scheme and an alias.

Describe the solution you'd like

Please change the javadocs to contain a hint, that the scheme used in the newNameResolver must be the same and only as the default scheme (or at least that no other schemes will be checked).

Describe alternatives you've considered

Add a new method that assumes that the check has already been done, with the newNameResolver being implemented to do the checks and then invoke the new method. Later that method should be marked as final to disallow invalid behavior.

@Nullable
public final NameResolver newNameResolver(URI targetUri, NameResolver.Args args) {
    if (getDefaultScheme().equals(targetUri.getScheme())) {
        return createNameResolver(targetUri, args);
    }
    return null;
}

@NotNull
protected abstract NameResolver createNameResolver(URI targetUri, NameResolver.Args args);

[sanjaypujare]

@YifeiZhuang assigned to you to address it. Looks like the user is only requesting Javadoc enhancements.

CC @ejona86

[YifeiZhuang]

#8323 changed the behavior at NameResolverRegistry to only look up the matching scheme at nameResolverProvider getScheme() based on targetUri scheme. Previously it loops through all the registered providers. This is the way we wanted to encourage people to use, specified in javadoc.

How does your newNameResolver() that does the scheme check prevent what kind of breakages introduced by the change in #8323?

[ejona86]

Please change the javadocs to contain a hint, that the scheme used in the newNameResolver must be the same and only as the default scheme (or at least that no other schemes will be checked).

I think this is where we are trying to get to. But I think today we were expecting there were going to be NameResolvers supporting older versions of gRPC and they would still need the scheme check. If you are okay with requiring a newer version of gRPC, then I guess you have close to the guarantee you want already.

I believe the exception is ManagedChannelBuilder.nameResolverFactory(). Once that is dead, then I think NameResolvers will be in a fairly regular world.

[ejona86]

I've added a note to #7133 that we should update the javadoc when we remove nameResolverFactory(). I think that addresses the concern here. @ST-DDT, speak up if I'm mistaken. Updating the doc is good, but slightly premature right now.