java.util: public class: Timer

java.util
public class: Timer [javadoc | source]

java.lang.Object
   java.util.Timer

{@code Timer}s 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 {@code cancel} you can terminate a {@code 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 {@code TimerTask} does not offer any guarantees about the real-time nature of scheduling tasks as its underlying implementation relies on the {@code Object.wait(long)} method.

Multiple threads can share a single {@code Timer} without the need for their own synchronization.

A {@code 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 {@code 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 {@code period}.

Also see:

TimerTask

java.lang.Object#wait(long)

Constructor:

Constructor:
public Timer() { this(false); } Creates a new non-daemon {@code Timer}.
public Timer(String name) { this(name, false); } Creates a new named {@code Timer} which does not run as a daemon thread. Parameters: `name` - the name of the Timer. Throws: `NullPointerException` - is {@code name} is {@code null}
public Timer(boolean isDaemon) { this("Timer-" + Timer.nextId(), isDaemon); } Creates a new {@code Timer} which may be specified to be run as a daemon thread. Parameters: `isDaemon` - {@code true} if the {@code Timer}'s thread should be a daemon thread.
public Timer(String name, boolean isDaemon) { super(); if (name == null){ throw new NullPointerException("name is null"); } this.impl = new TimerImpl(name, isDaemon); this.finalizer = new FinalizerHelper(impl); } Creates a new named {@code Timer} which may be specified to be run as a daemon thread. Parameters: `name` - the name of the {@code Timer}. `isDaemon` - true if {@code Timer}'s thread should be a daemon thread. Throws: `NullPointerException` - is {@code name} is {@code null}

 public Timer() {
        this(false);
}

Creates a new non-daemon {@code Timer}.

 public Timer(String name) {
        this(name, false);
}

Creates a new named {@code Timer} which does not run as a daemon thread.

Parameters:

name - the name of the Timer.

Throws:

NullPointerException - is {@code name} is {@code null}

 public Timer(boolean isDaemon) {
        this("Timer-" + Timer.nextId(), isDaemon);
}

Creates a new {@code Timer} which may be specified to be run as a daemon thread.

Parameters:

isDaemon - {@code true} if the {@code Timer}'s thread should be a daemon thread.

 public Timer(String name,
    boolean isDaemon) {
    	super();
    	if (name == null){
    		throw new NullPointerException("name is null");
    	}
        this.impl = new TimerImpl(name, isDaemon);
        this.finalizer = new FinalizerHelper(impl);
}

Creates a new named {@code Timer} which may be specified to be run as a daemon thread.

Parameters:

name - the name of the {@code Timer}.

isDaemon - true if {@code Timer}'s thread should be a daemon thread.

Throws:

NullPointerException - is {@code name} is {@code null}

Method from java.util.Timer Summary:
cancel, purge, schedule, schedule, schedule, schedule, scheduleAtFixedRate, scheduleAtFixedRate

Methods from java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from java.util.Timer Detail:
public void cancel() { impl.cancel(); } Cancels the {@code 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 {@code Timer}. Subsequent calls do nothing.
public int purge() { synchronized (impl) { return impl.purge(); } } 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.
public void schedule(TimerTask task, Date when) { if (when.getTime() < 0) { throw new IllegalArgumentException(); } long delay = when.getTime() - System.currentTimeMillis(); scheduleImpl(task, delay < 0 ? 0 : delay, -1, false); } Schedule a task for single execution. If {@code when} is less than the current time, it will be scheduled to be executed as soon as possible.
public void schedule(TimerTask task, long delay) { if (delay < 0) { throw new IllegalArgumentException(); } scheduleImpl(task, delay, -1, false); } Schedule a task for single execution after a specified delay.
public void schedule(TimerTask task, long delay, long period) { if (delay < 0 \|\| period < = 0) { throw new IllegalArgumentException(); } scheduleImpl(task, delay, period, false); } Schedule a task for repeated fixed-delay execution after a specific delay.
public void schedule(TimerTask task, Date when, long period) { if (period < = 0 \|\| when.getTime() < 0) { throw new IllegalArgumentException(); } long delay = when.getTime() - System.currentTimeMillis(); scheduleImpl(task, delay < 0 ? 0 : delay, period, false); } Schedule a task for repeated fixed-delay execution after a specific time has been reached.
public void scheduleAtFixedRate(TimerTask task, long delay, long period) { if (delay < 0 \|\| period < = 0) { throw new IllegalArgumentException(); } scheduleImpl(task, delay, period, true); } Schedule a task for repeated fixed-rate execution after a specific delay has passed.
public void scheduleAtFixedRate(TimerTask task, Date when, long period) { if (period < = 0 \|\| when.getTime() < 0) { throw new IllegalArgumentException(); } long delay = when.getTime() - System.currentTimeMillis(); scheduleImpl(task, delay, period, true); } Schedule a task for repeated fixed-rate execution after a specific time has been reached.

Method from java.util.Timer Detail:

 public  void cancel() {
        impl.cancel();
}

Cancels the {@code 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 {@code Timer}. Subsequent calls do nothing.

 public int purge() {
        synchronized (impl) {
            return impl.purge();
        }
}

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.

 public  void schedule(TimerTask task,
    Date when) {
        if (when.getTime() <  0) {
            throw new IllegalArgumentException();
        }
        long delay = when.getTime() - System.currentTimeMillis();
        scheduleImpl(task, delay <  0 ? 0 : delay, -1, false);
}

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

 public  void schedule(TimerTask task,
    long delay) {
        if (delay <  0) {
            throw new IllegalArgumentException();
        }
        scheduleImpl(task, delay, -1, false);
}

Schedule a task for single execution after a specified delay.

 public  void schedule(TimerTask task,
    long delay,
    long period) {
        if (delay <  0 || period < = 0) {
            throw new IllegalArgumentException();
        }
        scheduleImpl(task, delay, period, false);
}

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

 public  void schedule(TimerTask task,
    Date when,
    long period) {
        if (period < = 0 || when.getTime() <  0) {
            throw new IllegalArgumentException();
        }
        long delay = when.getTime() - System.currentTimeMillis();
        scheduleImpl(task, delay <  0 ? 0 : delay, period, false);
}

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

 public  void scheduleAtFixedRate(TimerTask task,
    long delay,
    long period) {
        if (delay <  0 || period < = 0) {
            throw new IllegalArgumentException();
        }
        scheduleImpl(task, delay, period, true);
}

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

 public  void scheduleAtFixedRate(TimerTask task,
    Date when,
    long period) {
        if (period < = 0 || when.getTime() <  0) {
            throw new IllegalArgumentException();
        }
        long delay = when.getTime() - System.currentTimeMillis();
        scheduleImpl(task, delay, period, true);
}

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