UberChannel.java

/**
 * A virtual connection to a conceptual endpoint, to perform RPCs. A channel is free to have zero or
 * many actual connections to the endpoint based on configuration, load, etc. A channel is also free
 * to determine which actual endpoints to use and may change it every RPC, permitting client-side
 * load balancing. Applications are generally expected to use stubs instead of calling this class
 * directly.
 *
 * <p>Every new request will return an instance of {@link UberClientCall} and all further
 * processing, monitoring, manipulations are done with the UberClientCall instance.
 *
 * <p>Applications can add common cross-cutting behaviors to stubs by decorating Channel
 * implementations using {@link ClientInterceptor}. It is expected that most application code will
 * not use this class directly but rather work with stubs that have been bound to a Channel that was
 * decorated during application initialization.
 *
 * <p>This Channel also provides lifecycle management apis like shutting down, check for termination
 * stattus, etc.
 */
@ThreadSafe
public interface UberChannel {

  /**
   * Create a {@link UberClientCall} to the remote operation specified by the given {@link
   * MethodInfo<T>}. The returned {@link UberClientCall} does not trigger any remote behavior until
   * {@link UberClientCall#start(UberNetworkListener, UberNetworkHeaders)} is invoked.
   *
   * @param methodInfo instance of {@link MethodInfo} containing meta information about the request
   *     being made.
   * @param uberInternalCallOptions runtime options to be applied to this call.
   * @param <ReqT> request fo generic type <ReqT>
   * @param <RespT> response fo generic type <RespT>
   * @param <T> methodinfo of generic type <T>
   * @return a {@link UberClientCall} bound to the specified method.
   */
  <ReqT, RespT, T> UberClientCall<ReqT, RespT> newCall(
      MethodInfo<T> methodInfo, UberInternalCallOptions uberInternalCallOptions);

  /**
   * The authority of the destination this Channel connects to. Typically this is in the format
   * {@code host:port}.
   *
   * @return the authority of the call.
   */
  String authority();

  /**
   * Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately
   * cancelled.
   *
   * @return the current managed channel in use.
   */
  @Nullable
  ManagedChannel shutdown();

  /**
   * Returns whether the channel is shutdown. Shutdown channels immediately cancel any new calls,
   * but may still have some calls being processed.
   *
   * @return true if the channel is shutdown. else false.
   */
  boolean isShutdown();

  /**
   * Returns whether the channel is terminated. Terminated channels have no running calls and
   * relevant resources released (like TCP connections).
   *
   * @return true if the channel is terminated. else false.
   */
  boolean isTerminated();

  /**
   * Initiates a forceful shutdown in which preexisting and new calls are cancelled. Although
   * forceful, the shutdown process is still not instantaneous; {@link #isTerminated()} will likely
   * return {@code false} immediately after this method returns.
   *
   * @return the managed channel currently in use.
   */
  @Nullable
  ManagedChannel shutdownNow();

  /**
   * Waits for the channel to become terminated, giving up if the timeout is reached.
   *
   * @param timeout timeout in long.
   * @param unit timeout units.
   * @return whether the channel is terminated, as would be done by {@link #isTerminated()}.
   * @throws InterruptedException on any interrupted exception.
   */
  boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException;
}