Package io.grpc

Class NameResolver


  • @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1770")
    public abstract class NameResolver
    extends java.lang.Object
    A pluggable component that resolves a target URI and return addresses to the caller.

    A NameResolver uses the URI's scheme to determine whether it can resolve it, and uses the components after the scheme for actual resolution.

    The addresses and attributes of a target may be changed over time, thus the caller registers a NameResolver.Listener to receive continuous updates.

    A NameResolver does not need to automatically re-resolve on failure. Instead, the NameResolver.Listener is responsible for eventually (after an appropriate backoff period) invoking refresh().

    Implementations don't need to be thread-safe. All methods are guaranteed to be called sequentially. Additionally, all methods that have side-effects, i.e., start(Listener2), shutdown() and refresh() are called from the same SynchronizationContext as returned by NameResolver.Args.getSynchronizationContext(). Do not block within the synchronization context; blocking I/O and time-consuming tasks should be offloaded to a separate thread, generally NameResolver.Args.getOffloadExecutor().

    Since:
    1.0.0
    • Constructor Detail

      • NameResolver

        public NameResolver()
    • Method Detail

      • getServiceAuthority

        public abstract java.lang.String getServiceAuthority()
        Returns the authority used to authenticate connections to servers. It must be from a trusted source, because if the authority is tampered with, RPCs may be sent to the attackers which may leak sensitive user data.

        An implementation must generate it without blocking, typically in line, and must keep it unchanged. NameResolvers created from the same factory with the same argument must return the same authority.

        Since:
        1.0.0
      • start

        public void start​(NameResolver.Listener listener)
        Starts the resolution. The method is not supposed to throw any exceptions. That might cause the Channel that the name resolver is serving to crash. Errors should be propagated through NameResolver.Listener.onError(io.grpc.Status).

        An instance may not be started more than once, by any overload of this method, even after an intervening call to shutdown().

        Parameters:
        listener - used to receive updates on the target
        Since:
        1.0.0
      • start

        public void start​(NameResolver.Listener2 listener)
        Starts the resolution. The method is not supposed to throw any exceptions. That might cause the Channel that the name resolver is serving to crash. Errors should be propagated through NameResolver.Listener2.onError(io.grpc.Status).

        An instance may not be started more than once, by any overload of this method, even after an intervening call to shutdown().

        Parameters:
        listener - used to receive updates on the target
        Since:
        1.21.0
      • shutdown

        public abstract void shutdown()
        Stops the resolution. Updates to the Listener will stop.
        Since:
        1.0.0
      • refresh

        public void refresh()
        Re-resolve the name.

        Can only be called after start(io.grpc.NameResolver.Listener) has been called.

        This is only a hint. Implementation takes it as a signal but may not start resolution immediately. It should never throw.

        The default implementation is no-op.

        Since:
        1.0.0