001/*
002 * Copyright (C) 2012 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 */
016package com.google.common.util.concurrent;
017
018import static com.google.common.base.Preconditions.checkArgument;
019import static com.google.common.base.Preconditions.checkNotNull;
020import static com.google.common.base.Preconditions.checkState;
021import static com.google.common.base.Predicates.equalTo;
022import static com.google.common.base.Predicates.in;
023import static com.google.common.base.Predicates.instanceOf;
024import static com.google.common.base.Predicates.not;
025import static com.google.common.util.concurrent.MoreExecutors.directExecutor;
026import static com.google.common.util.concurrent.Service.State.FAILED;
027import static com.google.common.util.concurrent.Service.State.NEW;
028import static com.google.common.util.concurrent.Service.State.RUNNING;
029import static com.google.common.util.concurrent.Service.State.STARTING;
030import static com.google.common.util.concurrent.Service.State.STOPPING;
031import static com.google.common.util.concurrent.Service.State.TERMINATED;
032import static java.util.concurrent.TimeUnit.MILLISECONDS;
033
034import com.google.common.annotations.Beta;
035import com.google.common.base.Function;
036import com.google.common.base.MoreObjects;
037import com.google.common.base.Stopwatch;
038import com.google.common.collect.Collections2;
039import com.google.common.collect.ImmutableCollection;
040import com.google.common.collect.ImmutableList;
041import com.google.common.collect.ImmutableMap;
042import com.google.common.collect.ImmutableMultimap;
043import com.google.common.collect.ImmutableSet;
044import com.google.common.collect.ImmutableSetMultimap;
045import com.google.common.collect.Lists;
046import com.google.common.collect.Maps;
047import com.google.common.collect.MultimapBuilder;
048import com.google.common.collect.Multimaps;
049import com.google.common.collect.Multiset;
050import com.google.common.collect.Ordering;
051import com.google.common.collect.SetMultimap;
052import com.google.common.util.concurrent.ListenerCallQueue.Callback;
053import com.google.common.util.concurrent.Service.State;
054
055import java.lang.ref.WeakReference;
056import java.util.ArrayList;
057import java.util.Collections;
058import java.util.EnumSet;
059import java.util.List;
060import java.util.Map;
061import java.util.Map.Entry;
062import java.util.concurrent.Executor;
063import java.util.concurrent.TimeUnit;
064import java.util.concurrent.TimeoutException;
065import java.util.logging.Level;
066import java.util.logging.Logger;
067
068import javax.annotation.concurrent.GuardedBy;
069
070/**
071 * A manager for monitoring and controlling a set of {@linkplain Service services}. This class
072 * provides methods for {@linkplain #startAsync() starting}, {@linkplain #stopAsync() stopping} and
073 * {@linkplain #servicesByState inspecting} a collection of {@linkplain Service services}.
074 * Additionally, users can monitor state transitions with the {@linkplain Listener listener}
075 * mechanism.
076 *
077 * <p>While it is recommended that service lifecycles be managed via this class, state transitions
078 * initiated via other mechanisms do not impact the correctness of its methods. For example, if the
079 * services are started by some mechanism besides {@link #startAsync}, the listeners will be invoked
080 * when appropriate and {@link #awaitHealthy} will still work as expected.
081 *
082 * <p>Here is a simple example of how to use a {@code ServiceManager} to start a server.
083 * <pre>   {@code
084 * class Server {
085 *   public static void main(String[] args) {
086 *     Set<Service> services = ...;
087 *     ServiceManager manager = new ServiceManager(services);
088 *     manager.addListener(new Listener() {
089 *         public void stopped() {}
090 *         public void healthy() {
091 *           // Services have been initialized and are healthy, start accepting requests...
092 *         }
093 *         public void failure(Service service) {
094 *           // Something failed, at this point we could log it, notify a load balancer, or take
095 *           // some other action.  For now we will just exit.
096 *           System.exit(1);
097 *         }
098 *       },
099 *       MoreExecutors.directExecutor());
100 *
101 *     Runtime.getRuntime().addShutdownHook(new Thread() {
102 *       public void run() {
103 *         // Give the services 5 seconds to stop to ensure that we are responsive to shutdown
104 *         // requests.
105 *         try {
106 *           manager.stopAsync().awaitStopped(5, TimeUnit.SECONDS);
107 *         } catch (TimeoutException timeout) {
108 *           // stopping timed out
109 *         }
110 *       }
111 *     });
112 *     manager.startAsync();  // start all the services asynchronously
113 *   }
114 * }}</pre>
115 *
116 * <p>This class uses the ServiceManager's methods to start all of its services, to respond to
117 * service failure and to ensure that when the JVM is shutting down all the services are stopped.
118 *
119 * @author Luke Sandberg
120 * @since 14.0
121 */
122@Beta
123public final class ServiceManager {
124  private static final Logger logger = Logger.getLogger(ServiceManager.class.getName());
125  private static final Callback<Listener> HEALTHY_CALLBACK = new Callback<Listener>("healthy()") {
126    @Override void call(Listener listener) {
127      listener.healthy();
128    }
129  };
130  private static final Callback<Listener> STOPPED_CALLBACK = new Callback<Listener>("stopped()") {
131    @Override void call(Listener listener) {
132      listener.stopped();
133    }
134  };
135
136  /**
137   * A listener for the aggregate state changes of the services that are under management. Users
138   * that need to listen to more fine-grained events (such as when each particular {@linkplain
139   * Service service} starts, or terminates), should attach {@linkplain Service.Listener service
140   * listeners} to each individual service.
141   *
142   * @author Luke Sandberg
143   * @since 15.0 (present as an interface in 14.0)
144   */
145  @Beta  // Should come out of Beta when ServiceManager does
146  public abstract static class Listener {
147    /**
148     * Called when the service initially becomes healthy.
149     *
150     * <p>This will be called at most once after all the services have entered the
151     * {@linkplain State#RUNNING running} state. If any services fail during start up or
152     * {@linkplain State#FAILED fail}/{@linkplain State#TERMINATED terminate} before all other
153     * services have started {@linkplain State#RUNNING running} then this method will not be called.
154     */
155    public void healthy() {}
156
157    /**
158     * Called when the all of the component services have reached a terminal state, either
159     * {@linkplain State#TERMINATED terminated} or {@linkplain State#FAILED failed}.
160     */
161    public void stopped() {}
162
163    /**
164     * Called when a component service has {@linkplain State#FAILED failed}.
165     *
166     * @param service The service that failed.
167     */
168    public void failure(Service service) {}
169  }
170
171  /**
172   * An encapsulation of all of the state that is accessed by the {@linkplain ServiceListener
173   * service listeners}.  This is extracted into its own object so that {@link ServiceListener}
174   * could be made {@code static} and its instances can be safely constructed and added in the
175   * {@link ServiceManager} constructor without having to close over the partially constructed
176   * {@link ServiceManager} instance (i.e. avoid leaking a pointer to {@code this}).
177   */
178  private final ServiceManagerState state;
179  private final ImmutableList<Service> services;
180
181  /**
182   * Constructs a new instance for managing the given services.
183   *
184   * @param services The services to manage
185   *
186   * @throws IllegalArgumentException if not all services are {@linkplain State#NEW new} or if there
187   * are any duplicate services.
188   */
189  public ServiceManager(Iterable<? extends Service> services) {
190    ImmutableList<Service> copy = ImmutableList.copyOf(services);
191    if (copy.isEmpty()) {
192      // Having no services causes the manager to behave strangely. Notably, listeners are never
193      // fired.  To avoid this we substitute a placeholder service.
194      logger.log(Level.WARNING,
195          "ServiceManager configured with no services.  Is your application configured properly?",
196          new EmptyServiceManagerWarning());
197      copy = ImmutableList.<Service>of(new NoOpService());
198    }
199    this.state = new ServiceManagerState(copy);
200    this.services = copy;
201    WeakReference<ServiceManagerState> stateReference =
202        new WeakReference<ServiceManagerState>(state);
203    for (Service service : copy) {
204      service.addListener(new ServiceListener(service, stateReference), directExecutor());
205      // We check the state after adding the listener as a way to ensure that our listener was added
206      // to a NEW service.
207      checkArgument(service.state() == NEW, "Can only manage NEW services, %s", service);
208    }
209    // We have installed all of our listeners and after this point any state transition should be
210    // correct.
211    this.state.markReady();
212  }
213
214  /**
215   * Registers a {@link Listener} to be {@linkplain Executor#execute executed} on the given
216   * executor. The listener will not have previous state changes replayed, so it is
217   * suggested that listeners are added before any of the managed services are
218   * {@linkplain Service#startAsync started}.
219   *
220   * <p>{@code addListener} guarantees execution ordering across calls to a given listener but not
221   * across calls to multiple listeners. Specifically, a given listener will have its callbacks
222   * invoked in the same order as the underlying service enters those states. Additionally, at most
223   * one of the listener's callbacks will execute at once. However, multiple listeners' callbacks
224   * may execute concurrently, and listeners may execute in an order different from the one in which
225   * they were registered.
226   *
227   * <p>RuntimeExceptions thrown by a listener will be caught and logged. Any exception thrown
228   * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException}) will be caught and
229   * logged.
230   *
231   * <p> For fast, lightweight listeners that would be safe to execute in any thread, consider
232   * calling {@link #addListener(Listener)}.
233   *
234   * @param listener the listener to run when the manager changes state
235   * @param executor the executor in which the listeners callback methods will be run.
236   */
237  public void addListener(Listener listener, Executor executor) {
238    state.addListener(listener, executor);
239  }
240
241  /**
242   * Registers a {@link Listener} to be run when this {@link ServiceManager} changes state. The
243   * listener will not have previous state changes replayed, so it is suggested that listeners are
244   * added before any of the managed services are {@linkplain Service#startAsync started}.
245   *
246   * <p>{@code addListener} guarantees execution ordering across calls to a given listener but not
247   * across calls to multiple listeners. Specifically, a given listener will have its callbacks
248   * invoked in the same order as the underlying service enters those states. Additionally, at most
249   * one of the listener's callbacks will execute at once. However, multiple listeners' callbacks
250   * may execute concurrently, and listeners may execute in an order different from the one in which
251   * they were registered.
252   *
253   * <p>RuntimeExceptions thrown by a listener will be caught and logged.
254   *
255   * @param listener the listener to run when the manager changes state
256   */
257  public void addListener(Listener listener) {
258    state.addListener(listener, directExecutor());
259  }
260
261  /**
262   * Initiates service {@linkplain Service#startAsync startup} on all the services being managed.
263   * It is only valid to call this method if all of the services are {@linkplain State#NEW new}.
264   *
265   * @return this
266   * @throws IllegalStateException if any of the Services are not {@link State#NEW new} when the
267   *     method is called.
268   */
269  public ServiceManager startAsync() {
270    for (Service service : services) {
271      State state = service.state();
272      checkState(state == NEW, "Service %s is %s, cannot start it.", service, state);
273    }
274    for (Service service : services) {
275      try {
276        state.tryStartTiming(service);
277        service.startAsync();
278      } catch (IllegalStateException e) {
279        // This can happen if the service has already been started or stopped (e.g. by another
280        // service or listener). Our contract says it is safe to call this method if
281        // all services were NEW when it was called, and this has already been verified above, so we
282        // don't propagate the exception.
283        logger.log(Level.WARNING, "Unable to start Service " + service, e);
284      }
285    }
286    return this;
287  }
288
289  /**
290   * Waits for the {@link ServiceManager} to become {@linkplain #isHealthy() healthy}.  The manager
291   * will become healthy after all the component services have reached the {@linkplain State#RUNNING
292   * running} state.
293   *
294   * @throws IllegalStateException if the service manager reaches a state from which it cannot
295   *     become {@linkplain #isHealthy() healthy}.
296   */
297  public void awaitHealthy() {
298    state.awaitHealthy();
299  }
300
301  /**
302   * Waits for the {@link ServiceManager} to become {@linkplain #isHealthy() healthy} for no more
303   * than the given time.  The manager will become healthy after all the component services have
304   * reached the {@linkplain State#RUNNING running} state.
305   *
306   * @param timeout the maximum time to wait
307   * @param unit the time unit of the timeout argument
308   * @throws TimeoutException if not all of the services have finished starting within the deadline
309   * @throws IllegalStateException if the service manager reaches a state from which it cannot
310   *     become {@linkplain #isHealthy() healthy}.
311   */
312  public void awaitHealthy(long timeout, TimeUnit unit) throws TimeoutException {
313    state.awaitHealthy(timeout, unit);
314  }
315
316  /**
317   * Initiates service {@linkplain Service#stopAsync shutdown} if necessary on all the services
318   * being managed.
319   *
320   * @return this
321   */
322  public ServiceManager stopAsync() {
323    for (Service service : services) {
324      service.stopAsync();
325    }
326    return this;
327  }
328
329  /**
330   * Waits for the all the services to reach a terminal state. After this method returns all
331   * services will either be {@linkplain Service.State#TERMINATED terminated} or {@linkplain
332   * Service.State#FAILED failed}.
333   */
334  public void awaitStopped() {
335    state.awaitStopped();
336  }
337
338  /**
339   * Waits for the all the services to reach a terminal state for no more than the given time. After
340   * this method returns all services will either be {@linkplain Service.State#TERMINATED
341   * terminated} or {@linkplain Service.State#FAILED failed}.
342   *
343   * @param timeout the maximum time to wait
344   * @param unit the time unit of the timeout argument
345   * @throws TimeoutException if not all of the services have stopped within the deadline
346   */
347  public void awaitStopped(long timeout, TimeUnit unit) throws TimeoutException {
348    state.awaitStopped(timeout, unit);
349  }
350
351  /**
352   * Returns true if all services are currently in the {@linkplain State#RUNNING running} state.
353   *
354   * <p>Users who want more detailed information should use the {@link #servicesByState} method to
355   * get detailed information about which services are not running.
356   */
357  public boolean isHealthy() {
358    for (Service service : services) {
359      if (!service.isRunning()) {
360        return false;
361      }
362    }
363    return true;
364  }
365
366  /**
367   * Provides a snapshot of the current state of all the services under management.
368   *
369   * <p>N.B. This snapshot is guaranteed to be consistent, i.e. the set of states returned will
370   * correspond to a point in time view of the services.
371   */
372  public ImmutableMultimap<State, Service> servicesByState() {
373    return state.servicesByState();
374  }
375
376  /**
377   * Returns the service load times. This value will only return startup times for services that
378   * have finished starting.
379   *
380   * @return Map of services and their corresponding startup time in millis, the map entries will be
381   *     ordered by startup time.
382   */
383  public ImmutableMap<Service, Long> startupTimes() {
384    return state.startupTimes();
385  }
386
387  @Override public String toString() {
388    return MoreObjects.toStringHelper(ServiceManager.class)
389        .add("services", Collections2.filter(services, not(instanceOf(NoOpService.class))))
390        .toString();
391  }
392
393  /**
394   * An encapsulation of all the mutable state of the {@link ServiceManager} that needs to be
395   * accessed by instances of {@link ServiceListener}.
396   */
397  private static final class ServiceManagerState {
398    final Monitor monitor = new Monitor();
399
400    @GuardedBy("monitor")
401    final SetMultimap<State, Service> servicesByState =
402        MultimapBuilder.enumKeys(State.class).linkedHashSetValues().build();
403
404    @GuardedBy("monitor")
405    final Multiset<State> states = servicesByState.keys();
406
407    @GuardedBy("monitor")
408    final Map<Service, Stopwatch> startupTimers = Maps.newIdentityHashMap();
409
410    /**
411     * These two booleans are used to mark the state as ready to start.
412     * {@link #ready}: is set by {@link #markReady} to indicate that all listeners have been
413     *     correctly installed
414     * {@link #transitioned}: is set by {@link #transitionService} to indicate that some transition
415     *     has been performed.
416     *
417     * <p>Together, they allow us to enforce that all services have their listeners installed prior
418     * to any service performing a transition, then we can fail in the ServiceManager constructor
419     * rather than in a Service.Listener callback.
420     */
421    @GuardedBy("monitor")
422    boolean ready;
423
424    @GuardedBy("monitor")
425    boolean transitioned;
426
427    final int numberOfServices;
428
429    /**
430     * Controls how long to wait for all the services to either become healthy or reach a
431     * state from which it is guaranteed that it can never become healthy.
432     */
433    final Monitor.Guard awaitHealthGuard = new Monitor.Guard(monitor) {
434      @Override public boolean isSatisfied() {
435        // All services have started or some service has terminated/failed.
436        return states.count(RUNNING) == numberOfServices
437            || states.contains(STOPPING)
438            || states.contains(TERMINATED)
439            || states.contains(FAILED);
440      }
441    };
442
443    /**
444     * Controls how long to wait for all services to reach a terminal state.
445     */
446    final Monitor.Guard stoppedGuard = new Monitor.Guard(monitor) {
447      @Override public boolean isSatisfied() {
448        return states.count(TERMINATED) + states.count(FAILED) == numberOfServices;
449      }
450    };
451
452    /** The listeners to notify during a state transition. */
453    @GuardedBy("monitor")
454    final List<ListenerCallQueue<Listener>> listeners =
455        Collections.synchronizedList(new ArrayList<ListenerCallQueue<Listener>>());
456
457    /**
458     * It is implicitly assumed that all the services are NEW and that they will all remain NEW
459     * until all the Listeners are installed and {@link #markReady()} is called.  It is our caller's
460     * responsibility to only call {@link #markReady()} if all services were new at the time this
461     * method was called and when all the listeners were installed.
462     */
463    ServiceManagerState(ImmutableCollection<Service> services) {
464      this.numberOfServices = services.size();
465      servicesByState.putAll(NEW, services);
466    }
467
468    /**
469     * Attempts to start the timer immediately prior to the service being started via
470     * {@link Service#startAsync()}.
471     */
472    void tryStartTiming(Service service) {
473      monitor.enter();
474      try {
475        Stopwatch stopwatch = startupTimers.get(service);
476        if (stopwatch == null) {
477          startupTimers.put(service, Stopwatch.createStarted());
478        }
479      } finally {
480        monitor.leave();
481      }
482    }
483
484    /**
485     * Marks the {@link State} as ready to receive transitions. Returns true if no transitions have
486     * been observed yet.
487     */
488    void markReady() {
489      monitor.enter();
490      try {
491        if (!transitioned) {
492          // nothing has transitioned since construction, good.
493          ready = true;
494        } else {
495          // This should be an extremely rare race condition.
496          List<Service> servicesInBadStates = Lists.newArrayList();
497          for (Service service : servicesByState().values()) {
498            if (service.state() != NEW) {
499              servicesInBadStates.add(service);
500            }
501          }
502          throw new IllegalArgumentException("Services started transitioning asynchronously before "
503              + "the ServiceManager was constructed: " + servicesInBadStates);
504        }
505      } finally {
506        monitor.leave();
507      }
508    }
509
510    void addListener(Listener listener, Executor executor) {
511      checkNotNull(listener, "listener");
512      checkNotNull(executor, "executor");
513      monitor.enter();
514      try {
515        // no point in adding a listener that will never be called
516        if (!stoppedGuard.isSatisfied()) {
517          listeners.add(new ListenerCallQueue<Listener>(listener, executor));
518        }
519      } finally {
520        monitor.leave();
521      }
522    }
523
524    void awaitHealthy() {
525      monitor.enterWhenUninterruptibly(awaitHealthGuard);
526      try {
527        checkHealthy();
528      } finally {
529        monitor.leave();
530      }
531    }
532
533    void awaitHealthy(long timeout, TimeUnit unit) throws TimeoutException {
534      monitor.enter();
535      try {
536        if (!monitor.waitForUninterruptibly(awaitHealthGuard, timeout, unit)) {
537          throw new TimeoutException("Timeout waiting for the services to become healthy. The "
538              + "following services have not started: "
539              + Multimaps.filterKeys(servicesByState, in(ImmutableSet.of(NEW, STARTING))));
540        }
541        checkHealthy();
542      } finally {
543        monitor.leave();
544      }
545    }
546
547    void awaitStopped() {
548      monitor.enterWhenUninterruptibly(stoppedGuard);
549      monitor.leave();
550    }
551
552    void awaitStopped(long timeout, TimeUnit unit) throws TimeoutException {
553      monitor.enter();
554      try {
555        if (!monitor.waitForUninterruptibly(stoppedGuard, timeout, unit)) {
556          throw new TimeoutException("Timeout waiting for the services to stop. The following "
557              + "services have not stopped: "
558              + Multimaps.filterKeys(servicesByState,
559                  not(in(EnumSet.of(TERMINATED, FAILED)))));
560        }
561      } finally {
562        monitor.leave();
563      }
564    }
565
566    ImmutableMultimap<State, Service> servicesByState() {
567      ImmutableSetMultimap.Builder<State, Service> builder = ImmutableSetMultimap.builder();
568      monitor.enter();
569      try {
570        for (Entry<State, Service> entry : servicesByState.entries()) {
571          if (!(entry.getValue() instanceof NoOpService)) {
572            builder.put(entry);
573          }
574        }
575      } finally {
576        monitor.leave();
577      }
578      return builder.build();
579    }
580
581    ImmutableMap<Service, Long> startupTimes() {
582      List<Entry<Service, Long>> loadTimes;
583      monitor.enter();
584      try {
585        loadTimes = Lists.newArrayListWithCapacity(startupTimers.size());
586        // N.B. There will only be an entry in the map if the service has started
587        for (Entry<Service, Stopwatch> entry : startupTimers.entrySet()) {
588          Service service = entry.getKey();
589          Stopwatch stopWatch = entry.getValue();
590          if (!stopWatch.isRunning() && !(service instanceof NoOpService)) {
591            loadTimes.add(Maps.immutableEntry(service, stopWatch.elapsed(MILLISECONDS)));
592          }
593        }
594      } finally {
595        monitor.leave();
596      }
597      Collections.sort(loadTimes, Ordering.natural()
598          .onResultOf(new Function<Entry<Service, Long>, Long>() {
599            @Override public Long apply(Map.Entry<Service, Long> input) {
600              return input.getValue();
601            }
602          }));
603      return ImmutableMap.copyOf(loadTimes);
604    }
605
606    /**
607     * Updates the state with the given service transition.
608     *
609     * <p>This method performs the main logic of ServiceManager in the following steps.
610     * <ol>
611     *      <li>Update the {@link #servicesByState()}
612     *      <li>Update the {@link #startupTimers}
613     *      <li>Based on the new state queue listeners to run
614     *      <li>Run the listeners (outside of the lock)
615     * </ol>
616     */
617    void transitionService(final Service service, State from, State to) {
618      checkNotNull(service);
619      checkArgument(from != to);
620      monitor.enter();
621      try {
622        transitioned = true;
623        if (!ready) {
624          return;
625        }
626        // Update state.
627        checkState(servicesByState.remove(from, service),
628            "Service %s not at the expected location in the state map %s", service, from);
629        checkState(servicesByState.put(to, service),
630            "Service %s in the state map unexpectedly at %s", service, to);
631        // Update the timer
632        Stopwatch stopwatch = startupTimers.get(service);
633        if (stopwatch == null) {
634          // This means the service was started by some means other than ServiceManager.startAsync
635          stopwatch = Stopwatch.createStarted();
636          startupTimers.put(service, stopwatch);
637        }
638        if (to.compareTo(RUNNING) >= 0 && stopwatch.isRunning()) {
639          // N.B. if we miss the STARTING event then we may never record a startup time.
640          stopwatch.stop();
641          if (!(service instanceof NoOpService)) {
642            logger.log(Level.FINE, "Started {0} in {1}.", new Object[] {service, stopwatch});
643          }
644        }
645        // Queue our listeners
646
647        // Did a service fail?
648        if (to == FAILED) {
649          fireFailedListeners(service);
650        }
651
652        if (states.count(RUNNING) == numberOfServices) {
653          // This means that the manager is currently healthy. N.B. If other threads call isHealthy
654          // they are not guaranteed to get 'true', because any service could fail right now.
655          fireHealthyListeners();
656        } else if (states.count(TERMINATED) + states.count(FAILED) == numberOfServices) {
657          fireStoppedListeners();
658        }
659      } finally {
660        monitor.leave();
661        // Run our executors outside of the lock
662        executeListeners();
663      }
664    }
665
666    @GuardedBy("monitor")
667    void fireStoppedListeners() {
668      STOPPED_CALLBACK.enqueueOn(listeners);
669    }
670
671    @GuardedBy("monitor")
672    void fireHealthyListeners() {
673      HEALTHY_CALLBACK.enqueueOn(listeners);
674    }
675
676    @GuardedBy("monitor")
677    void fireFailedListeners(final Service service) {
678      new Callback<Listener>("failed({service=" + service + "})") {
679        @Override void call(Listener listener) {
680          listener.failure(service);
681        }
682      }.enqueueOn(listeners);
683    }
684
685    /** Attempts to execute all the listeners in {@link #listeners}. */
686    void executeListeners() {
687      checkState(!monitor.isOccupiedByCurrentThread(),
688          "It is incorrect to execute listeners with the monitor held.");
689      // iterate by index to avoid concurrent modification exceptions
690      for (int i = 0; i < listeners.size(); i++) {
691        listeners.get(i).execute();
692      }
693    }
694
695    @GuardedBy("monitor")
696    void checkHealthy() {
697      if (states.count(RUNNING) != numberOfServices) {
698        IllegalStateException exception = new IllegalStateException(
699            "Expected to be healthy after starting. The following services are not running: "
700                + Multimaps.filterKeys(servicesByState, not(equalTo(RUNNING))));
701        throw exception;
702      }
703    }
704  }
705
706  /**
707   * A {@link Service} that wraps another service and times how long it takes for it to start and
708   * also calls the {@link ServiceManagerState#transitionService(Service, State, State)},
709   * to record the state transitions.
710   */
711  private static final class ServiceListener extends Service.Listener {
712    final Service service;
713    // We store the state in a weak reference to ensure that if something went wrong while
714    // constructing the ServiceManager we don't pointlessly keep updating the state.
715    final WeakReference<ServiceManagerState> state;
716
717    ServiceListener(Service service, WeakReference<ServiceManagerState> state) {
718      this.service = service;
719      this.state = state;
720    }
721
722    @Override public void starting() {
723      ServiceManagerState state = this.state.get();
724      if (state != null) {
725        state.transitionService(service, NEW, STARTING);
726        if (!(service instanceof NoOpService)) {
727          logger.log(Level.FINE, "Starting {0}.", service);
728        }
729      }
730    }
731
732    @Override public void running() {
733      ServiceManagerState state = this.state.get();
734      if (state != null) {
735        state.transitionService(service, STARTING, RUNNING);
736      }
737    }
738
739    @Override public void stopping(State from) {
740      ServiceManagerState state = this.state.get();
741      if (state != null) {
742        state.transitionService(service, from, STOPPING);
743      }
744    }
745
746    @Override public void terminated(State from) {
747      ServiceManagerState state = this.state.get();
748      if (state != null) {
749        if (!(service instanceof NoOpService)) {
750          logger.log(Level.FINE, "Service {0} has terminated. Previous state was: {1}",
751              new Object[] {service, from});
752        }
753        state.transitionService(service, from, TERMINATED);
754      }
755    }
756
757    @Override public void failed(State from, Throwable failure) {
758      ServiceManagerState state = this.state.get();
759      if (state != null) {
760        // Log before the transition, so that if the process exits in response to server failure,
761        // there is a higher likelihood that the cause will be in the logs.
762        if (!(service instanceof NoOpService) ) {
763          logger.log(Level.SEVERE, "Service " + service + " has failed in the " + from + " state.",
764              failure);
765        }
766        state.transitionService(service, from, FAILED);
767      }
768    }
769  }
770
771  /**
772   * A {@link Service} instance that does nothing.  This is only useful as a placeholder to
773   * ensure that the {@link ServiceManager} functions properly even when it is managing no services.
774   *
775   * <p>The use of this class is considered an implementation detail of ServiceManager and as such
776   * it is excluded from {@link #servicesByState}, {@link #startupTimes}, {@link #toString} and all
777   * logging statements.
778   */
779  private static final class NoOpService extends AbstractService {
780    @Override protected void doStart() { notifyStarted(); }
781    @Override protected void doStop() { notifyStopped(); }
782  }
783
784  /** This is never thrown but only used for logging. */
785  private static final class EmptyServiceManagerWarning extends Throwable {}
786}