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