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
017package com.google.common.util.concurrent;
018
019import com.google.common.annotations.Beta;
020import com.google.common.base.Supplier;
021
022import java.util.concurrent.Executor;
023import java.util.concurrent.TimeUnit;
024import java.util.concurrent.TimeoutException;
025
026/**
027 * Base class for services that do not need a thread while "running"
028 * but may need one during startup and shutdown. Subclasses can
029 * implement {@link #startUp} and {@link #shutDown} methods, each
030 * which run in a executor which by default uses a separate thread
031 * for each method.
032 *
033 * @author Chris Nokleberg
034 * @since 1.0
035 */
036@Beta
037public abstract class AbstractIdleService implements Service {
038
039  /* Thread names will look like {@code "MyService STARTING"}. */
040  private final Supplier<String> threadNameSupplier = new Supplier<String>() {
041    @Override public String get() {
042      return serviceName() + " " + state();
043    }
044  };
045
046  /* use AbstractService for state management */
047  private final Service delegate = new AbstractService() {
048    @Override protected final void doStart() {
049      MoreExecutors.renamingDecorator(executor(), threadNameSupplier)
050          .execute(new Runnable() {
051            @Override public void run() {
052              try {
053                startUp();
054                notifyStarted();
055              } catch (Throwable t) {
056                notifyFailed(t);
057              }
058            }
059          });
060    }
061
062    @Override protected final void doStop() {
063      MoreExecutors.renamingDecorator(executor(), threadNameSupplier)
064          .execute(new Runnable() {
065            @Override public void run() {
066              try {
067                shutDown();
068                notifyStopped();
069              } catch (Throwable t) {
070                notifyFailed(t);
071              }
072            }
073          });
074    }
075  };
076
077  /** Constructor for use by subclasses. */
078  protected AbstractIdleService() {}
079
080  /** Start the service. */
081  protected abstract void startUp() throws Exception;
082
083  /** Stop the service. */
084  protected abstract void shutDown() throws Exception;
085
086  /**
087   * Returns the {@link Executor} that will be used to run this service.
088   * Subclasses may override this method to use a custom {@link Executor}, which
089   * may configure its worker thread with a specific name, thread group or
090   * priority. The returned executor's {@link Executor#execute(Runnable)
091   * execute()} method is called when this service is started and stopped,
092   * and should return promptly.
093   */
094  protected Executor executor() {
095    return new Executor() {
096      @Override public void execute(Runnable command) {
097        MoreExecutors.newThread(threadNameSupplier.get(), command).start();
098      }
099    };
100  }
101
102  @Override public String toString() {
103    return serviceName() + " [" + state() + "]";
104  }
105
106  @Override public final boolean isRunning() {
107    return delegate.isRunning();
108  }
109
110  @Override public final State state() {
111    return delegate.state();
112  }
113
114  /**
115   * @since 13.0
116   */
117  @Override public final void addListener(Listener listener, Executor executor) {
118    delegate.addListener(listener, executor);
119  }
120  
121  /**
122   * @since 14.0
123   */
124  @Override public final Throwable failureCause() {
125    return delegate.failureCause();
126  }
127  
128  /**
129   * @since 15.0
130   */
131  @Override public final Service startAsync() {
132    delegate.startAsync();
133    return this;
134  }
135  
136  /**
137   * @since 15.0
138   */
139  @Override public final Service stopAsync() {
140    delegate.stopAsync();
141    return this;
142  }
143  
144  /**
145   * @since 15.0
146   */
147  @Override public final void awaitRunning() {
148    delegate.awaitRunning();
149  }
150  
151  /**
152   * @since 15.0
153   */
154  @Override public final void awaitRunning(long timeout, TimeUnit unit) throws TimeoutException {
155    delegate.awaitRunning(timeout, unit);
156  }
157  
158  /**
159   * @since 15.0
160   */
161  @Override public final void awaitTerminated() {
162    delegate.awaitTerminated();
163  }
164  
165  /**
166   * @since 15.0
167   */
168  @Override public final void awaitTerminated(long timeout, TimeUnit unit) throws TimeoutException {
169    delegate.awaitTerminated(timeout, unit);
170  }
171  
172  /**
173   * Returns the name of this service. {@link AbstractIdleService} may include the name in debugging
174   * output.
175   *
176   * @since 14.0
177   */
178  protected String serviceName() {
179    return getClass().getSimpleName();
180  }
181}