1bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor/* 21d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Copyright (C) 2009 The Guava Authors 3bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 4bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Licensed under the Apache License, Version 2.0 (the "License"); 5bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * you may not use this file except in compliance with the License. 6bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * You may obtain a copy of the License at 7bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 8bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * http://www.apache.org/licenses/LICENSE-2.0 9bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 10bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Unless required by applicable law or agreed to in writing, software 11bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * distributed under the License is distributed on an "AS IS" BASIS, 12bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * See the License for the specific language governing permissions and 14bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * limitations under the License. 15bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 16bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertpackage com.google.common.util.concurrent; 181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.annotations.Beta; 20bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 21bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorimport java.util.concurrent.ExecutionException; 22bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 23bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor/** 24bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * An object with an operational state, plus asynchronous {@link #start()} and 25bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * {@link #stop()} lifecycle methods to transfer into and out of this state. 26bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Example services include webservers, RPC servers and timers. The normal 27bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * lifecycle of a service is: 28bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * <ul> 29bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * <li>{@link State#NEW} -></li> 30bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * <li>{@link State#STARTING} -></li> 31bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * <li>{@link State#RUNNING} -></li> 32bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * <li>{@link State#STOPPING} -></li> 33bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * <li>{@link State#TERMINATED}</li> 34bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * </ul> 35bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 36bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * If the service fails while starting, running or stopping, its state will be 37bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * {@link State#FAILED}, and its behavior is undefined. Such a service cannot be 38bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * started nor stopped. 39bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>Implementors of this interface are strongly encouraged to extend one of 411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * the abstract classes in this package which implement this interface and 421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * make the threading and state management easier. 43bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 44bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @author Jesse Wilson 451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 9.0 (in 1.0 as 461d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code com.google.common.base.Service}) 47bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert@Beta // TODO(kevinb): make abstract class? 49bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorpublic interface Service { 50bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 51bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * If the service state is {@link State#NEW}, this initiates service startup 52bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * and returns immediately. If the service has already been started, this 53bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * method returns immediately without taking action. A stopped service may not 54bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * be restarted. 55bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 56bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return a future for the startup result, regardless of whether this call 571d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * initiated startup. Calling {@link ListenableFuture#get} will block 581d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * until the service has finished starting, and returns one of {@link 59bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * State#RUNNING}, {@link State#STOPPING} or {@link State#TERMINATED}. If 601d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * the service fails to start, {@link ListenableFuture#get} will throw an 611d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link ExecutionException}, and the service's state will be {@link 621d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * State#FAILED}. If it has already finished starting, {@link 631d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * ListenableFuture#get} returns immediately. Cancelling this future has 641d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * no effect on the service. 65bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 661d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert ListenableFuture<State> start(); 67bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 68bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 69bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Initiates service startup (if necessary), returning once the service has 70bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * finished starting. Unlike calling {@code start().get()}, this method throws 711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * no checked exceptions, and it cannot be {@linkplain Thread#interrupt 721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * interrupted}. 73bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 741d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws UncheckedExecutionException if startup failed 75bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return the state of the service when startup finished. 76bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 77bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor State startAndWait(); 78bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 79bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 801d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns {@code true} if this service is {@linkplain State#RUNNING running}. 81bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 82bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor boolean isRunning(); 83bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 84bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 85bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Returns the lifecycle state of the service. 86bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 87bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor State state(); 88bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 89bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 901d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * If the service is {@linkplain State#STARTING starting} or {@linkplain 911d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * State#RUNNING running}, this initiates service shutdown and returns 921d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * immediately. If the service is {@linkplain State#NEW new}, it is 931d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@linkplain State#TERMINATED terminated} without having been started nor 941d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * stopped. If the service has already been stopped, this method returns 951d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * immediately without taking action. 96bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 97bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return a future for the shutdown result, regardless of whether this call 981d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * initiated shutdown. Calling {@link ListenableFuture#get} will block 991d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * until the service has finished shutting down, and either returns 1001d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link State#TERMINATED} or throws an {@link ExecutionException}. If 1011d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * it has already finished stopping, {@link ListenableFuture#get} returns 1021d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * immediately. Cancelling this future has no effect on the service. 103bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 1041d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert ListenableFuture<State> stop(); 105bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 106bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 107bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Initiates service shutdown (if necessary), returning once the service has 108bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * finished stopping. If this is {@link State#STARTING}, startup will be 109bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * cancelled. If this is {@link State#NEW}, it is {@link State#TERMINATED 110bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * terminated} without having been started nor stopped. Unlike calling {@code 111bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * stop().get()}, this method throws no checked exceptions. 112bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 1131d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws UncheckedExecutionException if shutdown failed 114bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return the state of the service when shutdown finished. 115bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 116bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor State stopAndWait(); 117bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 118bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 119bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * The lifecycle states of a service. 1201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 9.0 (in 1.0 as 1221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code com.google.common.base.Service.State}) 123bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 1241d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Beta // should come out of Beta when Service does 1251d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert enum State { 126bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 127bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * A service in this state is inactive. It does minimal work and consumes 128bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * minimal resources. 129bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 130bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor NEW, 131bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 132bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 133bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * A service in this state is transitioning to {@link #RUNNING}. 134bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 135bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor STARTING, 136bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 137bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 138bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * A service in this state is operational. 139bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 140bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor RUNNING, 141bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 142bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 143bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * A service in this state is transitioning to {@link #TERMINATED}. 144bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 145bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor STOPPING, 146bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 147bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 148bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * A service in this state has completed execution normally. It does minimal 149bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * work and consumes minimal resources. 150bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 151bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor TERMINATED, 152bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 153bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 154bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * A service in this state has encountered a problem and may not be 155bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * operational. It cannot be started nor stopped. 156bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 157bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor FAILED 158bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 159bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor} 160