oracle.bali.share.thread
Class Timer

java.lang.Object
  |
  +--oracle.bali.share.thread.Timer

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

Periodic

public class Timer

extends java.lang.Object

implements java.lang.Runnable

A Timer is an object that will wait a user-defined length of time and then call a user-specified target. The delay is not guaranteed to be accurate; the delay may be greater than requested. However, the delay will never be less than requested. To implement drift-free timing, use the getMillisSinceExpired() method.

Timers may be rescheduled or cancelled at any time, but they are not destroyed until the kill() method is explicitly called.

Constructor Summary

Timer(java.lang.Runnable target)
Constructs a new timer for the specified target.

Timer(java.lang.Runnable target, long delay)
Constructs a new timer for the specified target, immediately scheduling it.

Timer(java.lang.Runnable target, java.lang.String name)
Constructs a new timer for the specified target, with a given name.

Method Summary

protected void	accurateSleep(long millis) Sleeps the current thread for the designated number of milliseconds; attempting to be more accurate than the built-in Thread.sleep() function.
void	cancel() Cancels a scheduled timer.
protected void	doRun() Actually runs the target.
protected void	finalize() Cleans up the timer.
protected java.lang.String	getDefaultName() Returns the default name for the timer.
long	getDelay() Returns the current delay, in milliseconds.
long	getMillisSinceExpired() Returns the milliseconds between when the current time and the actual time when the timer should have expired.
java.lang.String	getName() Gets the name of the timer.
int	getPriority() Gets and returns the priority of the timer.
boolean	isDaemon() Tests if this timer is a daemon timer.
boolean	isKilled()
boolean	isScheduled() Returns TRUE if the timer has been scheduled.
void	kill() Kills a timer.
void	run() Target function for timer thread.
void	schedule(long delay) Schedules a timer.
void	setDaemon(boolean on) Marks this timer as either a daemon timer or a user timer.
void	setDelay(long delay) Sets the current delay, in milliseconds.
void	setName(java.lang.String name) Sets the name of the timer.
void	setPriority(int newPriority) Sets the timer's priority.
protected boolean	wasCancelledDuringRun() Returns TRUE if cancel was called during the run.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Timer

public Timer(java.lang.Runnable target)

Constructs a new timer for the specified target.

Parameters:

target - the Runnable object

Timer

public Timer(java.lang.Runnable target,
             java.lang.String name)

Constructs a new timer for the specified target, with a given name.

Parameters:

target - the Runnable object

name - the new name for any threads used by the timer.

Timer

public Timer(java.lang.Runnable target,
             long delay)

Constructs a new timer for the specified target, immediately scheduling it.

Parameters:

target - the Runnable object

delay - the length of time in milliseconds to sleep

Method Detail

schedule

public void schedule(long delay)

Schedules a timer. The timer will call the target's "run" method after "delay" milliseconds. If the timer is already scheduled, reschedules the timer for the new delay.

Parameters:

delay - the length of time to sleep in milliseconds

See Also:

isScheduled(), getDelay()

isScheduled

public boolean isScheduled()

Returns TRUE if the timer has been scheduled.

See Also:

schedule(long), getDelay()

getDelay

public long getDelay()

Returns the current delay, in milliseconds. The delay is not reset by a call to cancel.

See Also:

schedule(long), isScheduled()

setDelay

public void setDelay(long delay)

Sets the current delay, in milliseconds. Does not cause the timer to be scheduled.

Parameters:

delay - the length of time to sleep in milliseconds

getMillisSinceExpired

public long getMillisSinceExpired()

Returns the milliseconds between when the current time and the actual time when the timer should have expired. If the timer hasn't yet expired, returns a negative number. Can be used to implement drift-free timing.

cancel

public void cancel()

Cancels a scheduled timer. Has no effect if the timer is already running the target's "run" method.

See Also:

schedule(long), kill(), wasCancelledDuringRun()

kill

public void kill()

Kills a timer. The timer continues to wait to be scheduled until this call is made. Calling kill() will not stop the timer's thread if it's running, so it is safe to call this method from within the supplied run() method. Timers cannot be reused after being killed().

See Also:

cancel()

isKilled

public boolean isKilled()

Returns:

true if the timer has been killed.

setName

public void setName(java.lang.String name)

Sets the name of the timer. This name is used by any threads used by the timer.

Parameters:

name - the new name for any threads used by the timer.

getName

public java.lang.String getName()

Gets the name of the timer.

setDaemon

public void setDaemon(boolean on)

Marks this timer as either a daemon timer or a user timer.

This method must be called before the timer has ever been scheduled, or an IllegalThreadStateException will be thrown.

Parameters:

on - if true, marks this timer as a daemon timer

Throws:

IllegalThreadStateException - if this timer has been scheduled.

isDaemon

public boolean isDaemon()

Tests if this timer is a daemon timer.

setPriority

public void setPriority(int newPriority)

Sets the timer's priority. This should not significantly affect the accuracy of the timer, but will affect the priority of the code executed in the target.

Parameters:

newPriority - timer's new priority

getPriority

public int getPriority()

Gets and returns the priority of the timer.

run

public void run()

Target function for timer thread. Clients should not call this function directly or override it.

Specified by:

run in interface java.lang.Runnable

See Also:

schedule(long), doRun()

accurateSleep

protected void accurateSleep(long millis)
                      throws java.lang.InterruptedException

Sleeps the current thread for the designated number of milliseconds; attempting to be more accurate than the built-in Thread.sleep() function. Override this if extremely accurate timing is needed (and you know how to implement it!)

Parameters:

millis - the number of milliseconds to sleep.

Throws:

java.lang.InterruptedException - Another thread has interrupted this thread.

See Also:

Thread.sleep(long)

doRun

protected void doRun()

Actually runs the target. Subclasses may override this method to customize behavior (e.g., automatically rescheduling after running), but should always call super.doRun() to call through to the target.

wasCancelledDuringRun

protected boolean wasCancelledDuringRun()

Returns TRUE if cancel was called during the run. Subclasses should not re-schedule themselves if they were cancelled during the run.

getDefaultName

protected java.lang.String getDefaultName()

Returns the default name for the timer.

finalize

protected void finalize()
                 throws java.lang.Throwable

Cleans up the timer.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - Any exception thrown by a finalize method causes finalization to halt; otherwise, it is ignored.