| /* |
| * Copyright 2015 The gRPC Authors |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package io.grpc; |
| |
| import java.net.URI; |
| import java.util.List; |
| import javax.annotation.Nullable; |
| import javax.annotation.concurrent.ThreadSafe; |
| |
| /** |
| * A pluggable component that resolves a target {@link URI} and return addresses to the caller. |
| * |
| * <p>A {@code NameResolver} uses the URI's scheme to determine whether it can resolve it, and uses |
| * the components after the scheme for actual resolution. |
| * |
| * <p>The addresses and attributes of a target may be changed over time, thus the caller registers a |
| * {@link Listener} to receive continuous updates. |
| * |
| * <p>A {@code NameResolver} does not need to automatically re-resolve on failure. Instead, the |
| * {@link Listener} is responsible for eventually (after an appropriate backoff period) invoking |
| * {@link #refresh()}. |
| * |
| * @since 1.0.0 |
| */ |
| @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1770") |
| @ThreadSafe |
| public abstract class NameResolver { |
| /** |
| * Returns the authority used to authenticate connections to servers. It <strong>must</strong> 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. |
| * |
| * <p>An implementation must generate it without blocking, typically in line, and |
| * <strong>must</strong> keep it unchanged. {@code NameResolver}s created from the same factory |
| * with the same argument must return the same authority. |
| * |
| * @since 1.0.0 |
| */ |
| public abstract String getServiceAuthority(); |
| |
| /** |
| * Starts the resolution. |
| * |
| * @param listener used to receive updates on the target |
| * @since 1.0.0 |
| */ |
| public abstract void start(Listener listener); |
| |
| /** |
| * Stops the resolution. Updates to the Listener will stop. |
| * |
| * @since 1.0.0 |
| */ |
| public abstract void shutdown(); |
| |
| /** |
| * Re-resolve the name. |
| * |
| * <p>Can only be called after {@link #start} has been called. |
| * |
| * <p>This is only a hint. Implementation takes it as a signal but may not start resolution |
| * immediately. It should never throw. |
| * |
| * <p>The default implementation is no-op. |
| * |
| * @since 1.0.0 |
| */ |
| public void refresh() {} |
| |
| /** |
| * Factory that creates {@link NameResolver} instances. |
| * |
| * @since 1.0.0 |
| */ |
| public abstract static class Factory { |
| /** |
| * The port number used in case the target or the underlying naming system doesn't provide a |
| * port number. |
| * |
| * @since 1.0.0 |
| */ |
| public static final Attributes.Key<Integer> PARAMS_DEFAULT_PORT = |
| Attributes.Key.create("params-default-port"); |
| |
| /** |
| * Creates a {@link NameResolver} for the given target URI, or {@code null} if the given URI |
| * cannot be resolved by this factory. The decision should be solely based on the scheme of the |
| * URI. |
| * |
| * @param targetUri the target URI to be resolved, whose scheme must not be {@code null} |
| * @param params optional parameters. Canonical keys are defined as {@code PARAMS_*} fields in |
| * {@link Factory}. |
| * @since 1.0.0 |
| */ |
| @Nullable |
| public abstract NameResolver newNameResolver(URI targetUri, Attributes params); |
| |
| /** |
| * 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 |
| * URI. |
| * |
| * @since 1.0.0 |
| */ |
| public abstract String getDefaultScheme(); |
| } |
| |
| /** |
| * Receives address updates. |
| * |
| * <p>All methods are expected to return quickly. |
| * |
| * @since 1.0.0 |
| */ |
| @ThreadSafe |
| public interface Listener { |
| /** |
| * Handles updates on resolved addresses and attributes. |
| * |
| * <p>Implementations will not modify the given {@code servers}. |
| * |
| * @param servers the resolved server addresses. An empty list will trigger {@link #onError} |
| * @param attributes extra metadata from naming system |
| * @since 1.3.0 |
| */ |
| void onAddresses(List<EquivalentAddressGroup> servers, Attributes attributes); |
| |
| /** |
| * Handles an error from the resolver. The listener is responsible for eventually invoking |
| * {@link #refresh()} to re-attempt resolution. |
| * |
| * @param error a non-OK status |
| * @since 1.0.0 |
| */ |
| void onError(Status error); |
| } |
| } |