AbstractScheduledService (Guava: Google Core Libraries for Java 12.0 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.google.common.util.concurrent
Class AbstractScheduledService

java.lang.Object
  com.google.common.util.concurrent.AbstractScheduledService

All Implemented Interfaces:: Service

@Beta public abstract class AbstractScheduledService
extends Object
implements Service
extends Object
implements Service

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 AbstractScheduledService.Scheduler. When this service is asked to stop via stop() or stopAndWait(), 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.

Since:: 11.0
Author:: Luke Sandberg

Nested Class Summary
`static class`	`AbstractScheduledService.CustomScheduler` A `AbstractScheduledService.Scheduler` that provides a convenient way for the `AbstractScheduledService` to use a dynamically changing schedule.
`static class`	`AbstractScheduledService.Scheduler` A scheduler defines the policy for how the `AbstractScheduledService` should run its task.

Nested classes/interfaces inherited from interface com.google.common.util.concurrent.Service
`Service.State`

Constructor Summary
`AbstractScheduledService()`

Method Summary
`protected ScheduledExecutorService`	`executor()` Returns the `ScheduledExecutorService` that will be used to execute the `startUp()`, `runOneIteration()` and `shutDown()` methods.
`boolean`	`isRunning()` Returns `true` if this service is running.
`protected abstract void`	`runOneIteration()` Run one iteration of the scheduled task.
`protected abstract AbstractScheduledService.Scheduler`	`scheduler()` Returns the `AbstractScheduledService.Scheduler` object used to configure this service.
`protected 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 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()`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

AbstractScheduledService

public AbstractScheduledService()

Method Detail

runOneIteration

protected abstract void runOneIteration()
                                 throws Exception

Run one iteration of the scheduled task. If any invocation of this method throws an exception, the service will transition to the Service.State.FAILED state and this method will no longer be called.

Throws:: Exception

startUp

protected void startUp()
                throws Exception

Start the service.

By default this method does nothing.

Throws:: Exception

shutDown

protected void shutDown()
                 throws Exception

Stop the service. This is guaranteed not to run concurrently with runOneIteration().

By default this method does nothing.

Throws:: Exception

scheduler

protected abstract AbstractScheduledService.Scheduler scheduler()

Returns the AbstractScheduledService.Scheduler object used to configure this service. This method will only be called once.

executor

protected ScheduledExecutorService executor()

Returns the ScheduledExecutorService that will be used to execute the startUp(), runOneIteration() and shutDown() methods. The executor will not be ExecutorService.shutdown() when this service stops. Subclasses may override this method to use a custom ScheduledExecutorService instance.

By default this returns a new ScheduledExecutorService with a single thread thread pool. This method will only be called once.

toString

public String toString()

Overrides:: toString in class Object