1 /* 2 * Copyright 2016 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 java.lang.annotation.Documented; 20 import java.lang.annotation.Retention; 21 import java.lang.annotation.RetentionPolicy; 22 import java.net.SocketAddress; 23 import java.net.URI; 24 import java.net.URISyntaxException; 25 import javax.net.ssl.SSLSession; 26 27 /** 28 * Stuff that are part of the public API but are not bound to particular classes, e.g., static 29 * methods, constants, attribute and context keys. 30 */ 31 public final class Grpc { Grpc()32 private Grpc() { 33 } 34 35 /** 36 * Attribute key for the remote address of a transport. 37 */ 38 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1710") 39 @TransportAttr 40 public static final Attributes.Key<SocketAddress> TRANSPORT_ATTR_REMOTE_ADDR = 41 Attributes.Key.create("io.grpc.Grpc.TRANSPORT_ATTR_REMOTE_ADDR"); 42 43 /** 44 * Attribute key for the local address of a transport. 45 */ 46 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1710") 47 @TransportAttr 48 public static final Attributes.Key<SocketAddress> TRANSPORT_ATTR_LOCAL_ADDR = 49 Attributes.Key.create("io.grpc.Grpc.TRANSPORT_ATTR_LOCAL_ADDR"); 50 51 /** 52 * Attribute key for SSL session of a transport. 53 */ 54 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1710") 55 @TransportAttr 56 public static final Attributes.Key<SSLSession> TRANSPORT_ATTR_SSL_SESSION = 57 Attributes.Key.create("io.grpc.Grpc.TRANSPORT_ATTR_SSL_SESSION"); 58 59 /** 60 * Annotation for transport attributes. It follows the annotation semantics defined 61 * by {@link Attributes}. 62 */ 63 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4972") 64 @Retention(RetentionPolicy.SOURCE) 65 @Documented 66 public @interface TransportAttr {} 67 68 /** 69 * Creates a channel builder with a target string and credentials. The target can be either a 70 * valid {@link NameResolver}-compliant URI, or an authority string. 71 * 72 * <p>A {@code NameResolver}-compliant URI is an absolute hierarchical URI as defined by {@link 73 * java.net.URI}. Example URIs: 74 * <ul> 75 * <li>{@code "dns:///foo.googleapis.com:8080"}</li> 76 * <li>{@code "dns:///foo.googleapis.com"}</li> 77 * <li>{@code "dns:///%5B2001:db8:85a3:8d3:1319:8a2e:370:7348%5D:443"}</li> 78 * <li>{@code "dns://8.8.8.8/foo.googleapis.com:8080"}</li> 79 * <li>{@code "dns://8.8.8.8/foo.googleapis.com"}</li> 80 * <li>{@code "zookeeper://zk.example.com:9900/example_service"}</li> 81 * </ul> 82 * 83 * <p>An authority string will be converted to a {@code NameResolver}-compliant URI, which has 84 * the scheme from the name resolver with the highest priority (e.g. {@code "dns"}), 85 * no authority, and the original authority string as its path after properly escaped. 86 * We recommend libraries to specify the schema explicitly if it is known, since libraries cannot 87 * know which NameResolver will be default during runtime. 88 * Example authority strings: 89 * <ul> 90 * <li>{@code "localhost"}</li> 91 * <li>{@code "127.0.0.1"}</li> 92 * <li>{@code "localhost:8080"}</li> 93 * <li>{@code "foo.googleapis.com:8080"}</li> 94 * <li>{@code "127.0.0.1:8080"}</li> 95 * <li>{@code "[2001:db8:85a3:8d3:1319:8a2e:370:7348]"}</li> 96 * <li>{@code "[2001:db8:85a3:8d3:1319:8a2e:370:7348]:443"}</li> 97 * </ul> 98 */ newChannelBuilder( String target, ChannelCredentials creds)99 public static ManagedChannelBuilder<?> newChannelBuilder( 100 String target, ChannelCredentials creds) { 101 return ManagedChannelRegistry.getDefaultRegistry().newChannelBuilder(target, creds); 102 } 103 104 /** 105 * Creates a channel builder from a host, port, and credentials. The host and port are combined to 106 * form an authority string and then passed to {@link #newChannelBuilder(String, 107 * ChannelCredentials)}. IPv6 addresses are properly surrounded by square brackets ("[]"). 108 */ newChannelBuilderForAddress( String host, int port, ChannelCredentials creds)109 public static ManagedChannelBuilder<?> newChannelBuilderForAddress( 110 String host, int port, ChannelCredentials creds) { 111 return newChannelBuilder(authorityFromHostAndPort(host, port), creds); 112 } 113 114 /** 115 * Combine a host and port into an authority string. 116 */ 117 // A copy of GrpcUtil.authorityFromHostAndPort authorityFromHostAndPort(String host, int port)118 private static String authorityFromHostAndPort(String host, int port) { 119 try { 120 return new URI(null, null, host, port, null, null, null).getAuthority(); 121 } catch (URISyntaxException ex) { 122 throw new IllegalArgumentException("Invalid host or port: " + host + " " + port, ex); 123 } 124 } 125 126 /** 127 * Static factory for creating a new ServerBuilder. 128 * 129 * @param port the port to listen on 130 * @param creds the server identity 131 */ newServerBuilderForPort(int port, ServerCredentials creds)132 public static ServerBuilder<?> newServerBuilderForPort(int port, ServerCredentials creds) { 133 return ServerRegistry.getDefaultRegistry().newServerBuilderForPort(port, creds); 134 } 135 } 136