001/* 002 * Copyright (C) 2009 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.util.concurrent; 016 017import com.google.common.annotations.Beta; 018import com.google.common.annotations.GwtIncompatible; 019import com.google.common.base.Supplier; 020import com.google.errorprone.annotations.CanIgnoreReturnValue; 021import java.util.concurrent.Executor; 022import java.util.concurrent.TimeUnit; 023import java.util.concurrent.TimeoutException; 024import java.util.logging.Level; 025import java.util.logging.Logger; 026 027/** 028 * Base class for services that can implement {@link #startUp}, {@link #run} and {@link #shutDown} 029 * methods. This class uses a single thread to execute the service; consider {@link AbstractService} 030 * if you would like to manage any threading manually. 031 * 032 * @author Jesse Wilson 033 * @since 1.0 034 */ 035@Beta 036@GwtIncompatible 037public abstract class AbstractExecutionThreadService implements Service { 038 private static final Logger logger = 039 Logger.getLogger(AbstractExecutionThreadService.class.getName()); 040 041 /* use AbstractService for state management */ 042 private final Service delegate = 043 new AbstractService() { 044 @Override 045 protected final void doStart() { 046 Executor executor = 047 MoreExecutors.renamingDecorator( 048 executor(), 049 new Supplier<String>() { 050 @Override 051 public String get() { 052 return serviceName(); 053 } 054 }); 055 executor.execute( 056 new Runnable() { 057 @Override 058 public void run() { 059 try { 060 startUp(); 061 notifyStarted(); 062 // If stopAsync() is called while starting we may be in the STOPPING state in 063 // which case we should skip right down to shutdown. 064 if (isRunning()) { 065 try { 066 AbstractExecutionThreadService.this.run(); 067 } catch (Throwable t) { 068 try { 069 shutDown(); 070 } catch (Exception ignored) { 071 // TODO(lukes): if guava ever moves to java7, this would be a good 072 // candidate for a suppressed exception, or maybe we could generalize 073 // Closer.Suppressor 074 logger.log( 075 Level.WARNING, 076 "Error while attempting to shut down the service after failure.", 077 ignored); 078 } 079 notifyFailed(t); 080 return; 081 } 082 } 083 084 shutDown(); 085 notifyStopped(); 086 } catch (Throwable t) { 087 notifyFailed(t); 088 } 089 } 090 }); 091 } 092 093 @Override 094 protected void doStop() { 095 triggerShutdown(); 096 } 097 098 @Override 099 public String toString() { 100 return AbstractExecutionThreadService.this.toString(); 101 } 102 }; 103 104 /** Constructor for use by subclasses. */ 105 protected AbstractExecutionThreadService() {} 106 107 /** 108 * Start the service. This method is invoked on the execution thread. 109 * 110 * <p>By default this method does nothing. 111 */ 112 protected void startUp() throws Exception {} 113 114 /** 115 * Run the service. This method is invoked on the execution thread. Implementations must respond 116 * to stop requests. You could poll for lifecycle changes in a work loop: 117 * 118 * <pre> 119 * public void run() { 120 * while ({@link #isRunning()}) { 121 * // perform a unit of work 122 * } 123 * } 124 * </pre> 125 * 126 * <p>...or you could respond to stop requests by implementing {@link #triggerShutdown()}, which 127 * should cause {@link #run()} to return. 128 */ 129 protected abstract void run() throws Exception; 130 131 /** 132 * Stop the service. This method is invoked on the execution thread. 133 * 134 * <p>By default this method does nothing. 135 */ 136 // TODO: consider supporting a TearDownTestCase-like API 137 protected void shutDown() throws Exception {} 138 139 /** 140 * Invoked to request the service to stop. 141 * 142 * <p>By default this method does nothing. 143 */ 144 protected void triggerShutdown() {} 145 146 /** 147 * Returns the {@link Executor} that will be used to run this service. Subclasses may override 148 * this method to use a custom {@link Executor}, which may configure its worker thread with a 149 * specific name, thread group or priority. The returned executor's {@link 150 * Executor#execute(Runnable) execute()} method is called when this service is started, and should 151 * return promptly. 152 * 153 * <p>The default implementation returns a new {@link Executor} that sets the name of its threads 154 * to the string returned by {@link #serviceName} 155 */ 156 protected Executor executor() { 157 return new Executor() { 158 @Override 159 public void execute(Runnable command) { 160 MoreExecutors.newThread(serviceName(), command).start(); 161 } 162 }; 163 } 164 165 @Override 166 public String toString() { 167 return serviceName() + " [" + state() + "]"; 168 } 169 170 @Override 171 public final boolean isRunning() { 172 return delegate.isRunning(); 173 } 174 175 @Override 176 public final State state() { 177 return delegate.state(); 178 } 179 180 /** @since 13.0 */ 181 @Override 182 public final void addListener(Listener listener, Executor executor) { 183 delegate.addListener(listener, executor); 184 } 185 186 /** @since 14.0 */ 187 @Override 188 public final Throwable failureCause() { 189 return delegate.failureCause(); 190 } 191 192 /** @since 15.0 */ 193 @CanIgnoreReturnValue 194 @Override 195 public final Service startAsync() { 196 delegate.startAsync(); 197 return this; 198 } 199 200 /** @since 15.0 */ 201 @CanIgnoreReturnValue 202 @Override 203 public final Service stopAsync() { 204 delegate.stopAsync(); 205 return this; 206 } 207 208 /** @since 15.0 */ 209 @Override 210 public final void awaitRunning() { 211 delegate.awaitRunning(); 212 } 213 214 /** @since 15.0 */ 215 @Override 216 public final void awaitRunning(long timeout, TimeUnit unit) throws TimeoutException { 217 delegate.awaitRunning(timeout, unit); 218 } 219 220 /** @since 15.0 */ 221 @Override 222 public final void awaitTerminated() { 223 delegate.awaitTerminated(); 224 } 225 226 /** @since 15.0 */ 227 @Override 228 public final void awaitTerminated(long timeout, TimeUnit unit) throws TimeoutException { 229 delegate.awaitTerminated(timeout, unit); 230 } 231 232 /** 233 * Returns the name of this service. {@link AbstractExecutionThreadService} may include the name 234 * in debugging output. 235 * 236 * <p>Subclasses may override this method. 237 * 238 * @since 14.0 (present in 10.0 as getServiceName) 239 */ 240 protected String serviceName() { 241 return getClass().getSimpleName(); 242 } 243}