## com.google.common.util.concurrent
Interface Service

All Known Implementing Classes:
  AbstractExecutionThreadService, AbstractIdleService, AbstractScheduledService, AbstractService, ForwardingService

    @Beta
    public interface Service

An object with an operational state, plus asynchronous `start()` and `stop()` lifecycle methods to transition between states. Example services include webservers, RPC servers and timers.

The normal lifecycle of a service is:

- NEW ->
- STARTING ->
- RUNNING ->
- STOPPING ->
- TERMINATED

There are deviations from this if there are failures or if `stop()` is called before the `Service` reaches the RUNNING state. The set of legal transitions form a DAG, therefore every method of the listener will be called at most once. N.B. The `Service.State.FAILED` and `Service.State.TERMINATED` states are terminal states, once a service enters either of these states it cannot ever leave them.

Implementors of this interface are strongly encouraged to extend one of the abstract classes in this package which implement this interface and make the threading and state management easier.

Since:
  9.0 (in 1.0 as `com.google.common.base.Service`)
Author:
  Jesse Wilson, Luke Sandberg

Nested Class Summary
`static interface` `Service.Listener` A listener for the various state changes that a `Service` goes through in its lifecycle.
`static class` `Service.State` The lifecycle states of a service.

Method Summary
`void` `addListener(Service.Listener listener, Executor executor)` Registers a `Service.Listener` to be executed on the given executor.
`boolean` `isRunning()` Returns `true` if this service is running.
`ListenableFuture<Service.State>` `start()` If the service state is `Service.State.NEW`, this initiates service startup and returns immediately.
`Service.State` `startAndWait()` Initiates service startup (if necessary), returning once the service has finished starting.
`Service.State` `state()` Returns the lifecycle state of the service.
`ListenableFuture<Service.State>` `stop()` If the service is starting or running, this initiates service shutdown and returns immediately.
`Service.State` `stopAndWait()` Initiates service shutdown (if necessary), returning once the service has finished stopping.

Method Detail

### start

    ListenableFuture<Service.State> start()

  If the service state is `Service.State.NEW`, this initiates service startup and returns immediately. If the service has already been started, this method returns immediately without taking action. A stopped service may not be restarted.

  Returns:
    a future for the startup result, regardless of whether this call initiated startup. Calling `Future.get()` will block until the service has finished starting, and returns one of `Service.State.RUNNING`, `Service.State.STOPPING` or `Service.State.TERMINATED`. If the service fails to start, `Future.get()` will throw an `ExecutionException`, and the service's state will be `Service.State.FAILED`. If it has already finished starting, `Future.get()` returns immediately. Cancelling this future has no effect on the service.

### startAndWait

    Service.State startAndWait()

  Initiates service startup (if necessary), returning once the service has finished starting. Unlike calling `start().get()`, this method throws no checked exceptions, and it cannot be interrupted.

  Returns:
    the state of the service when startup finished.
  Throws:
    `UncheckedExecutionException` - if startup failed

### isRunning

    boolean isRunning()

  Returns `true` if this service is running.

### state

    Service.State state()

  Returns the lifecycle state of the service.

### stop

    ListenableFuture<Service.State> stop()

  If the service is starting or running, this initiates service shutdown and returns immediately. If the service is new, it is terminated without having been started nor stopped. If the service has already been stopped, this method returns immediately without taking action.

  Returns:
    a future for the shutdown result, regardless of whether this call initiated shutdown. Calling `Future.get()` will block until the service has finished shutting down, and either returns `Service.State.TERMINATED` or throws an `ExecutionException`. If it has already finished stopping, `Future.get()` returns immediately. Cancelling this future has no effect on the service.

### stopAndWait

    Service.State stopAndWait()

  Initiates service shutdown (if necessary), returning once the service has finished stopping. If this is `Service.State.STARTING`, startup will be cancelled. If this is `Service.State.NEW`, it is `terminated` without having been started nor stopped. Unlike calling `stop().get()`, this method throws no checked exceptions.

  Returns:
    the state of the service when shutdown finished.
  Throws:
    `UncheckedExecutionException` - if the service has failed or fails during shutdown

### addListener

    void addListener(Service.Listener listener,
                     Executor executor)

  Registers a `Service.Listener` to be executed on the given executor. The listener will have the corresponding transition method called whenever the service changes state. The listener will not have previous state changes replayed, so it is suggested that listeners are added before the service starts.

  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.

  Parameters:
    `listener` - the listener to run when the service changes state is complete
    `executor` - 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()`.
  Since:
    13.0

Copyright © 2010-2012. All Rights Reserved.