1 /* 2 * Copyright 2014 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.internal; 18 19 import com.google.common.base.Objects; 20 import com.google.common.base.Preconditions; 21 import io.grpc.Attributes; 22 import java.io.Closeable; 23 import java.net.SocketAddress; 24 import java.util.concurrent.ScheduledExecutorService; 25 import javax.annotation.Nullable; 26 27 /** Pre-configured factory for creating {@link ConnectionClientTransport} instances. */ 28 public interface ClientTransportFactory extends Closeable { 29 /** 30 * Creates an unstarted transport for exclusive use. Ownership of {@code options} is passed to the 31 * callee; the caller should not reuse or read from the options after this method is called. 32 * 33 * @param serverAddress the address that the transport is connected to 34 * @param options additional configuration 35 */ newClientTransport( SocketAddress serverAddress, ClientTransportOptions options)36 ConnectionClientTransport newClientTransport( 37 SocketAddress serverAddress, 38 ClientTransportOptions options); 39 40 /** 41 * Returns an executor for scheduling provided by the transport. The service should be configured 42 * to allow cancelled scheduled runnables to be GCed. 43 * 44 * <p>The executor should not be used after the factory has been closed. The caller should ensure 45 * any outstanding tasks are cancelled before the factory is closed. However, it is a 46 * <a href="https://github.com/grpc/grpc-java/issues/1981">known issue</a> that ClientCallImpl may 47 * use this executor after close, so implementations should not go out of their way to prevent 48 * usage. 49 */ getScheduledExecutorService()50 ScheduledExecutorService getScheduledExecutorService(); 51 52 /** 53 * Releases any resources. 54 * 55 * <p>After this method has been called, it's no longer valid to call 56 * {@link #newClientTransport}. No guarantees about thread-safety are made. 57 */ 58 @Override close()59 void close(); 60 61 /** 62 * Options passed to {@link #newClientTransport(SocketAddress, ClientTransportOptions)}. Although 63 * it is safe to save this object if received, it is generally expected that the useful fields are 64 * copied and then the options object is discarded. This allows using {@code final} for those 65 * fields as well as avoids retaining unused objects contained in the options. 66 */ 67 public static final class ClientTransportOptions { 68 private String authority = "unknown-authority"; 69 private Attributes eagAttributes = Attributes.EMPTY; 70 private @Nullable String userAgent; 71 private @Nullable ProxyParameters proxyParameters; 72 getAuthority()73 public String getAuthority() { 74 return authority; 75 } 76 77 /** Sets the non-null authority. */ setAuthority(String authority)78 public ClientTransportOptions setAuthority(String authority) { 79 this.authority = Preconditions.checkNotNull(authority, "authority"); 80 return this; 81 } 82 getEagAttributes()83 public Attributes getEagAttributes() { 84 return eagAttributes; 85 } 86 87 /** Sets the non-null EquivalentAddressGroup's attributes. */ setEagAttributes(Attributes eagAttributes)88 public ClientTransportOptions setEagAttributes(Attributes eagAttributes) { 89 Preconditions.checkNotNull(eagAttributes, "eagAttributes"); 90 this.eagAttributes = eagAttributes; 91 return this; 92 } 93 94 @Nullable getUserAgent()95 public String getUserAgent() { 96 return userAgent; 97 } 98 setUserAgent(@ullable String userAgent)99 public ClientTransportOptions setUserAgent(@Nullable String userAgent) { 100 this.userAgent = userAgent; 101 return this; 102 } 103 104 @Nullable getProxyParameters()105 public ProxyParameters getProxyParameters() { 106 return proxyParameters; 107 } 108 setProxyParameters(@ullable ProxyParameters proxyParameters)109 public ClientTransportOptions setProxyParameters(@Nullable ProxyParameters proxyParameters) { 110 this.proxyParameters = proxyParameters; 111 return this; 112 } 113 114 @Override hashCode()115 public int hashCode() { 116 return Objects.hashCode(authority, eagAttributes, userAgent, proxyParameters); 117 } 118 119 @Override equals(Object o)120 public boolean equals(Object o) { 121 if (!(o instanceof ClientTransportOptions)) { 122 return false; 123 } 124 ClientTransportOptions that = (ClientTransportOptions) o; 125 return this.authority.equals(that.authority) 126 && this.eagAttributes.equals(that.eagAttributes) 127 && Objects.equal(this.userAgent, that.userAgent) 128 && Objects.equal(this.proxyParameters, that.proxyParameters); 129 } 130 } 131 } 132