stella.util

Class Alarm

java.lang.Object

java.lang.Thread

stella.util.Alarm

All Implemented Interfaces:

Runnable

public class Alarm
extends Thread

A class with the functionality of an alarm clock. It is a self-starting thread that waits for specified time. If the alarm was not canceled with the cancel method during the waiting phase the setOff method of the registered alarm handlers are called. Note that all the alarm handlers must be available at the construction phase because of the self-starting nature of this thread.

In principle the functionality of the alarm can be constructed using the java Timer and TimerTask classes but the simplicity of this class may provide a very easy and convenient access.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Alarm.Test Test purpose only.

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field and Description
private double	accelerate System-wide acceleration.
protected AlarmHandler	alarmList The alarm handlers
private boolean	alarmOff Gets true if the alarm is canceled.
private static int	COUNT An internal counter for automatic naming.
private long	mintime The time-tag that must be reached.
private long	starttime The first time-tag that must be reached.
private long	sustime The time the Thread.suspend() method was called.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Alarm() Constructor chaining, do not use.
	Alarm(AlarmHandler ear, Date when) Constructs a new alarm with a default name and starts it automatically.
	Alarm(AlarmHandler ear, long timeout) Constructs a new alarm with a default name and starts it automatically.
	Alarm(ThreadGroup group, String name, AlarmHandler ear, Date when) Constructs a new alarm and starts it automatically.
	Alarm(ThreadGroup group, String name, AlarmHandler ear, long timeout) Constructs a new alarm and starts it automatically.

Method Summary

Modifier and Type	Method and Description
void	cancel() Cancels this alarm.
private static int	nextCount() Gets the next available number at automatic naming.
void	restartTimeout(long timeout) If this alarm has not yet set off, you can allocate a new timeout to it.
void	resumeAlarm() Resumes the alarm-clock ticking after a call to suspendAlarm().
void	run() The run method of the alarm.
protected void	setOffAlarm() This method sets off all registered alarm listeners by calling their setOff method.
void	suspendAlarm() Temporarily pauses the alarm clock.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

alarmList

protected AlarmHandler alarmList

The alarm handlers

alarmOff

private boolean alarmOff

Gets true if the alarm is canceled.

mintime

private long mintime

The time-tag that must be reached.

starttime

private long starttime

The first time-tag that must be reached. Set to mintime at construct.

accelerate

private double accelerate

System-wide acceleration.

sustime

private long sustime

The time the Thread.suspend() method was called.

COUNT

private static int COUNT

An internal counter for automatic naming.

Constructor Detail

Alarm

protected Alarm()

Constructor chaining, do not use.

Alarm

public Alarm(AlarmHandler ear,
             Date when)

Constructs a new alarm with a default name and starts it automatically. The handlers setOff method is called if the alarm is not set off before the wait time is over.

Parameters:

ear - The alarm handlers to notify.

when - The date when the alarm is set off.

Alarm

public Alarm(AlarmHandler ear,
             long timeout)

Constructs a new alarm with a default name and starts it automatically. The handlers setOff method is called if the alarm is not set off before the wait time is over.

Parameters:

ear - The alarm handlers to notify.

timeout - The time till alarm is set off, in ms.

Throws:

IllegalArgumentException - If timeout is negative.

Alarm

public Alarm(ThreadGroup group,
             String name,
             AlarmHandler ear,
             Date when)

Constructs a new alarm and starts it automatically. The handlers setOff method is called if the alarm is not set off before the wait time is over.

Parameters:

group - The thread group this alarm should run in.

name - The name for the alarm

ear - The alarm handlers to notify.

when - The date when the alarm is set off.

Alarm

public Alarm(ThreadGroup group,
             String name,
             AlarmHandler ear,
             long timeout)

Constructs a new alarm and starts it automatically. The listeners setOff method is called if the alarm is not set off before the wait time is over.

Parameters:

group - The thread group this alarm should run in.

name - The name for the alarm

ear - The alarm listeners to notify.

timeout - The time till alarm is set off, in ms.

Throws:

IllegalArgumentException - If timeout is negative.

Method Detail

nextCount

private static int nextCount()

Gets the next available number at automatic naming.

suspendAlarm

public final void suspendAlarm()

Temporarily pauses the alarm clock. The time-counting is resumed as the resumeAlarm() method is called.

resumeAlarm

public final void resumeAlarm()

Resumes the alarm-clock ticking after a call to suspendAlarm().

restartTimeout

public final void restartTimeout(long timeout)

If this alarm has not yet set off, you can allocate a new timeout to it. Alarm is restarted from now.

Parameters:

timeout -

run

public final void run()

The run method of the alarm. This method waits at maximum for the specified timeout stated in the construct section. If the alarm has not been canceled during this wait period the registered alarm listeners are set off. The normal way to cancel an alarm is by a call to the cancel() method but if this thread is interrupted the same effect should be obtained.

Specified by:

run in interface Runnable

Overrides:

run in class Thread

setOffAlarm

protected void setOffAlarm()

This method sets off all registered alarm listeners by calling their setOff method. The ordering in the alarm listener array specified in the construction phase of this alarm specifies the order in which this alarm listeners are set off.

cancel

public void cancel()

Cancels this alarm. This method sets the alarm off and guarantees that this task dies as soon as possible.