com.google.common.util.concurrent
Class AbstractIdleService

java.lang.Object
  extended by com.google.common.util.concurrent.AbstractIdleService
All Implemented Interfaces:
Service

@Beta
public abstract class AbstractIdleService
extends Object
implements Service

Base class for services that do not need a thread while "running" but may need one during startup and shutdown. Subclasses can implement startUp() and shutDown() methods, each which run in a executor which by default uses a separate thread for each method.

Since:
1
Author:
Chris Nokleberg

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.google.common.util.concurrent.Service
Service.State
 
Constructor Summary
AbstractIdleService()
           
 
Method Summary
protected  Executor executor(Service.State state)
          Returns the Executor that will be used to run this service.
 boolean isRunning()
          Returns true if this service is running.
protected abstract  void shutDown()
          Stop the service.
 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.
protected abstract  void startUp()
          Start the service.
 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.
 String toString()
          Returns a string representation of the object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AbstractIdleService

public AbstractIdleService()
Method Detail

startUp

protected abstract void startUp()
                         throws Exception
Start the service.

Throws:
Exception

shutDown

protected abstract void shutDown()
                          throws Exception
Stop the service.

Throws:
Exception

executor

protected Executor executor(Service.State state)
Returns the Executor that will be used to run this service. Subclasses may override this method to use a custom Executor, which may configure its worker thread with a specific name, thread group or priority. The returned executor's execute() method is called when this service is started and stopped, and should return promptly.

Parameters:
state - Service.State.STARTING or Service.State.STOPPING, used by the default implementation for naming the thread

toString

public String toString()
Description copied from class: java.lang.Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:
toString in class Object
Returns:
a string representation of the object.

start

public final ListenableFuture<Service.State> start()
Description copied from interface: Service
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.

Specified by:
start in interface Service
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 the returned future is unsupported and always returns false.

startAndWait

public final Service.State startAndWait()
Description copied from interface: Service
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.

Specified by:
startAndWait in interface Service
Returns:
the state of the service when startup finished.

isRunning

public final boolean isRunning()
Description copied from interface: Service
Returns true if this service is running.

Specified by:
isRunning in interface Service

state

public final Service.State state()
Description copied from interface: Service
Returns the lifecycle state of the service.

Specified by:
state in interface Service

stop

public final ListenableFuture<Service.State> stop()
Description copied from interface: Service
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.

Specified by:
stop in interface Service
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 is unsupported and always returns false.

stopAndWait

public final Service.State stopAndWait()
Description copied from interface: Service
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.

Specified by:
stopAndWait in interface Service
Returns:
the state of the service when shutdown finished.