dev.mccue.guava.concurrent.ServiceManager

public final class ServiceManager extends Object

A manager for monitoring and controlling a set of Service services. This class provides methods for #startAsync() starting, #stopAsync() stopping and #servicesByState inspecting a collection of Service services. Additionally, users can monitor state transitions with the Listener listener mechanism.

While it is recommended that service lifecycles be managed via this class, state transitions initiated via other mechanisms do not impact the correctness of its methods. For example, if the services are started by some mechanism besides #startAsync, the listeners will be invoked when appropriate and #awaitHealthy will still work as expected.

Here is a simple example of how to use a ServiceManager to start a server.


 class Server {
   public static void main(String[] args) {
     Set<Service> services = ...;
     ServiceManager manager = new ServiceManager(services);
     manager.addListener(new Listener() {
         public void stopped() {}
         public void healthy() {
           // Services have been initialized and are healthy, start accepting requests...
         }
         public void failure(Service service) {
           // Something failed, at this point we could log it, notify a load balancer, or take
           // some other action.  For now we will just exit.
           System.exit(1);
         }
       },
       MoreExecutors.directExecutor());

     Runtime.getRuntime().addShutdownHook(new Thread() {
       public void run() {
         // Give the services 5 seconds to stop to ensure that we are responsive to shutdown
         // requests.
         try {
           manager.stopAsync().awaitStopped(5, TimeUnit.SECONDS);
         } catch (TimeoutException timeout) {
           // stopping timed out
         }
       }
     });
     manager.startAsync();  // start all the services asynchronously
   }
 }

This class uses the ServiceManager's methods to start all of its services, to respond to service failure and to ensure that when the JVM is shutting down all the services are stopped.

Since:: 14.0
Author:: Luke Sandberg

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static class

ServiceManager.Listener

A listener for the aggregate state changes of the services that are under management.
Constructor Summary

Constructors

Constructor

Description

ServiceManager(Iterable<? extends Service> services)

Constructs a new instance for managing the given services.
Method Summary

Modifier and Type

Method

Description

void

addListener(ServiceManager.Listener listener, Executor executor)

Registers a Listener to be Executor#execute executed on the given executor.

void

awaitHealthy()

Waits for the ServiceManager to become #isHealthy() healthy.

void

awaitHealthy(long timeout, TimeUnit unit)

Waits for the ServiceManager to become #isHealthy() healthy for no more than the given time.

void

awaitHealthy(Duration timeout)

Waits for the ServiceManager to become #isHealthy() healthy for no more than the given time.

void

awaitStopped()

Waits for the all the services to reach a terminal state.

void

awaitStopped(long timeout, TimeUnit unit)

Waits for the all the services to reach a terminal state for no more than the given time.

void

awaitStopped(Duration timeout)

Waits for the all the services to reach a terminal state for no more than the given time.

boolean

isHealthy()

Returns true if all services are currently in the State#RUNNING running state.

dev.mccue.guava.collect.ImmutableSetMultimap<Service.State,Service>

servicesByState()

Provides a snapshot of the current state of all the services under management.

ServiceManager

startAsync()

Initiates service Service#startAsync startup on all the services being managed.

dev.mccue.guava.collect.ImmutableMap<Service,Duration>

startupDurations()

Returns the service load times.

dev.mccue.guava.collect.ImmutableMap<Service,Long>

startupTimes()

Returns the service load times.

ServiceManager

stopAsync()

Initiates service Service#stopAsync shutdown if necessary on all the services being managed.

String

toString()

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details
- ServiceManager
  
  public ServiceManager(Iterable<? extends Service> services)
  
  Constructs a new instance for managing the given services.
  
  Parameters:
  
  services - The services to manage
  
  Throws:
  
  IllegalArgumentException - if not all services are State#NEW new or if there are any duplicate services.
Method Details
- addListener
  
  public void addListener(ServiceManager.Listener listener, Executor executor)
  
  Registers a Listener to be Executor#execute executed on the given executor. The listener will not have previous state changes replayed, so it is suggested that listeners are added before any of the managed services are Service#startAsync started.
  addListener guarantees execution ordering across calls to a given listener but not across calls to multiple listeners. Specifically, a given listener will have its callbacks invoked in the same order as the underlying service enters those states. Additionally, at most one of the listener's callbacks will execute at once. However, multiple listeners' callbacks may execute concurrently, and listeners may execute in an order different from the one in which they were registered.
  RuntimeExceptions thrown by a listener will be caught and logged. Any exception thrown during Executor.execute (e.g., a RejectedExecutionException) will be caught and logged.
  When selecting an executor, note that directExecutor is dangerous in some cases. See the discussion in the ListenableFuture#addListener ListenableFuture.addListener documentation.
  
  Parameters:
  
  listener - the listener to run when the manager changes state
  
  executor - the executor in which the listeners callback methods will be run.
