/*
* 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
* {@link Timer}.
*
*
A timer task is not reusable. Once a task has been scheduled
* for execution on a {@codeTimer} or cancelled, subsequent attempts to
* schedule it for execution will throw {@codeIllegalStateException}.
*
* @author Josh Bloch
* @since 1.3
*/
// 定时任务
public abstract class TimerTask implements Runnable {
/**
* 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.
*/
static final int SCHEDULED = 1; // 【排队】
/**
* 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).
*/
static final int CANCELLED = 3; // 【取消】
/**
* The state of this task, chosen from the constants below.
*/
int state = VIRGIN; // 任务状态
/**
* 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时间就被触发一次
* 负数:重复性任务:固定延时,任务下次的开始时间=任务上次结束时间+(-period)
*/
long period = 0;
/**
* This object is used to control access to the TimerTask internals.
*/
final Object lock = new Object();
/**
* Creates a new timer task.
*/
protected TimerTask() {
}
/**
* 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 {@coderun} 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.
*
* @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 {@codetrue} 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:
*
{@code
* 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.
*
* @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);
}
}
}