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