- startAsync
  
  @CanIgnoreReturnValue public ServiceManager startAsync()
  
  Initiates service Service#startAsync startup on all the services being managed. It is only valid to call this method if all of the services are State#NEW new.
  
  Returns:
  
  this
  
  Throws:
  
  IllegalStateException - if any of the Services are not State#NEW new when the method is called.
- awaitHealthy
  
  public void awaitHealthy()
  
  Waits for the ServiceManager to become #isHealthy() healthy. The manager will become healthy after all the component services have reached the State#RUNNING running state.
  
  Throws:
  
  IllegalStateException - if the service manager reaches a state from which it cannot become #isHealthy() healthy.
- awaitHealthy
  
  public void awaitHealthy(Duration timeout) throws TimeoutException
  
  Waits for the ServiceManager to become #isHealthy() healthy for no more than the given time. The manager will become healthy after all the component services have reached the State#RUNNING running state.
  
  Parameters:
  
  timeout - the maximum time to wait
  
  Throws:
  
  TimeoutException - if not all of the services have finished starting within the deadline
  
  IllegalStateException - if the service manager reaches a state from which it cannot become #isHealthy() healthy.
  
  Since:
  
  28.0
- awaitHealthy
  
  public void awaitHealthy(long timeout, TimeUnit unit) throws TimeoutException
  
  Waits for the ServiceManager to become #isHealthy() healthy for no more than the given time. The manager will become healthy after all the component services have reached the State#RUNNING running state.
  
  Parameters:
  
  timeout - the maximum time to wait
  
  unit - the time unit of the timeout argument
  
  Throws:
  
  TimeoutException - if not all of the services have finished starting within the deadline
  
  IllegalStateException - if the service manager reaches a state from which it cannot become #isHealthy() healthy.
- stopAsync
  
  @CanIgnoreReturnValue public ServiceManager stopAsync()
  
  Initiates service Service#stopAsync shutdown if necessary on all the services being managed.
  
  Returns:
  
  this
- awaitStopped
  
  public void awaitStopped()
  
  Waits for the all the services to reach a terminal state. After this method returns all services will either be Service.State#TERMINATED terminated or Service.State#FAILED failed.
- awaitStopped
  
  public void awaitStopped(Duration timeout) throws TimeoutException
  
  Waits for the all the services to reach a terminal state for no more than the given time. After this method returns all services will either be Service.State#TERMINATED terminated or Service.State#FAILED failed.
  
  Parameters:
  
  timeout - the maximum time to wait
  
  Throws:
  
  TimeoutException - if not all of the services have stopped within the deadline
  
  Since:
  
  28.0
- awaitStopped
  
  public void awaitStopped(long timeout, TimeUnit unit) throws TimeoutException
  
  Waits for the all the services to reach a terminal state for no more than the given time. After this method returns all services will either be Service.State#TERMINATED terminated or Service.State#FAILED failed.
  
  Parameters:
  
  timeout - the maximum time to wait
  
  unit - the time unit of the timeout argument
  
  Throws:
  
  TimeoutException - if not all of the services have stopped within the deadline
- isHealthy
  
  public boolean isHealthy()
  
  Returns true if all services are currently in the State#RUNNING running state.
  Users who want more detailed information should use the #servicesByState method to get detailed information about which services are not running.
- servicesByState
  
  public dev.mccue.guava.collect.ImmutableSetMultimap<Service.State,Service> servicesByState()
  
  Provides a snapshot of the current state of all the services under management.
  N.B. This snapshot is guaranteed to be consistent, i.e. the set of states returned will correspond to a point in time view of the services.
  
  Since:
  
  29.0 (present with return type ImmutableMultimap since 14.0)
- startupTimes
  
  public dev.mccue.guava.collect.ImmutableMap<Service,Long> startupTimes()
  
  Returns the service load times. This value will only return startup times for services that have finished starting.
  
  Returns:
  
  Map of services and their corresponding startup time in millis, the map entries will be ordered by startup time.
- startupDurations
  
  public dev.mccue.guava.collect.ImmutableMap<Service,Duration> startupDurations()
  
  Returns the service load times. This value will only return startup times for services that have finished starting.
  
  Returns:
  
  Map of services and their corresponding startup time, the map entries will be ordered by startup time.
  
  Since:
  
  31.0
- toString
  
  public String toString()
  
  Overrides:
  
  toString in class Object

Class ServiceManager

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

ServiceManager

Method Details

addListener

startAsync

awaitHealthy

awaitHealthy

awaitHealthy

stopAsync

awaitStopped

awaitStopped

awaitStopped

isHealthy

servicesByState

startupTimes

startupDurations

toString