- Type Parameters:
V
- The computed value of the ScheduledService
- All Implemented Interfaces:
Worker<V>
,EventTarget
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.
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()
, andfailed()
methods are implemented in this class. Subclasses which also override these methods must take care to invoke the super implementation. - Since:
- JavaFX 8.0
-
Property Summary
TypePropertyDescriptionfinal ObjectProperty
<Callback<ScheduledService<?>, Duration>> Computes the amount of time to add to the period on each failure.final ReadOnlyObjectProperty
<Duration> The current cumulative period in use between iterations.final ReadOnlyIntegerProperty
The current number of times the ScheduledService has failed.final ObjectProperty
<Duration> The initial delay between when the ScheduledService is first started, and when it will begin operation.final ReadOnlyObjectProperty
<V> The last successfully computed value.final ObjectProperty
<Duration> The maximum allowed value for the cumulativePeriod.final IntegerProperty
The maximum number of times the ScheduledService can fail before it simply ends in the FAILED state.final ObjectProperty
<Duration> The minimum amount of time to allow between the start of the last run and the start of the next run.final BooleanProperty
Indicates whether the ScheduledService should automatically restart in the case of a failure in the Task. -
Nested Class Summary
Nested classes/interfaces declared in interface javafx.concurrent.Worker
Worker.State
-
Field Summary
Modifier and TypeFieldDescriptionstatic final Callback
<ScheduledService<?>, Duration> A Callback implementation for thebackoffStrategy
property which will exponentially backoff the period between re-executions in the case of a failure.static final Callback
<ScheduledService<?>, Duration> A Callback implementation for thebackoffStrategy
property which will linearly backoff the period between re-executions in the case of a failure.static final Callback
<ScheduledService<?>, Duration> A Callback implementation for thebackoffStrategy
property which will logarithmically backoff the period between re-executions in the case of a failure. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionfinal ObjectProperty
<Callback<ScheduledService<?>, Duration>> Computes the amount of time to add to the period on each failure.boolean
cancel()
Cancels any currently running task and stops this scheduled service, such that no additional iterations will occur.final ReadOnlyObjectProperty
<Duration> The current cumulative period in use between iterations.final ReadOnlyIntegerProperty
The current number of times the ScheduledService has failed.final ObjectProperty
<Duration> The initial delay between when the ScheduledService is first started, and when it will begin operation.protected void
failed()
A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the FAILED state.final Callback
<ScheduledService<?>, Duration> Gets the value of thebackoffStrategy
property.final Duration
Gets the value of thecumulativePeriod
property.final int
Gets the value of thecurrentFailureCount
property.final Duration
getDelay()
Gets the value of thedelay
property.final V
Gets the value of thelastValue
property.final Duration
Gets the value of themaximumCumulativePeriod
property.final int
Gets the value of themaximumFailureCount
property.final Duration
Gets the value of theperiod
property.final boolean
Gets the value of therestartOnFailure
property.final ReadOnlyObjectProperty
<V> The last successfully computed value.final ObjectProperty
<Duration> The maximum allowed value for the cumulativePeriod.final IntegerProperty
The maximum number of times the ScheduledService can fail before it simply ends in the FAILED state.final ObjectProperty
<Duration> The minimum amount of time to allow between the start of the last run and the start of the next run.void
reset()
Resets the Service.final BooleanProperty
Indicates whether the ScheduledService should automatically restart in the case of a failure in the Task.final void
setBackoffStrategy
(Callback<ScheduledService<?>, Duration> value) Sets the value of thebackoffStrategy
property.final void
Sets the value of thedelay
property.final void
Sets the value of themaximumCumulativePeriod
property.final void
setMaximumFailureCount
(int value) Sets the value of themaximumFailureCount
property.final void
Sets the value of theperiod
property.final void
setRestartOnFailure
(boolean value) Sets the value of therestartOnFailure
property.protected void
A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the SUCCEEDED state.Methods declared in class javafx.concurrent.Service
addEventFilter, addEventHandler, buildEventDispatchChain, cancelled, createTask, exceptionProperty, executeTask, executorProperty, fireEvent, getException, getExecutor, getMessage, getOnCancelled, getOnFailed, getOnReady, getOnRunning, getOnScheduled, getOnSucceeded, getProgress, getState, getTitle, getTotalWork, getValue, getWorkDone, isRunning, messageProperty, onCancelledProperty, onFailedProperty, onReadyProperty, onRunningProperty, onScheduledProperty, onSucceededProperty, progressProperty, ready, removeEventFilter, removeEventHandler, restart, running, runningProperty, scheduled, setEventHandler, setExecutor, setOnCancelled, setOnFailed, setOnReady, setOnRunning, setOnScheduled, setOnSucceeded, start, stateProperty, titleProperty, totalWorkProperty, valueProperty, workDoneProperty
-
Property Details
-
delay
The initial delay between when the ScheduledService is first started, and when it will begin operation. This is the amount of time the ScheduledService will remain in the SCHEDULED state, before entering the RUNNING state, following a fresh invocation ofService.start()
orService.restart()
.- See Also:
-
period
The minimum amount of time to allow between the start of the last run and the start of the next run. The actual period (also known ascumulativePeriod
) will depend on this property as well as thebackoffStrategy
and number of failures.- See Also:
-
backoffStrategy
Computes the amount of time to add to the period on each failure. This cumulative amount is reset whenever the the ScheduledService is manually restarted.- See Also:
-
restartOnFailure
Indicates whether the ScheduledService should automatically restart in the case of a failure in the Task.- See Also:
-
maximumFailureCount
The maximum number of times the ScheduledService can fail before it simply ends in the FAILED state. You can of course restart the ScheduledService manually, which will cause the current count to be reset.- See Also:
-
currentFailureCount
The current number of times the ScheduledService has failed. This is reset whenever the ScheduledService is manually restarted.- See Also:
-
cumulativePeriod
The current cumulative period in use between iterations. This will be the same asperiod
, except after a failure, in which case the result of the backoffStrategy will be used as the cumulative period following each failure. This is reset whenever the ScheduledService is manually restarted or an iteration is successful. The cumulativePeriod is modified when the ScheduledService enters the scheduled state. The cumulativePeriod can be capped by setting themaximumCumulativePeriod
.- See Also:
-
maximumCumulativePeriod
The maximum allowed value for the cumulativePeriod. Setting this value will help ensure that in the case of repeated failures the back-off algorithm doesn't end up producing unreasonably large values for cumulative period. The cumulative period is guaranteed not to be any larger than this value. If the maximumCumulativePeriod is negative, then cumulativePeriod will be capped at 0. If maximumCumulativePeriod is NaN or null, then it will not influence the cumulativePeriod.- See Also:
-
lastValue
The last successfully computed value. During each iteration, the "value" of the ScheduledService will be reset to null, as with any other Service. The "lastValue" however will be set to the most recently successfully computed value, even across iterations. It is reset however whenever you manually call reset or restart.- See Also:
-
-
Field Details
-
EXPONENTIAL_BACKOFF_STRATEGY
A Callback implementation for thebackoffStrategy
property which will exponentially backoff the period between re-executions in the case of a failure. This computation takes the original period and the number of consecutive failures and computes the backoff amount from that information.If the
service
is null, then Duration.ZERO is returned. If the period is 0 then the result of this method will simply beMath.exp(currentFailureCount)
. In all other cases, the returned value is the same asperiod + (period * Math.exp(currentFailureCount))
. -
LOGARITHMIC_BACKOFF_STRATEGY
A Callback implementation for thebackoffStrategy
property which will logarithmically backoff the period between re-executions in the case of a failure. This computation takes the original period and the number of consecutive failures and computes the backoff amount from that information.If the
service
is null, then Duration.ZERO is returned. If the period is 0 then the result of this method will simply beMath.log1p(currentFailureCount)
. In all other cases, the returned value is the same asperiod + (period * Math.log1p(currentFailureCount))
. -
LINEAR_BACKOFF_STRATEGY
A Callback implementation for thebackoffStrategy
property which will linearly backoff the period between re-executions in the case of a failure. This computation takes the original period and the number of consecutive failures and computes the backoff amount from that information.If the
service
is null, then Duration.ZERO is returned. If the period is 0 then the result of this method will simply becurrentFailureCount
. In all other cases, the returned value is the same asperiod + (period * currentFailureCount)
.
-
-
Constructor Details
-
ScheduledService
public ScheduledService()Constructor for subclasses to call.
-
-
Method Details
-
getDelay
Gets the value of thedelay
property.- Property description:
- The initial delay between when the ScheduledService is first started, and when it will begin
operation. This is the amount of time the ScheduledService will remain in the SCHEDULED state,
before entering the RUNNING state, following a fresh invocation of
Service.start()
orService.restart()
. - Returns:
- the value of the
delay
property - See Also:
-
setDelay
Sets the value of thedelay
property.- Property description:
- The initial delay between when the ScheduledService is first started, and when it will begin
operation. This is the amount of time the ScheduledService will remain in the SCHEDULED state,
before entering the RUNNING state, following a fresh invocation of
Service.start()
orService.restart()
. - Parameters:
value
- the value for thedelay
property- See Also:
-
delayProperty
The initial delay between when the ScheduledService is first started, and when it will begin operation. This is the amount of time the ScheduledService will remain in the SCHEDULED state, before entering the RUNNING state, following a fresh invocation ofService.start()
orService.restart()
.- Returns:
- the
delay
property - See Also:
-
getPeriod
Gets the value of theperiod
property.- Property description:
- The minimum amount of time to allow between the start of the last run and the start of the next run.
The actual period (also known as
cumulativePeriod
) will depend on this property as well as thebackoffStrategy
and number of failures. - Returns:
- the value of the
period
property - See Also:
-
setPeriod
Sets the value of theperiod
property.- Property description:
- The minimum amount of time to allow between the start of the last run and the start of the next run.
The actual period (also known as
cumulativePeriod
) will depend on this property as well as thebackoffStrategy
and number of failures. - Parameters:
value
- the value for theperiod
property- See Also:
-
periodProperty
The minimum amount of time to allow between the start of the last run and the start of the next run. The actual period (also known ascumulativePeriod
) will depend on this property as well as thebackoffStrategy
and number of failures.- Returns:
- the
period
property - See Also:
-
getBackoffStrategy
Gets the value of thebackoffStrategy
property.- Property description:
- Computes the amount of time to add to the period on each failure. This cumulative amount is reset whenever the the ScheduledService is manually restarted.
- Returns:
- the value of the
backoffStrategy
property - See Also:
-
setBackoffStrategy
Sets the value of thebackoffStrategy
property.- Property description:
- Computes the amount of time to add to the period on each failure. This cumulative amount is reset whenever the the ScheduledService is manually restarted.
- Parameters:
value
- the value for thebackoffStrategy
property- See Also:
-
backoffStrategyProperty
Computes the amount of time to add to the period on each failure. This cumulative amount is reset whenever the the ScheduledService is manually restarted.- Returns:
- the
backoffStrategy
property - See Also:
-
getRestartOnFailure
public final boolean getRestartOnFailure()Gets the value of therestartOnFailure
property.- Property description:
- Indicates whether the ScheduledService should automatically restart in the case of a failure in the Task.
- Returns:
- the value of the
restartOnFailure
property - See Also:
-
setRestartOnFailure
public final void setRestartOnFailure(boolean value) Sets the value of therestartOnFailure
property.- Property description:
- Indicates whether the ScheduledService should automatically restart in the case of a failure in the Task.
- Parameters:
value
- the value for therestartOnFailure
property- See Also:
-
restartOnFailureProperty
Indicates whether the ScheduledService should automatically restart in the case of a failure in the Task.- Returns:
- the
restartOnFailure
property - See Also:
-
getMaximumFailureCount
public final int getMaximumFailureCount()Gets the value of themaximumFailureCount
property.- Property description:
- The maximum number of times the ScheduledService can fail before it simply ends in the FAILED state. You can of course restart the ScheduledService manually, which will cause the current count to be reset.
- Returns:
- the value of the
maximumFailureCount
property - See Also:
-
setMaximumFailureCount
public final void setMaximumFailureCount(int value) Sets the value of themaximumFailureCount
property.- Property description:
- The maximum number of times the ScheduledService can fail before it simply ends in the FAILED state. You can of course restart the ScheduledService manually, which will cause the current count to be reset.
- Parameters:
value
- the value for themaximumFailureCount
property- See Also:
-
maximumFailureCountProperty
The maximum number of times the ScheduledService can fail before it simply ends in the FAILED state. You can of course restart the ScheduledService manually, which will cause the current count to be reset.- Returns:
- the
maximumFailureCount
property - See Also:
-
getCurrentFailureCount
public final int getCurrentFailureCount()Gets the value of thecurrentFailureCount
property.- Property description:
- The current number of times the ScheduledService has failed. This is reset whenever the ScheduledService is manually restarted.
- Returns:
- the value of the
currentFailureCount
property - See Also:
-
currentFailureCountProperty
The current number of times the ScheduledService has failed. This is reset whenever the ScheduledService is manually restarted.- Returns:
- the
currentFailureCount
property - See Also:
-
getCumulativePeriod
Gets the value of thecumulativePeriod
property.- Property description:
- The current cumulative period in use between iterations. This will be the same as
period
, except after a failure, in which case the result of the backoffStrategy will be used as the cumulative period following each failure. This is reset whenever the ScheduledService is manually restarted or an iteration is successful. The cumulativePeriod is modified when the ScheduledService enters the scheduled state. The cumulativePeriod can be capped by setting themaximumCumulativePeriod
. - Returns:
- the value of the
cumulativePeriod
property - See Also:
-
cumulativePeriodProperty
The current cumulative period in use between iterations. This will be the same asperiod
, except after a failure, in which case the result of the backoffStrategy will be used as the cumulative period following each failure. This is reset whenever the ScheduledService is manually restarted or an iteration is successful. The cumulativePeriod is modified when the ScheduledService enters the scheduled state. The cumulativePeriod can be capped by setting themaximumCumulativePeriod
.- Returns:
- the
cumulativePeriod
property - See Also:
-
getMaximumCumulativePeriod
Gets the value of themaximumCumulativePeriod
property.- Property description:
- The maximum allowed value for the cumulativePeriod. Setting this value will help ensure that in the case of repeated failures the back-off algorithm doesn't end up producing unreasonably large values for cumulative period. The cumulative period is guaranteed not to be any larger than this value. If the maximumCumulativePeriod is negative, then cumulativePeriod will be capped at 0. If maximumCumulativePeriod is NaN or null, then it will not influence the cumulativePeriod.
- Returns:
- the value of the
maximumCumulativePeriod
property - See Also:
-
setMaximumCumulativePeriod
Sets the value of themaximumCumulativePeriod
property.- Property description:
- The maximum allowed value for the cumulativePeriod. Setting this value will help ensure that in the case of repeated failures the back-off algorithm doesn't end up producing unreasonably large values for cumulative period. The cumulative period is guaranteed not to be any larger than this value. If the maximumCumulativePeriod is negative, then cumulativePeriod will be capped at 0. If maximumCumulativePeriod is NaN or null, then it will not influence the cumulativePeriod.
- Parameters:
value
- the value for themaximumCumulativePeriod
property- See Also:
-
maximumCumulativePeriodProperty
The maximum allowed value for the cumulativePeriod. Setting this value will help ensure that in the case of repeated failures the back-off algorithm doesn't end up producing unreasonably large values for cumulative period. The cumulative period is guaranteed not to be any larger than this value. If the maximumCumulativePeriod is negative, then cumulativePeriod will be capped at 0. If maximumCumulativePeriod is NaN or null, then it will not influence the cumulativePeriod.- Returns:
- the
maximumCumulativePeriod
property - See Also:
-
getLastValue
Gets the value of thelastValue
property.- Property description:
- The last successfully computed value. During each iteration, the "value" of the ScheduledService will be reset to null, as with any other Service. The "lastValue" however will be set to the most recently successfully computed value, even across iterations. It is reset however whenever you manually call reset or restart.
- Returns:
- the value of the
lastValue
property - See Also:
-
lastValueProperty
The last successfully computed value. During each iteration, the "value" of the ScheduledService will be reset to null, as with any other Service. The "lastValue" however will be set to the most recently successfully computed value, even across iterations. It is reset however whenever you manually call reset or restart.- Returns:
- the
lastValue
property - See Also:
-
succeeded
protected void succeeded()A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the SUCCEEDED state. This method is invoked after the Service has been fully transitioned to the new state. Implementation Note: Subclasses which override this method must call this super implementation. -
failed
protected void failed()A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the FAILED state. This method is invoked after the Service has been fully transitioned to the new state. Implementation Note: Subclasses which override this method must call this super implementation. -
reset
public void reset()Resets the Service. May only be called while in one of the finish states, that is, SUCCEEDED, FAILED, or CANCELLED, or when READY. This method should only be called on the FX application thread. Implementation Note: Subclasses which override this method must call this super implementation. -
cancel
public boolean cancel()Cancels any currently running task and stops this scheduled service, such that no additional iterations will occur.
-