/*
* Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util;
A task that can be scheduled for one-time or repeated execution by a Timer. A timer task is not reusable. Once a task has been scheduled for execution on a Timer or cancelled, subsequent attempts to schedule it for execution will throw IllegalStateException.
Author: Josh Bloch Since: 1.3
/**
* A task that can be scheduled for one-time or repeated execution by a
* {@link Timer}.
*
* <p>A timer task is <em>not</em> reusable. Once a task has been scheduled
* for execution on a {@code Timer} or cancelled, subsequent attempts to
* schedule it for execution will throw {@code IllegalStateException}.
*
* @author Josh Bloch
* @since 1.3
*/
public abstract class TimerTask implements Runnable {
This object is used to control access to the TimerTask internals.
/**
* This object is used to control access to the TimerTask internals.
*/
final Object lock = new Object();
The state of this task, chosen from the constants below.
/**
* The state of this task, chosen from the constants below.
*/
int state = VIRGIN;
This task has not yet been scheduled.
/**
* This task has not yet been scheduled.
*/
static final int VIRGIN = 0;
This task is scheduled for execution. If it is a non-repeating task,
it has not yet been executed.
/**
* This task is scheduled for execution. If it is a non-repeating task,
* it has not yet been executed.
*/
static final int SCHEDULED = 1;
This non-repeating task has already executed (or is currently
executing) and has not been cancelled.
/**
* This non-repeating task has already executed (or is currently
* executing) and has not been cancelled.
*/
static final int EXECUTED = 2;
This task has been cancelled (with a call to TimerTask.cancel).
/**
* This task has been cancelled (with a call to TimerTask.cancel).
*/
static final int CANCELLED = 3;
Next execution time for this task in the format returned by
System.currentTimeMillis, assuming this task is scheduled for execution.
For repeating tasks, this field is updated prior to each task execution.
/**
* Next execution time for this task in the format returned by
* System.currentTimeMillis, assuming this task is scheduled for execution.
* For repeating tasks, this field is updated prior to each task execution.
*/
long nextExecutionTime;
Period in milliseconds for repeating tasks. A positive value indicates
fixed-rate execution. A negative value indicates fixed-delay execution.
A value of 0 indicates a non-repeating task.
/**
* Period in milliseconds for repeating tasks. A positive value indicates
* fixed-rate execution. A negative value indicates fixed-delay execution.
* A value of 0 indicates a non-repeating task.
*/
long period = 0;
Creates a new timer task.
/**
* Creates a new timer task.
*/
protected TimerTask() {
}
The action to be performed by this timer task.
/**
* The action to be performed by this timer task.
*/
public abstract void run();
Cancels this timer task. If the task has been scheduled for one-time
execution and has not yet run, or has not yet been scheduled, it will
never run. If the task has been scheduled for repeated execution, it
will never run again. (If the task is running when this call occurs,
the task will run to completion, but will never run again.)
Note that calling this method from within the run method of a repeating timer task absolutely guarantees that the timer task will not run again.
This method may be called repeatedly; the second and subsequent
calls have no effect.
Returns: true if this task is scheduled for one-time execution and has not yet run, or this task is scheduled for repeated execution. Returns false if the task was scheduled for one-time execution and has already run, or if the task was never scheduled, or if the task was already cancelled. (Loosely speaking, this method returns true if it prevents one or more scheduled executions from taking place.)
/**
* Cancels this timer task. If the task has been scheduled for one-time
* execution and has not yet run, or has not yet been scheduled, it will
* never run. If the task has been scheduled for repeated execution, it
* will never run again. (If the task is running when this call occurs,
* the task will run to completion, but will never run again.)
*
* <p>Note that calling this method from within the {@code run} method of
* a repeating timer task absolutely guarantees that the timer task will
* not run again.
*
* <p>This method may be called repeatedly; the second and subsequent
* calls have no effect.
*
* @return true if this task is scheduled for one-time execution and has
* not yet run, or this task is scheduled for repeated execution.
* Returns false if the task was scheduled for one-time execution
* and has already run, or if the task was never scheduled, or if
* the task was already cancelled. (Loosely speaking, this method
* returns {@code true} if it prevents one or more scheduled
* executions from taking place.)
*/
public boolean cancel() {
synchronized(lock) {
boolean result = (state == SCHEDULED);
state = CANCELLED;
return result;
}
}
Returns the scheduled execution time of the most recent
actual execution of this task. (If this method is invoked
while task execution is in progress, the return value is the scheduled
execution time of the ongoing task execution.)
This method is typically invoked from within a task's run method, to
determine whether the current execution of the task is sufficiently
timely to warrant performing the scheduled activity:
public void run() {
if (System.currentTimeMillis() - scheduledExecutionTime() >=
MAX_TARDINESS)
return; // Too late; skip this execution.
// Perform the task
}
This method is typically not used in conjunction with
fixed-delay execution repeating tasks, as their scheduled
execution times are allowed to drift over time, and so are not terribly
significant.
See Also: Returns: the time at which the most recent execution of this task was
scheduled to occur, in the format returned by Date.getTime().
The return value is undefined if the task has yet to commence
its first execution.
/**
* Returns the <i>scheduled</i> execution time of the most recent
* <i>actual</i> execution of this task. (If this method is invoked
* while task execution is in progress, the return value is the scheduled
* execution time of the ongoing task execution.)
*
* <p>This method is typically invoked from within a task's run method, to
* determine whether the current execution of the task is sufficiently
* timely to warrant performing the scheduled activity:
* <pre>{@code
* public void run() {
* if (System.currentTimeMillis() - scheduledExecutionTime() >=
* MAX_TARDINESS)
* return; // Too late; skip this execution.
* // Perform the task
* }
* }</pre>
* This method is typically <i>not</i> used in conjunction with
* <i>fixed-delay execution</i> repeating tasks, as their scheduled
* execution times are allowed to drift over time, and so are not terribly
* significant.
*
* @return the time at which the most recent execution of this task was
* scheduled to occur, in the format returned by Date.getTime().
* The return value is undefined if the task has yet to commence
* its first execution.
* @see Date#getTime()
*/
public long scheduledExecutionTime() {
synchronized(lock) {
return (period < 0 ? nextExecutionTime + period
: nextExecutionTime - period);
}
}
}