From d352540a02cc3f438caf7527acfa7bec8c03ecf8 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Wed, 16 Jul 2025 09:09:43 +0000 Subject: [PATCH] api: Add more Javadoc for NameResolver.Listener2 interface (#12220) --- api/src/main/java/io/grpc/NameResolver.java | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/io/grpc/NameResolver.java b/api/src/main/java/io/grpc/NameResolver.java index 9483f5f3b0..2ac4ecae69 100644 --- a/api/src/main/java/io/grpc/NameResolver.java +++ b/api/src/main/java/io/grpc/NameResolver.java @@ -239,6 +239,9 @@ public abstract class NameResolver { * {@link ResolutionResult#getAddressesOrError()} is empty, {@link #onError(Status)} will be * called. * + *

Newer NameResolver implementations should prefer calling onResult2. This method exists to + * facilitate older {@link Listener} implementations to migrate to {@link Listener2}. + * * @param resolutionResult the resolved server addresses, attributes, and Service Config. * @since 1.21.0 */ @@ -248,6 +251,10 @@ public abstract class NameResolver { * Handles a name resolving error from the resolver. The listener is responsible for eventually * invoking {@link NameResolver#refresh()} to re-attempt resolution. * + *

New NameResolver implementations should prefer calling onResult2 which will have the + * address resolution error in {@link ResolutionResult}'s addressesOrError. This method exists + * to facilitate older implementations using {@link Listener} to migrate to {@link Listener2}. + * * @param error a non-OK status * @since 1.21.0 */ @@ -255,9 +262,14 @@ public abstract class NameResolver { public abstract void onError(Status error); /** - * Handles updates on resolved addresses and attributes. + * Handles updates on resolved addresses and attributes. Must be called from the same + * {@link SynchronizationContext} available in {@link NameResolver.Args} that is passed + * from the channel. * - * @param resolutionResult the resolved server addresses, attributes, and Service Config. + * @param resolutionResult the resolved server addresses or error in address resolution, + * attributes, and Service Config or error + * @return status indicating whether the resolutionResult was accepted by the listener, + * typically the result from a load balancer. * @since 1.66 */ public Status onResult2(ResolutionResult resolutionResult) {