Base class for services that can implement startUp and shutDown but while in the "running" state need to perform a periodic task. Subclasses can implement startUp, shutDown and also a runOneIteration method that will be executed periodically.

This class uses the ScheduledExecutorService returned from executor to run the startUp and shutDown methods and also uses that service to schedule the runOneIteration that will be executed periodically as specified by its Scheduler. When this service is asked to stop via stopAsync it will cancel the periodic task (but not interrupt it) and wait for it to stop before running the shutDown method.

Subclasses are guaranteed that the life cycle methods (runOneIteration, startUp and shutDown) will never run concurrently. Notably, if any execution of runOneIteration takes longer than its schedule defines, then subsequent executions may start late. Also, all life cycle methods are executed with a lock held, so subclasses can safely modify shared state without additional synchronization necessary for visibility to later executions of the life cycle methods.

Usage Example

Here is a sketch of a service which crawls a website and uses the scheduling capabilities to rate limit itself.

class CrawlingService extends AbstractScheduledService {
  private Set<Uri> visited;
  private Queue<Uri> toCrawl;
  protected void startUp() throws Exception {
    toCrawl = readStartingUris();
  }

  protected void runOneIteration() throws Exception {
    Uri uri = toCrawl.remove();
    Collection<Uri> newUris = crawl(uri);
    visited.add(uri);
    for (Uri newUri : newUris) {
      if (!visited.contains(newUri)) { toCrawl.add(newUri); }
    }
  }

  protected void shutDown() throws Exception {
    saveUris(toCrawl);
  }

  protected Scheduler scheduler() {
    return Scheduler.newFixedRateSchedule(0, 1, TimeUnit.SECONDS);
  }
}

This class uses the life cycle methods to read in a list of starting URIs and save the set of outstanding URIs when shutting down. Also, it takes advantage of the scheduling functionality to rate limit the number of queries we perform.