public class

Timer

extends Object
java.lang.Object
   ↳ java.util.Timer

Class Overview

Timers are used to schedule jobs for execution in a background process. A single thread is used for the scheduling and this thread has the option of being a daemon thread. By calling cancel you can terminate a Timer and its associated thread. All tasks which are scheduled to run after this point are cancelled. Tasks are executed sequentially but are subject to the delays from other tasks run methods. If a specific task takes an excessive amount of time to run it may impact the time at which subsequent tasks may run.

The TimerTask does not offer any guarantees about the real-time nature of scheduling tasks as its underlying implementation relies on the Object.wait(long) method.

Multiple threads can share a single Timer without the need for their own synchronization.

A Timer can be set to schedule tasks either at a fixed rate or with a fixed period. Fixed-period execution is the default.

The difference between fixed-rate and fixed-period execution is the following: With fixed-rate execution, the start time of each successive run of the task is scheduled in absolute terms without regard for when the previous task run actually took place. This can result in a series of bunched-up runs (one launched immediately after another) if busy resources or other system delays prevent the Timer from firing for an extended time. With fixed-period execution, each successive run of the task is scheduled relative to the start time of the previous run of the task, so two runs of the task are never fired closer together in time than the specified period.

See Also

Summary

Public Constructors
Timer(String name, boolean isDaemon)
Creates a new named Timer which may be specified to be run as a daemon thread.
Timer(String name)
Creates a new named Timer which does not run as a daemon thread.
Timer(boolean isDaemon)
Creates a new Timer which may be specified to be run as a daemon thread.
Timer()
Creates a new non-daemon Timer.
Public Methods
void cancel()
Cancels the Timer and removes any scheduled tasks.
int purge()
Removes all canceled tasks from the task queue.
void schedule(TimerTask task, Date when)
Schedule a task for single execution.
void schedule(TimerTask task, long delay, long period)
Schedule a task for repeated fixed-delay execution after a specific delay.
void schedule(TimerTask task, long delay)
Schedule a task for single execution after a specified delay.
void schedule(TimerTask task, Date when, long period)
Schedule a task for repeated fixed-delay execution after a specific time has been reached.
void scheduleAtFixedRate(TimerTask task, Date when, long period)
Schedule a task for repeated fixed-rate execution after a specific time has been reached.
void scheduleAtFixedRate(TimerTask task, long delay, long period)
Schedule a task for repeated fixed-rate execution after a specific delay has passed.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public Timer (String name, boolean isDaemon)

Since: API Level 1

Creates a new named Timer which may be specified to be run as a daemon thread.

Parameters
name the name of the Timer.
isDaemon true if Timer's thread should be a daemon thread.
Throws
NullPointerException is name is null

public Timer (String name)

Since: API Level 1

Creates a new named Timer which does not run as a daemon thread.

Parameters
name the name of the Timer.
Throws
NullPointerException is name is null

public Timer (boolean isDaemon)

Since: API Level 1

Creates a new Timer which may be specified to be run as a daemon thread.

Parameters
isDaemon true if the Timer's thread should be a daemon thread.

public Timer ()

Since: API Level 1

Creates a new non-daemon Timer.

Public Methods

public void cancel ()

Since: API Level 1

Cancels the Timer and removes any scheduled tasks. If there is a currently running task it is not affected. No more tasks may be scheduled on this Timer. Subsequent calls do nothing.

public int purge ()

Since: API Level 1

Removes all canceled tasks from the task queue. If there are no other references on the tasks, then after this call they are free to be garbage collected.

Returns
  • the number of canceled tasks that were removed from the task queue.

public void schedule (TimerTask task, Date when)

Since: API Level 1

Schedule a task for single execution. If when is less than the current time, it will be scheduled to be executed as soon as possible.

Parameters
task the task to schedule.
when time of execution.
Throws
IllegalArgumentException if when.getTime() < 0.
IllegalStateException if the Timer has been canceled, or if the task has been scheduled or canceled.

public void schedule (TimerTask task, long delay, long period)

Since: API Level 1

Schedule a task for repeated fixed-delay execution after a specific delay.

Parameters
task the task to schedule.
delay amount of time in milliseconds before first execution.
period amount of time in milliseconds between subsequent executions.
Throws
IllegalArgumentException if delay < 0 or period < 0.
IllegalStateException if the Timer has been canceled, or if the task has been scheduled or canceled.

public void schedule (TimerTask task, long delay)

Since: API Level 1

Schedule a task for single execution after a specified delay.

Parameters
task the task to schedule.
delay amount of time in milliseconds before execution.
Throws
IllegalArgumentException if delay < 0.
IllegalStateException if the Timer has been canceled, or if the task has been scheduled or canceled.

public void schedule (TimerTask task, Date when, long period)

Since: API Level 1

Schedule a task for repeated fixed-delay execution after a specific time has been reached.

Parameters
task the task to schedule.
when time of first execution.
period amount of time in milliseconds between subsequent executions.
Throws
IllegalArgumentException if when.getTime() < 0 or period < 0.
IllegalStateException if the Timer has been canceled, or if the task has been scheduled or canceled.

public void scheduleAtFixedRate (TimerTask task, Date when, long period)

Since: API Level 1

Schedule a task for repeated fixed-rate execution after a specific time has been reached.

Parameters
task the task to schedule.
when time of first execution.
period amount of time in milliseconds between subsequent executions.
Throws
IllegalArgumentException if when.getTime() < 0 or period < 0.
IllegalStateException if the Timer has been canceled, or if the task has been scheduled or canceled.

public void scheduleAtFixedRate (TimerTask task, long delay, long period)

Since: API Level 1

Schedule a task for repeated fixed-rate execution after a specific delay has passed.

Parameters
task the task to schedule.
delay amount of time in milliseconds before first execution.
period amount of time in milliseconds between subsequent executions.
Throws
IllegalArgumentException if delay < 0 or period < 0.
IllegalStateException if the Timer has been canceled, or if the task has been scheduled or canceled.