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 java.util.concurrent.TimeUnit; 20 import javax.annotation.concurrent.ThreadSafe; 21 22 /** 23 * A {@link Channel} that provides lifecycle management. 24 */ 25 @ThreadSafe 26 public abstract class ManagedChannel extends Channel { 27 /** 28 * Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately 29 * cancelled. 30 * 31 * @return this 32 * @since 1.0.0 33 */ shutdown()34 public abstract ManagedChannel shutdown(); 35 36 /** 37 * Returns whether the channel is shutdown. Shutdown channels immediately cancel any new calls, 38 * but may still have some calls being processed. 39 * 40 * @see #shutdown() 41 * @see #isTerminated() 42 * @since 1.0.0 43 */ isShutdown()44 public abstract boolean isShutdown(); 45 46 /** 47 * Returns whether the channel is terminated. Terminated channels have no running calls and 48 * relevant resources released (like TCP connections). 49 * 50 * @see #isShutdown() 51 * @since 1.0.0 52 */ isTerminated()53 public abstract boolean isTerminated(); 54 55 /** 56 * Initiates a forceful shutdown in which preexisting and new calls are cancelled. Although 57 * forceful, the shutdown process is still not instantaneous; {@link #isTerminated()} will likely 58 * return {@code false} immediately after this method returns. 59 * 60 * @return this 61 * @since 1.0.0 62 */ shutdownNow()63 public abstract ManagedChannel shutdownNow(); 64 65 /** 66 * Waits for the channel to become terminated, giving up if the timeout is reached. 67 * 68 * @return whether the channel is terminated, as would be done by {@link #isTerminated()}. 69 * @since 1.0.0 70 */ awaitTermination(long timeout, TimeUnit unit)71 public abstract boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException; 72 73 /** 74 * Gets the current connectivity state. Note the result may soon become outdated. 75 * 76 * <p>Note that the core library did not provide an implementation of this method until v1.6.1. 77 * 78 * @param requestConnection if {@code true}, the channel will try to make a connection if it is 79 * currently IDLE 80 * @throws UnsupportedOperationException if not supported by implementation 81 * @since 1.1.0 82 */ 83 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4359") getState(boolean requestConnection)84 public ConnectivityState getState(boolean requestConnection) { 85 throw new UnsupportedOperationException("Not implemented"); 86 } 87 88 /** 89 * Registers a one-off callback that will be run if the connectivity state of the channel diverges 90 * from the given {@code source}, which is typically what has just been returned by {@link 91 * #getState}. If the states are already different, the callback will be called immediately. The 92 * callback is run in the same executor that runs Call listeners. 93 * 94 * <p>There is an inherent race between the notification to {@code callback} and any call to 95 * {@code getState()}. There is a similar race between {@code getState()} and a call to {@code 96 * notifyWhenStateChanged()}. The state can change during those races, so there is not a way to 97 * see every state transition. "Transitions" to the same state are possible, because intermediate 98 * states may not have been observed. The API is only reliable in tracking the <em>current</em> 99 * state. 100 * 101 * <p>Note that the core library did not provide an implementation of this method until v1.6.1. 102 * 103 * @param source the assumed current state, typically just returned by {@link #getState} 104 * @param callback the one-off callback 105 * @throws UnsupportedOperationException if not supported by implementation 106 * @since 1.1.0 107 */ 108 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4359") notifyWhenStateChanged(ConnectivityState source, Runnable callback)109 public void notifyWhenStateChanged(ConnectivityState source, Runnable callback) { 110 throw new UnsupportedOperationException("Not implemented"); 111 } 112 113 /** 114 * For subchannels that are in TRANSIENT_FAILURE state, short-circuit the backoff timer and make 115 * them reconnect immediately. May also attempt to invoke {@link NameResolver#refresh}. 116 * 117 * <p>This is primarily intended for Android users, where the network may experience frequent 118 * temporary drops. Rather than waiting for gRPC's name resolution and reconnect timers to elapse 119 * before reconnecting, the app may use this method as a mechanism to notify gRPC that the network 120 * is now available and a reconnection attempt may occur immediately. 121 * 122 * <p>No-op if not supported by the implementation. 123 * 124 * @since 1.8.0 125 */ 126 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4056") resetConnectBackoff()127 public void resetConnectBackoff() {} 128 129 /** 130 * Invoking this method moves the channel into the IDLE state and triggers tear-down of the 131 * channel's name resolver and load balancer, while still allowing on-going RPCs on the channel to 132 * continue. New RPCs on the channel will trigger creation of a new connection. 133 * 134 * <p>This is primarily intended for Android users when a device is transitioning from a cellular 135 * to a wifi connection. The OS will issue a notification that a new network (wifi) has been made 136 * the default, but for approximately 30 seconds the device will maintain both the cellular 137 * and wifi connections. Apps may invoke this method to ensure that new RPCs are created using the 138 * new default wifi network, rather than the soon-to-be-disconnected cellular network. 139 * 140 * <p>No-op if not supported by implementation. 141 * 142 * @since 1.11.0 143 */ 144 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4056") enterIdle()145 public void enterIdle() {} 146 } 147