Module javafx.graphics
Package javafx.concurrent

Class ScheduledService<V>

java.lang.Object
javafx.concurrent.Service<V>
javafx.concurrent.ScheduledService<V>
Type Parameters:
V - The computed value of the ScheduledService
All Implemented Interfaces:
Worker<V>, EventTarget
public abstract class ScheduledService<V> extends Service<V>

The ScheduledService is a Service that will automatically restart itself after a successful execution, and under some conditions will restart even in case of failure. A new ScheduledService begins in the READY state, just as a normal Service. After calling start or restart, the ScheduledService will enter the SCHEDULED state for the duration specified by delay.

Once RUNNING, the ScheduledService will execute its Task. On successful completion, the ScheduledService will transition to the SUCCEEDED state, and then to the READY state and back to the SCHEDULED state. The amount of time the ScheduledService will remain in this state depends on the amount of time between the last state transition to RUNNING, and the current time, and the period. In short, the period defines the minimum amount of time from the start of one run and the start of the next. If the previous execution completed before period expires, then the ScheduledService will remain in the SCHEDULED state until the period expires. If on the other hand the execution took longer than the specified period, then the ScheduledService will immediately transition back to RUNNING.

If, while RUNNING, the ScheduledService's Task throws an error or in some other way ends up transitioning to FAILED, then the ScheduledService will either restart or quit, depending on the values for backoffStrategy, restartOnFailure, and maximumFailureCount.

If a failure occurs and restartOnFailure is false, then the ScheduledService will transition to FAILED and will stop. To restart a failed ScheduledService, you must call restart manually.

If a failure occurs and restartOnFailure is true, then the the ScheduledService may restart automatically. First, the result of calling backoffStrategy will become the new cumulativePeriod. In this way, after each failure, you can cause the service to wait a longer and longer period of time before restarting. Once the task completes successfully, the cumulativePeriod is reset to the value of period.

ScheduledService defines static EXPONENTIAL_BACKOFF_STRATEGY and LOGARITHMIC_BACKOFF_STRATEGY implementations, of which LOGARITHMIC_BACKOFF_STRATEGY is the default value for backoffStrategy. After maximumFailureCount is reached, the ScheduledService will transition to FAILED in exactly the same way as if restartOnFailure were false.

If the period or delay is changed while the ScheduledService is running, the new values will be taken into account on the next iteration. For example, if the period is increased, then the next time the ScheduledService enters the SCHEDULED state, the new period will be used. Likewise, if the delay is changed, the new value will be honored on the next restart or reset/start.

The ScheduledService is typically used for use cases that involve polling. For example, you may want to ping a server on a regular basis to see if there are any updates. Such as ScheduledService might be implemented like this: 

 ScheduledService<Document> svc = new ScheduledService<Document>() {
     protected Task<Document> createTask() {
         return new Task<Document>() {
             protected Document call() {
                 // Connect to a Server
                 // Get the XML document
                 // Parse it into a document
                 return document;
             }
         };
     }
 };
 svc.setPeriod(Duration.seconds(1));
This example will ping the remote server every 1 second.

Timing for this class is not absolutely reliable. A very busy event thread might introduce some timing lag into the beginning of the execution of the background Task, so very small values for the period or delay are likely to be inaccurate. A delay or period in the hundreds of milliseconds or larger should be fairly reliable.

The ScheduledService in its default configuration has a default period of 0 and a default delay of 0. This will cause the ScheduledService to execute the task immediately upon Service.start(), and re-executing immediately upon successful completion.

For this purposes of this class, any Duration that answers true to Duration.isUnknown() will treat that duration as if it were Duration.ZERO. Likewise, any Duration which answers true to Duration.isIndefinite() will be treated as if it were a duration of Double.MAX_VALUE milliseconds. Any null Duration is treated as Duration.ZERO. Any custom implementation of a backoff strategy callback must be prepared to handle these different potential values.

The ScheduledService introduces a new property called lastValue. The lastValue is the value that was last successfully computed. Because a Service clears its value property on each run, and because the ScheduledService will reschedule a run immediately after completion (unless it enters the cancelled or failed states), the value property is not overly useful on a ScheduledService. In most cases you will want to instead use the value returned by lastValue.

Implementation Note:
The Service.ready(), Service.scheduled(), Service.running(), succeeded(), Service.cancelled(), and failed() methods are implemented in this class. Subclasses which also override these methods must take care to invoke the super implementation.
Since:
JavaFX 8.0