Class ServiceManager
- All Implemented Interfaces:
ServiceManagerBridge
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
This is never thrown but only used for logging.private static final class
static class
A listener for the aggregate state changes of the services that are under management.private static final class
AService
instance that does nothing.private static final class
AService
that wraps another service and times how long it takes for it to start and also calls theServiceManager.ServiceManagerState.transitionService(Service, State, State)
, to record the state transitions.private static final class
An encapsulation of all the mutable state of theServiceManager
that needs to be accessed by instances ofServiceManager.ServiceListener
. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final ListenerCallQueue.Event
<ServiceManager.Listener> private static final LazyLogger
private final ImmutableList
<Service> private final ServiceManager.ServiceManagerState
An encapsulation of all of the state that is accessed by the service listeners.private static final ListenerCallQueue.Event
<ServiceManager.Listener> -
Constructor Summary
ConstructorsConstructorDescriptionServiceManager
(Iterable<? extends Service> services) Constructs a new instance for managing the given services. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addListener
(ServiceManager.Listener listener, Executor executor) Registers aServiceManager.Listener
to be executed on the given executor.void
Waits for theServiceManager
to become healthy.void
awaitHealthy
(long timeout, TimeUnit unit) Waits for theServiceManager
to become healthy for no more than the given time.void
awaitHealthy
(Duration timeout) Waits for theServiceManager
to become healthy for no more than the given time.void
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
Returns true if all services are currently in the running state.Provides a snapshot of the current state of all the services under management.Initiates service startup on all the services being managed.Returns the service load times.Returns the service load times.Initiates service shutdown if necessary on all the services being managed.toString()
-
Field Details
-
logger
-
HEALTHY_EVENT
-
STOPPED_EVENT
-
state
An encapsulation of all of the state that is accessed by the service listeners. This is extracted into its own object so thatServiceManager.ServiceListener
could be madestatic
and its instances can be safely constructed and added in theServiceManager
constructor without having to close over the partially constructedServiceManager
instance (i.e. avoid leaking a pointer tothis
). -
services
-
-
Constructor Details
-
ServiceManager
Constructs a new instance for managing the given services.- Parameters:
services
- The services to manage- Throws:
IllegalArgumentException
- if not all services are new or if there are any duplicate services.
-
-
Method Details
-
addListener
Registers aServiceManager.Listener
to be 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 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., aRejectedExecutionException
) will be caught and logged.When selecting an executor, note that
directExecutor
is dangerous in some cases. See the discussion in theListenableFuture.addListener
documentation.- Parameters:
listener
- the listener to run when the manager changes stateexecutor
- the executor in which the listeners callback methods will be run.
-
startAsync
Initiates service startup on all the services being managed. It is only valid to call this method if all of the services are new.- Returns:
- this
- Throws:
IllegalStateException
- if any of the Services are notnew
when the method is called.
-
awaitHealthy
public void awaitHealthy()Waits for theServiceManager
to become healthy. The manager will become healthy after all the component services have reached the running state.- Throws:
IllegalStateException
- if the service manager reaches a state from which it cannot become healthy.
-
awaitHealthy
Waits for theServiceManager
to become healthy for no more than the given time. The manager will become healthy after all the component services have reached the running state.- Parameters:
timeout
- the maximum time to wait- Throws:
TimeoutException
- if not all of the services have finished starting within the deadlineIllegalStateException
- if the service manager reaches a state from which it cannot become healthy.- Since:
- 28.0
-
awaitHealthy
Waits for theServiceManager
to become healthy for no more than the given time. The manager will become healthy after all the component services have reached the running state.- Parameters:
timeout
- the maximum time to waitunit
- the time unit of the timeout argument- Throws:
TimeoutException
- if not all of the services have finished starting within the deadlineIllegalStateException
- if the service manager reaches a state from which it cannot become healthy.
-
stopAsync
Initiates service 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 terminated or failed. -
awaitStopped
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 terminated or 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
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 terminated or failed.- Parameters:
timeout
- the maximum time to waitunit
- 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 running state.Users who want more detailed information should use the
servicesByState()
method to get detailed information about which services are not running. -
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.
- Specified by:
servicesByState
in interfaceServiceManagerBridge
- Since:
- 29.0 (present with return type
ImmutableMultimap
since 14.0)
-
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
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
-