java.util
Class TimerTask

java.lang.Object
  extended byjava.util.TimerTask
All Implemented Interfaces:
Runnable

public abstract class TimerTask
extends Object
implements Runnable

A task that can be scheduled for one-time or repeated execution by a Timer.

Since:
1.3
Author:
Josh Bloch
See Also:
Timer

Field Summary
(package private) static int CANCELLED
          This task has been cancelled (with a call to TimerTask.cancel).
(package private) static int EXECUTED
          This non-repeating task has already executed (or is currently executing) and has not been cancelled.
(package private)  Object lock
          This object is used to control access to the TimerTask internals.
(package private)  long nextExecutionTime
          Next execution time for this task in the format returned by System.currentTimeMillis, assuming this task is schedule for execution.
(package private)  long period
          Period in milliseconds for repeating tasks.
(package private) static int SCHEDULED
          This task is scheduled for execution.
(package private)  int state
          The state of this task, chosen from the constants below.
(package private) static int VIRGIN
          This task has not yet been scheduled.
 
Constructor Summary
protected TimerTask()
          Creates a new timer task.
 
Method Summary
 boolean cancel()
          Cancels this timer task.
abstract  void run()
          The action to be performed by this timer task.
 long scheduledExecutionTime()
          Returns the scheduled execution time of the most recent actual execution of this task.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

lock

final Object lock
This object is used to control access to the TimerTask internals.


state

int state
The state of this task, chosen from the constants below.


VIRGIN

static final int VIRGIN
This task has not yet been scheduled.

See Also:
Constant Field Values

SCHEDULED

static final int SCHEDULED
This task is scheduled for execution. If it is a non-repeating task, it has not yet been executed.

See Also:
Constant Field Values

EXECUTED

static final int EXECUTED
This non-repeating task has already executed (or is currently executing) and has not been cancelled.

See Also:
Constant Field Values

CANCELLED

static final int CANCELLED
This task has been cancelled (with a call to TimerTask.cancel).

See Also:
Constant Field Values

nextExecutionTime

long nextExecutionTime
Next execution time for this task in the format returned by System.currentTimeMillis, assuming this task is schedule for execution. For repeating tasks, this field is updated prior to each task execution.


period

long period
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.

Constructor Detail

TimerTask

protected TimerTask()
Creates a new timer task.

Method Detail

run

public abstract void run()
The action to be performed by this timer task.

Specified by:
run in interface Runnable
See Also:
Thread.run()

cancel

public boolean cancel()
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.)

scheduledExecutionTime

public long scheduledExecutionTime()
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.

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.
See Also:
Date.getTime()