1 /* 2 * Copyright (C) 2009 Google Inc. 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 com.google.common.base; 18 19 import java.util.concurrent.ExecutionException; 20 import java.util.concurrent.Future; 21 22 /** 23 * An object with an operational state, plus asynchronous {@link #start()} and 24 * {@link #stop()} lifecycle methods to transfer into and out of this state. 25 * Example services include webservers, RPC servers and timers. The normal 26 * lifecycle of a service is: 27 * <ul> 28 * <li>{@link State#NEW} -></li> 29 * <li>{@link State#STARTING} -></li> 30 * <li>{@link State#RUNNING} -></li> 31 * <li>{@link State#STOPPING} -></li> 32 * <li>{@link State#TERMINATED}</li> 33 * </ul> 34 * 35 * If the service fails while starting, running or stopping, its state will be 36 * {@link State#FAILED}, and its behavior is undefined. Such a service cannot be 37 * started nor stopped. 38 * 39 * <p>Implementors of this interface are strongly encouraged to extend {@link 40 * com.google.common.util.concurrent.AbstractService} or {@link 41 * com.google.common.util.concurrent.AbstractExecutionThreadService}, which make 42 * the threading and state management easier. 43 * 44 * @author Jesse Wilson 45 * @since 2009.09.15 <b>tentative</b> 46 */ 47 public interface Service { 48 /** 49 * If the service state is {@link State#NEW}, this initiates service startup 50 * and returns immediately. If the service has already been started, this 51 * method returns immediately without taking action. A stopped service may not 52 * be restarted. 53 * 54 * @return a future for the startup result, regardless of whether this call 55 * initiated startup. Calling {@link Future#get} will block until the 56 * service has finished starting, and returns one of {@link 57 * State#RUNNING}, {@link State#STOPPING} or {@link State#TERMINATED}. If 58 * the service fails to start, {@link Future#get} will throw an {@link 59 * ExecutionException}, and the service's state will be {@link 60 * State#FAILED}. If it has already finished starting, {@link Future#get} 61 * returns immediately. Cancelling the returned future is unsupported and 62 * always returns {@code false}. 63 */ 64 Future<State> start(); 65 66 /** 67 * Initiates service startup (if necessary), returning once the service has 68 * finished starting. Unlike calling {@code start().get()}, this method throws 69 * no checked exceptions. 70 * 71 * @throws InterruptedRuntimeException if the thread was interrupted while 72 * waiting for the service to finish starting up. 73 * @throws RuntimeException if startup failed 74 * @return the state of the service when startup finished. 75 */ 76 State startAndWait(); 77 78 /** 79 * Returns {@code true} if this service is {@link State#RUNNING running}. 80 */ 81 boolean isRunning(); 82 83 /** 84 * Returns the lifecycle state of the service. 85 */ 86 State state(); 87 88 /** 89 * If the service is {@link State#STARTING} or {@link State#RUNNING}, this 90 * initiates service shutdown and returns immediately. If this is {@link 91 * State#NEW}, it is {@link State#TERMINATED terminated} without having been 92 * started nor stopped. If the service has already been stopped, this 93 * method returns immediately without taking action. 94 * 95 * @return a future for the shutdown result, regardless of whether this call 96 * initiated shutdown. Calling {@link Future#get} will block until the 97 * service has finished shutting down, and either returns {@link 98 * State#TERMINATED} or throws an {@link ExecutionException}. If it has 99 * already finished stopping, {@link Future#get} returns immediately. 100 * Cancelling this future is unsupported and always returns {@code 101 * false}. 102 */ 103 Future<State> stop(); 104 105 /** 106 * Initiates service shutdown (if necessary), returning once the service has 107 * finished stopping. If this is {@link State#STARTING}, startup will be 108 * cancelled. If this is {@link State#NEW}, it is {@link State#TERMINATED 109 * terminated} without having been started nor stopped. Unlike calling {@code 110 * stop().get()}, this method throws no checked exceptions. 111 * 112 * @throws InterruptedRuntimeException if the thread was interrupted while 113 * waiting for the service to finish shutting down. 114 * @throws RuntimeException if shutdown failed 115 * @return the state of the service when shutdown finished. 116 */ 117 State stopAndWait(); 118 119 /** 120 * The lifecycle states of a service. 121 */ 122 public enum State { 123 124 /** 125 * A service in this state is inactive. It does minimal work and consumes 126 * minimal resources. 127 */ 128 NEW, 129 130 /** 131 * A service in this state is transitioning to {@link #RUNNING}. 132 */ 133 STARTING, 134 135 /** 136 * A service in this state is operational. 137 */ 138 RUNNING, 139 140 /** 141 * A service in this state is transitioning to {@link #TERMINATED}. 142 */ 143 STOPPING, 144 145 /** 146 * A service in this state has completed execution normally. It does minimal 147 * work and consumes minimal resources. 148 */ 149 TERMINATED, 150 151 /** 152 * A service in this state has encountered a problem and may not be 153 * operational. It cannot be started nor stopped. 154 */ 155 FAILED 156 } 157 } 158
