Package io.grpc

Class NameResolver

java.lang.Object

io.grpc.NameResolver

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/1770")
public abstract class NameResolver
extends 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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	NameResolver.Args	Information that a NameResolver.Factory uses to create a NameResolver.
static class	NameResolver.ConfigOrError	Represents either a successfully parsed service config, containing all necessary parts to be later applied by the channel, or a Status containing the error encountered while parsing.
static class	NameResolver.Factory	Factory that creates NameResolver instances.
static interface	NameResolver.Listener	Receives address updates.
static class	NameResolver.Listener2	Receives address updates.
static class	NameResolver.ResolutionResult	Represents the results from a Name Resolver.
static interface	NameResolver.ResolutionResultAttr	Annotation for name resolution result attributes.
static class	NameResolver.ServiceConfigParser	Parses and validates service configuration.

Field Summary

Fields

Modifier and Type	Field	Description
static Attributes.Key<String>	ATTR_BACKEND_SERVICE

Constructor Summary

Constructors

Constructor	Description
NameResolver()

Method Summary

Modifier and Type	Method	Description
abstract String	getServiceAuthority()	Returns the authority used to authenticate connections to servers.
void	refresh()	Re-resolve the name.
abstract void	shutdown()	Stops the resolution.
void	start(NameResolver.Listener listener)	Starts the resolution.
void	start(NameResolver.Listener2 listener)	Starts the resolution.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ATTR_BACKEND_SERVICE

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/11989")
@ResolutionResultAttr
public static final Attributes.Key<String> ATTR_BACKEND_SERVICE

Constructor Detail

NameResolver

public NameResolver()

Method Detail

getServiceAuthority

public abstract 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