|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.google.common.util.concurrent.ServiceManager
@Beta @Singleton public final class ServiceManager
A manager for monitoring and controlling a set of services
. This class provides
methods for starting, stopping and
inspecting a collection of services.
Additionally, users can monitor state transitions with the 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.sameThreadExecutor());
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.
Nested Class Summary | |
---|---|
static interface |
ServiceManager.Listener
A listener for the aggregate state changes of the services that are under management. |
Constructor Summary | |
---|---|
ServiceManager(java.lang.Iterable<? extends Service> services)
Constructs a new instance for managing the given services. |
Method Summary | |
---|---|
void |
addListener(ServiceManager.Listener listener,
java.util.concurrent.Executor executor)
Registers a ServiceManager.Listener to be executed on the given
executor. |
void |
awaitHealthy()
Waits for the ServiceManager to become healthy. |
void |
awaitHealthy(long timeout,
java.util.concurrent.TimeUnit unit)
Waits for the ServiceManager to become 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,
java.util.concurrent.TimeUnit unit)
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 running state. |
ImmutableMultimap<Service.State,Service> |
servicesByState()
Provides a snapshot of the current state of all the services under management. |
ServiceManager |
startAsync()
Initiates service startup on all the services being managed. |
ImmutableMap<Service,java.lang.Long> |
startupTimes()
Returns the service load times. |
ServiceManager |
stopAsync()
Initiates service shutdown if necessary on all the services being managed. |
java.lang.String |
toString()
|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public ServiceManager(java.lang.Iterable<? extends Service> services)
services
- The services to manage
java.lang.IllegalArgumentException
- if not all services are new
or if there are
any duplicate services.Method Detail |
---|
public void addListener(ServiceManager.Listener listener, java.util.concurrent.Executor executor)
ServiceManager.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.
There is no guaranteed ordering of execution of listeners, but any listener added through this method is guaranteed to be called whenever there is a state change.
Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown
during Executor.execute
(e.g., a RejectedExecutionException
or an exception
thrown by inline execution) will be caught and
logged.
listener
- the listener to run when the manager changes stateexecutor
- the executor in which the the listeners callback methods will be run. For fast,
lightweight listeners that would be safe to execute in any thread, consider
MoreExecutors.sameThreadExecutor()
.public ServiceManager startAsync()
java.lang.IllegalStateException
- if any of the Services are not new
when the
method is called, terminated
or failed
.public void awaitHealthy()
ServiceManager
to become healthy. The manager
will become healthy after all the component services have reached the running state.
java.lang.IllegalStateException
- if the service manager reaches a state from which it cannot
become healthy.public void awaitHealthy(long timeout, java.util.concurrent.TimeUnit unit) throws java.util.concurrent.TimeoutException
ServiceManager
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.
timeout
- the maximum time to waitunit
- the time unit of the timeout argument
java.util.concurrent.TimeoutException
- if not all of the services have finished starting within the deadline
java.lang.IllegalStateException
- if the service manager reaches a state from which it cannot
become healthy.public ServiceManager stopAsync()
public void awaitStopped()
terminated
or
failed
public void awaitStopped(long timeout, java.util.concurrent.TimeUnit unit) throws java.util.concurrent.TimeoutException
terminated
or
failed
timeout
- the maximum time to waitunit
- the time unit of the timeout argument
java.util.concurrent.TimeoutException
- if not all of the services have stopped within the deadlinepublic boolean isHealthy()
Users who want more detailed information should use the servicesByState()
method to
get detailed information about which services are not running.
public ImmutableMultimap<Service.State,Service> servicesByState()
N.B. This snapshot it not guaranteed to be consistent, i.e. the set of states returned may not correspond to any particular point in time view of the services.
public ImmutableMap<Service,java.lang.Long> startupTimes()
public java.lang.String toString()
toString
in class java.lang.Object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |