1 /* 2 * Copyright 2015 The gRPC Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package io.grpc; 18 19 import com.google.common.base.Preconditions; 20 import java.net.SocketAddress; 21 import java.util.Collection; 22 23 /** 24 * Provider of managed channels for transport agnostic consumption. 25 * 26 * <p>Implementations can be automatically discovered by gRPC via Java's SPI mechanism. For 27 * automatic discovery, the implementation must have a zero-argument constructor and include 28 * a resource named {@code META-INF/services/io.grpc.ManagedChannelProvider} in their JAR. The 29 * file's contents should be the implementation's class name. 30 * 31 * <p>Implementations <em>should not</em> throw. If they do, it may interrupt class loading. If 32 * exceptions may reasonably occur for implementation-specific reasons, implementations should 33 * generally handle the exception gracefully and return {@code false} from {@link #isAvailable()}. 34 */ 35 @Internal 36 public abstract class ManagedChannelProvider { 37 /** 38 * Returns the ClassLoader-wide default channel. 39 * 40 * @throws ProviderNotFoundException if no provider is available 41 */ provider()42 public static ManagedChannelProvider provider() { 43 ManagedChannelProvider provider = ManagedChannelRegistry.getDefaultRegistry().provider(); 44 if (provider == null) { 45 throw new ProviderNotFoundException("No functional channel service provider found. " 46 + "Try adding a dependency on the grpc-okhttp, grpc-netty, or grpc-netty-shaded " 47 + "artifact"); 48 } 49 return provider; 50 } 51 52 /** 53 * Whether this provider is available for use, taking the current environment into consideration. 54 * If {@code false}, no other methods are safe to be called. 55 */ isAvailable()56 protected abstract boolean isAvailable(); 57 58 /** 59 * A priority, from 0 to 10 that this provider should be used, taking the current environment into 60 * consideration. 5 should be considered the default, and then tweaked based on environment 61 * detection. A priority of 0 does not imply that the provider wouldn't work; just that it should 62 * be last in line. 63 */ priority()64 protected abstract int priority(); 65 66 /** 67 * Creates a new builder with the given host and port. 68 */ builderForAddress(String name, int port)69 protected abstract ManagedChannelBuilder<?> builderForAddress(String name, int port); 70 71 /** 72 * Creates a new builder with the given target URI. 73 */ builderForTarget(String target)74 protected abstract ManagedChannelBuilder<?> builderForTarget(String target); 75 76 /** 77 * Creates a new builder with the given target URI and credentials. Returns an error-string result 78 * if unable to understand the credentials. 79 */ newChannelBuilder(String target, ChannelCredentials creds)80 protected NewChannelBuilderResult newChannelBuilder(String target, ChannelCredentials creds) { 81 return NewChannelBuilderResult.error("ChannelCredentials are unsupported"); 82 } 83 84 /** 85 * Returns the {@link SocketAddress} types this ManagedChannelProvider supports. 86 */ getSupportedSocketAddressTypes()87 protected abstract Collection<Class<? extends SocketAddress>> getSupportedSocketAddressTypes(); 88 89 public static final class NewChannelBuilderResult { 90 private final ManagedChannelBuilder<?> channelBuilder; 91 private final String error; 92 NewChannelBuilderResult(ManagedChannelBuilder<?> channelBuilder, String error)93 private NewChannelBuilderResult(ManagedChannelBuilder<?> channelBuilder, String error) { 94 this.channelBuilder = channelBuilder; 95 this.error = error; 96 } 97 channelBuilder(ManagedChannelBuilder<?> builder)98 public static NewChannelBuilderResult channelBuilder(ManagedChannelBuilder<?> builder) { 99 return new NewChannelBuilderResult(Preconditions.checkNotNull(builder), null); 100 } 101 error(String error)102 public static NewChannelBuilderResult error(String error) { 103 return new NewChannelBuilderResult(null, Preconditions.checkNotNull(error)); 104 } 105 getChannelBuilder()106 public ManagedChannelBuilder<?> getChannelBuilder() { 107 return channelBuilder; 108 } 109 getError()110 public String getError() { 111 return error; 112 } 113 } 114 115 /** 116 * Thrown when no suitable {@link ManagedChannelProvider} objects can be found. 117 */ 118 public static final class ProviderNotFoundException extends RuntimeException { 119 private static final long serialVersionUID = 1; 120 ProviderNotFoundException(String msg)121 public ProviderNotFoundException(String msg) { 122 super(msg); 123 } 124 } 125 } 126