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.internal; 18 19 import io.grpc.CallOptions; 20 import io.grpc.InternalChannelz.SocketStats; 21 import io.grpc.InternalInstrumented; 22 import io.grpc.Metadata; 23 import io.grpc.MethodDescriptor; 24 import java.util.concurrent.Executor; 25 import javax.annotation.concurrent.ThreadSafe; 26 27 /** 28 * The client-side transport typically encapsulating a single connection to a remote 29 * server. However, streams created before the client has discovered any server address may 30 * eventually be issued on different connections. All methods on the transport and its callbacks 31 * are expected to execute quickly. 32 */ 33 @ThreadSafe 34 public interface ClientTransport extends InternalInstrumented<SocketStats> { 35 36 /** 37 * Creates a new stream for sending messages to a remote end-point. 38 * 39 * <p>This method returns immediately and does not wait for any validation of the request. If 40 * creation fails for any reason, {@link ClientStreamListener#closed} will be called to provide 41 * the error information. Any sent messages for this stream will be buffered until creation has 42 * completed (either successfully or unsuccessfully). 43 * 44 * <p>This method is called under the {@link io.grpc.Context} of the {@link io.grpc.ClientCall}. 45 * 46 * @param method the descriptor of the remote method to be called for this stream. 47 * @param headers to send at the beginning of the call 48 * @param callOptions runtime options of the call 49 * @return the newly created stream. 50 */ 51 // TODO(nmittler): Consider also throwing for stopping. newStream(MethodDescriptor<?, ?> method, Metadata headers, CallOptions callOptions)52 ClientStream newStream(MethodDescriptor<?, ?> method, Metadata headers, CallOptions callOptions); 53 54 /** 55 * Pings a remote endpoint. When an acknowledgement is received, the given callback will be 56 * invoked using the given executor. 57 * 58 * <p>Pings are not necessarily sent to the same endpont, thus a successful ping only means at 59 * least one endpoint responded, but doesn't imply the availability of other endpoints (if there 60 * is any). 61 * 62 * <p>This is an optional method. Transports that do not have any mechanism by which to ping the 63 * remote endpoint may throw {@link UnsupportedOperationException}. 64 */ ping(PingCallback callback, Executor executor)65 void ping(PingCallback callback, Executor executor); 66 67 /** 68 * A callback that is invoked when the acknowledgement to a {@link #ping} is received. Exactly one 69 * of the two methods should be called per {@link #ping}. 70 */ 71 interface PingCallback { 72 73 /** 74 * Invoked when a ping is acknowledged. The given argument is the round-trip time of the ping, 75 * in nanoseconds. 76 * 77 * @param roundTripTimeNanos the round-trip duration between the ping being sent and the 78 * acknowledgement received 79 */ onSuccess(long roundTripTimeNanos)80 void onSuccess(long roundTripTimeNanos); 81 82 /** 83 * Invoked when a ping fails. The given argument is the cause of the failure. 84 * 85 * @param cause the cause of the ping failure 86 */ onFailure(Throwable cause)87 void onFailure(Throwable cause); 88 } 89 } 90