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; 18 19 import java.io.IOException; 20 import java.net.SocketAddress; 21 import java.util.Collections; 22 import java.util.List; 23 import java.util.concurrent.TimeUnit; 24 import javax.annotation.concurrent.ThreadSafe; 25 26 /** 27 * Server for listening for and dispatching incoming calls. It is not expected to be implemented by 28 * application code or interceptors. 29 */ 30 @ThreadSafe 31 public abstract class Server { 32 33 /** 34 * Key for accessing the {@link Server} instance inside server RPC {@link Context}. It's 35 * unclear to us what users would need. If you think you need to use this, please file an 36 * issue for us to discuss a public API. 37 */ 38 static final Context.Key<Server> SERVER_CONTEXT_KEY = 39 Context.key("io.grpc.Server"); 40 41 /** 42 * Bind and start the server. After this call returns, clients may begin connecting to the 43 * listening socket(s). 44 * 45 * @return {@code this} object 46 * @throws IllegalStateException if already started or shut down 47 * @throws IOException if unable to bind 48 * @since 1.0.0 49 */ start()50 public abstract Server start() throws IOException; 51 52 /** 53 * Returns the port number the server is listening on. This can return -1 if there is no actual 54 * port or the result otherwise does not make sense. Result is undefined after the server is 55 * terminated. If there are multiple possible ports, this will return one arbitrarily. 56 * Implementations are encouraged to return the same port on each call. 57 * 58 * @see #getListenSockets() 59 * @throws IllegalStateException if the server has not yet been started. 60 * @since 1.0.0 61 */ getPort()62 public int getPort() { 63 return -1; 64 } 65 66 /** 67 * Returns a list of listening sockets for this server. May be different than the originally 68 * requested sockets (e.g. listening on port '0' may end up listening on a different port). 69 * The list is unmodifiable. 70 * 71 * @throws IllegalStateException if the server has not yet been started. 72 * @since 1.19.0 73 */ 74 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/5332") getListenSockets()75 public List<? extends SocketAddress> getListenSockets() { 76 throw new UnsupportedOperationException(); 77 } 78 79 /** 80 * Returns all services registered with the server, or an empty list if not supported by the 81 * implementation. 82 * 83 * @since 1.1.0 84 */ 85 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2222") getServices()86 public List<ServerServiceDefinition> getServices() { 87 return Collections.emptyList(); 88 } 89 90 /** 91 * Returns immutable services registered with the server, or an empty list if not supported by the 92 * implementation. 93 * 94 * @since 1.1.0 95 */ 96 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2222") getImmutableServices()97 public List<ServerServiceDefinition> getImmutableServices() { 98 return Collections.emptyList(); 99 } 100 101 102 /** 103 * Returns mutable services registered with the server, or an empty list if not supported by the 104 * implementation. 105 * 106 * @since 1.1.0 107 */ 108 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2222") getMutableServices()109 public List<ServerServiceDefinition> getMutableServices() { 110 return Collections.emptyList(); 111 } 112 113 /** 114 * Initiates an orderly shutdown in which preexisting calls continue but new calls are rejected. 115 * After this call returns, this server has released the listening socket(s) and may be reused by 116 * another server. 117 * 118 * <p>Note that this method will not wait for preexisting calls to finish before returning. 119 * {@link #awaitTermination()} or {@link #awaitTermination(long, TimeUnit)} needs to be called to 120 * wait for existing calls to finish. 121 * 122 * <p>Calling this method before {@code start()} will shut down and terminate the server like 123 * normal, but prevents starting the server in the future. 124 * 125 * @return {@code this} object 126 * @since 1.0.0 127 */ shutdown()128 public abstract Server shutdown(); 129 130 /** 131 * Initiates a forceful shutdown in which preexisting and new calls are rejected. Although 132 * forceful, the shutdown process is still not instantaneous; {@link #isTerminated()} will likely 133 * return {@code false} immediately after this method returns. After this call returns, this 134 * server has released the listening socket(s) and may be reused by another server. 135 * 136 * <p>Calling this method before {@code start()} will shut down and terminate the server like 137 * normal, but prevents starting the server in the future. 138 * 139 * @return {@code this} object 140 * @since 1.0.0 141 */ shutdownNow()142 public abstract Server shutdownNow(); 143 144 /** 145 * Returns whether the server is shutdown. Shutdown servers reject any new calls, but may still 146 * have some calls being processed. 147 * 148 * @see #shutdown() 149 * @see #isTerminated() 150 * @since 1.0.0 151 */ isShutdown()152 public abstract boolean isShutdown(); 153 154 /** 155 * Returns whether the server is terminated. Terminated servers have no running calls and 156 * relevant resources released (like TCP connections). 157 * 158 * @see #isShutdown() 159 * @since 1.0.0 160 */ isTerminated()161 public abstract boolean isTerminated(); 162 163 /** 164 * Waits for the server to become terminated, giving up if the timeout is reached. 165 * 166 * <p>Calling this method before {@code start()} or {@code shutdown()} is permitted and does not 167 * change its behavior. 168 * 169 * @return whether the server is terminated, as would be done by {@link #isTerminated()}. 170 */ awaitTermination(long timeout, TimeUnit unit)171 public abstract boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException; 172 173 /** 174 * Waits for the server to become terminated. 175 * 176 * <p>Calling this method before {@code start()} or {@code shutdown()} is permitted and does not 177 * change its behavior. 178 * 179 * @since 1.0.0 180 */ awaitTermination()181 public abstract void awaitTermination() throws InterruptedException; 182 } 183