com.sas.util
Class Alarm

com.sas.util.Alarm

All Implemented Interfaces:

com.sas.beans.PropertyChangeSource, com.sas.beans.VetoableChangeSource, com.sas.ComponentInterface, com.sas.LinkPropertiesInterface, com.sas.ModelInterface, AlarmInterface, AlarmSource, com.sas.util.TimeIntervals, TimerInterface, com.sas.ViewInterface, MultipleValueEventSourceInterface, java.beans.PropertyChangeListener, java.io.ObjectInputValidation, java.io.Serializable, java.util.EventListener

public class Alarm
implements AlarmInterface

A timed alarm which fires events at regular intervals.

This object allows you to set an alarm at a specified time in the future. When the time expires, the alarm will send an AlarmEvent to all AlarmListeners. The alarm can auto-repeat indefinitely or a fixed number of times.

For example, an Alarm object may be used in a document editor to support an autosave operation. An alarm can be created to fire at five minute intervals (5 * Alarm.ONE_MINUTE) and the alarm listener can be an object which performs the autosave if the document has been modified since the last autosave.

Although Alarms have a run() method, they do not implement java.lang.Runnable since the Alarm implementation is expected to provide the alarm thread.

All time units are measured in milliseconds.

If an alarm is serialized, it saves its properties and when it is deserialized, the alarm will automatically start itself if it was running when serialized, and if the current time is still less than the stop time. However, the alarm does not store its AlarmEvent listeners when serialized, so you must call addAlarmListener after deserializing an alarm from a serial stream.

If an alarm is created in a design time environment (such as in an IDE), the count property is not decremented when the alarm fires. This preserves the count property for use at run time, when the Alarm is deserialized in a running application.

For example, if you wish to create an Alarm which fires events for a listener at 24:00 intervals, starting at midnight, you can use the following:

 Alarm alarm = new Alarm(listener,
                         com.sas.util.CurrentDate.millisUntilMidnight(null),
                         Alarm.ONE_DAY,
                         (int) 0);
 

Other unit time intervals are available from TimerInterface, which Alarm implements by way of AlarmInterface.

Properties (properties defined in TimerInterface)

• startTime
• stopTime
• running
• duration
• interval
• delay
• count

See Also:

Serialized Form

Nested Class Summary

protected class

Alarm.AlarmThread

Field Summary

protected Alarm.AlarmThread	alarmThread A separate thread used to implement the alarm timeout.
protected int	count Number of times to auto-repeat before stopping.
protected long	delay How long to actually delay before triggering this alarm each time it is started.
protected long	internalDelay How long until the next alarm will fire.
protected long	interval Duration of the auto-repeat interval, in milliseconds.
protected long	startTime Time alarm was last started
protected long	stopTime Time alarm was last stopped
protected long	timeLastFired Keep track of the time this alarm last fired, in milliseconds since the Epoch.

Fields inherited from interface com.sas.util.TimeIntervals

ONE_DAY, ONE_HOUR, ONE_MINUTE, ONE_SECOND, ONE_WEEK

Constructor Summary

Alarm()
Default no-arg constructor.

Alarm(AlarmListener listener, java.util.Calendar startDateTime, java.util.Calendar stopDateTime, long intervalMillis)
Construct and start an alarm which will fire at the time specified by the start date/time, and recur at the specified interval until the stop date/time.

Alarm(AlarmListener listener, java.util.Calendar startDateTime, long intervalMillis, int count)
Construct an alarm which will fire at the time specified by the java.util.Calendar and recur at the specified interval.

Alarm(AlarmListener listener, long millisecondDelay, long intervalMillis, int count)
Create and start an alarm which begins firing AlarmEvents millisecondDelay milliseconds from now, repeating every intervalMillis milliseconds, until it has fired count times (or indefinitely if count is 0).

Alarm(AlarmListener listener, long startTimeMillis, long stopTimeMillis, long intervalMillis)
Construct and start an alarm which will fire at the time specified by the startTimeMillis, and recur at the specified interval until the stopTimeMillis.

Method Summary

void	addAlarmListener(AlarmListener listener) Add a listener for the AlarmEvent event.
protected int	decrementCount() Decrement the count, but only at run time, not at design time.
protected void	fireAlarm(AlarmEvent event) Send an alarm event to all listeners.
int	getCount() Get the number of times this alarm will fire before stopping.
long	getDelay() Get the amount of time this alarm will wait before firing following a start().
long	getDuration() Return the number of milliseconds this alarm has been running.
static com.sas.beans.ExtendedBeanInfo	getExtendedBeanInfo()
long	getInterval() Return this alarm's interval, which measures the time interval at which this alarm repeats.
long	getStartTime() Retrieve the start time
long	getStopTime() Retrieve the stop time
protected void	init(AlarmListener listener, long millisecondDelay, long intervalMillis, int alarmCount)
boolean	isRunning() Test if an alarm is running.
protected void	onStop() Respond to a stop.
void	removeAlarmListener(AlarmListener listener) Remove a listener for the AlarmEvent event.
protected void	reset() Reset this alarm.
protected void	resetCount() Reset the count based on a start/stop interval.
void	setCount(int alarmCount) Set the number of times this alarm will fire.
void	setDelay(long millisecondDelay) Set the initial amount of time this alarm will wait before first firing when started.
void	setInterval(long intervalMillis) Set the interval at which this alarm fires.
void	setRunning(boolean running) Set the state of this alarm to be running or stopped.
void	setStartTime(long startTimeMillis) Set this alarm's start time, the time when this alarm will begin firing alarm events.
void	setStopTime(long stopTimeMillis) Set the timer's stop time.
void	start() Start this alarm.
void	stop() Stop this alarm if it is running.
java.lang.String	toString() Return a string representation of the alarm.
protected void	triggerAlarm() Trigger this alarm.

Field Detail

interval

protected long interval

Duration of the auto-repeat interval, in milliseconds. If this is 0, then this alarm will not auto-repeat.

timeLastFired

protected long timeLastFired

Keep track of the time this alarm last fired, in milliseconds since the Epoch. The first alarm is scheduled to fire at currenttime + delay; subsequent alarms are scheduled to fire as close to timeLastFired + interval as possible.

delay

protected long delay

How long to actually delay before triggering this alarm each time it is started.

internalDelay

protected transient long internalDelay

How long until the next alarm will fire.

startTime

protected long startTime

Time alarm was last started

stopTime

protected long stopTime

Time alarm was last stopped

count

protected int count

Number of times to auto-repeat before stopping.

alarmThread

protected transient Alarm.AlarmThread alarmThread

A separate thread used to implement the alarm timeout.

Constructor Detail

Alarm

public Alarm()

Default no-arg constructor. The alarm is not started.

Alarm

public Alarm(AlarmListener listener,
             long millisecondDelay,
             long intervalMillis,
             int count)

Create and start an alarm which begins firing AlarmEvents millisecondDelay milliseconds from now, repeating every intervalMillis milliseconds, until it has fired count times (or indefinitely if count is 0).

Note that this constructor is unfortunately very similar to new Alarm(AlarmListener listener, long startTimeMillis, long stopTimeMillis, long intervalMillis) and differs only in the type of the last argument, so be careful to use the right constructor.

Parameters:

listener - an initial listener for the AlarmEvent. More may be added later, but the Alarm may fire between Alarm construction and later calls to addAlarmListener. This listener is added to the listener list immediately, before the alarm is scheduled.

millisecondDelay - the amount of time to delay before firing the alarm after a start(). This can differ from interval. For example, if you want an alarm to fire at a fixed time each day starting at some day in the future, millisecondDelay will be the number of milliseconds until that time, and intervalMillis will be 24 hours (Alarm.ONE_DAY, or 24 * 60 * 60 * 1000).

intervalMillis - if greater than 0, then automatically reschedule the alarm this many time units after it goes off.

count - the number of times the alarm will fire before stopping automatically. This is only honored if intervalMillis is non-zero. If count is 0, the alarm will recur indefinitely. Otherwise, count is decremented each time the alarm fires. If you restart an expired alarm, you must reset the count if you want a limited number of alarm events. Note: count does not decrement if this alarm is created in a design time environment.

Alarm

public Alarm(AlarmListener listener,
             long startTimeMillis,
             long stopTimeMillis,
             long intervalMillis)

Construct and start an alarm which will fire at the time specified by the startTimeMillis, and recur at the specified interval until the stopTimeMillis.

Note that this constructor is unfortunately very similar to new Alarm(AlarmListener listener, long millisecondDelay, long intervalMillis, int count) and differs only in the type of the last argument, so be careful to use the right constructor.

Parameters:

listener - an initial listener for the AlarmEvent. More may be added later, but the alarm may fire between alarm construction and later calls to addAlarmListener. This listener is added to the listener list immediately, before the alarm is scheduled.

startTimeMillis - the time, in milliseconds since the Epoch, when the alarm should start. Use 0 to start immediately, or System.currentTimeMillis() + millisecondDelay to start at a specific delay.

stopTimeMillis - the time, in milliseconds since the Epoch, when the alarm should stop. The alarm will try fire at intervals up to and including the stop time, but the alarm will not fire after stopTimeMillis + intervalMillis/2. If stopTimeMillis == 0 and intervalMillis is non-zero, the alarm repeats indefinitely.

intervalMillis - if greater than 0, then automatically reschedule the alarm this many time units after it goes off, until the stop time has passed.

Alarm

public Alarm(AlarmListener listener,
             java.util.Calendar startDateTime,
             long intervalMillis,
             int count)

Construct an alarm which will fire at the time specified by the java.util.Calendar and recur at the specified interval.

Note that this constructor is unfortunately very similar to new Alarm(AlarmListener listener, Calendar startDateTime, Calendar stopDateTime, long intervalMillis) and differs only in the type of the last argument, so be careful to use the right constructor.

Parameters:

listener - an initial listener for the AlarmEvent. More may be added later, but the alarm may fire between alarm construction and later calls to addAlarmListener. This listener is added to the listener list immediately, before the alarm is scheduled.

startDateTime - the java.util.Calendartime when the alarm should start. Use null to start immediately.

intervalMillis - if greater than 0, then automatically reschedule the alarm this many time units after it goes off.

count - the number of times the alarm will fire before stopping automatically. This is only honored if intervalMillis is non-zero. If count is 0, the alarm will recur indefinitely. Otherwise, count is decremented each time the alarm fires. If you restart an expired alarm, you must reset the count if you want a limited number of alarm events. Note: count does not decrement if this alarm is created in a design time environment.

Alarm

public Alarm(AlarmListener listener,
             java.util.Calendar startDateTime,
             java.util.Calendar stopDateTime,
             long intervalMillis)

Construct and start an alarm which will fire at the time specified by the start date/time, and recur at the specified interval until the stop date/time.

Note that this constructor is unfortunately very similar to new Alarm(AlarmListener listener, Calendar startDateTime, long intervalMillis, int count) and differs only in the type of the last argument, so be careful to use the right constructor.

Parameters:

listener - an initial listener for the AlarmEvent. More may be added later, but the alarm may fire between alarm construction and later calls to addAlarmListener. This listener is added to the listener list immediately, before the alarm is scheduled.

startDateTime - the java.util.Calendartime when the alarm should start. Use null to start immediately.

stopDateTime - The time at which the alarm should stop. The alarm will try fire at intervals up to and including the stop time, but the alarm will not fire after stop time + intervalMillis/2. If stopDateTime is null and intervalMillis is non-zero, the alarm repeats indefinitely.

intervalMillis - if greater than 0, then automatically reschedule the alarm this many time units after it goes off, until the stop Time has passed.

Method Detail

getExtendedBeanInfo

public static com.sas.beans.ExtendedBeanInfo getExtendedBeanInfo()

init

protected void init(AlarmListener listener,
                    long millisecondDelay,
                    long intervalMillis,
                    int alarmCount)

resetCount

protected void resetCount()

Reset the count based on a start/stop interval. Call this after changing the start/stop time. For example, setting an alarm at 30 second intervals, with a start time of T and a stop time of T + 2 minutes, we'll set count to 5 (T, T+0:30, T+1:00, T+1:30, T+2:00)

See Also:

getCount()

getStartTime

public long getStartTime()

Retrieve the start time

Specified by:

getStartTime in interface TimerInterface

Returns:

the time this alarm was last started, in number of milliseconds since the Epoch, or the time this alarm is scheduled to start.

See Also:

stop(), start()

setStartTime

public void setStartTime(long startTimeMillis)

Set this alarm's start time, the time when this alarm will begin firing alarm events. This method does not start this alarm, however. This sets the initial delay based on the specified startTimeMillis. This does nothing if this alarm is already running or if startTimeMillis has already passed. Note that to convert a java.util.Calendar to milliseconds, you can use Util.toMillis(java.util.Calendar)

Specified by:

setStartTime in interface AlarmInterface

Parameters:

startTimeMillis - the time the timer should start, in number of milliseconds since the Epoch

See Also:

start()

getStopTime

public long getStopTime()

Retrieve the stop time

Specified by:

getStopTime in interface TimerInterface

Returns:

the time this alarm was last stopped, in number of milliseconds since the Epoch, or the time this alarm is scheduled to stop.

See Also:

stop(), start()

setStopTime

public void setStopTime(long stopTimeMillis)

Set the timer's stop time. This will stop a running alarm if the stopTimeMillis has already passed. This alarm will try fire at intervals up to and including the stop time, but this alarm will not fire after stopTimeMillis + interval/2. Due to small interval timing inconsistencies and hardware and operating system dependencies, this alarm is not guaranteed fire at or near the specified stop time. For example, setting an alarm at 30 second intervals, with a start time of T and a stop time of T + 2 minutes, an attempt is made to fire this alarm at (T, T+0:30, T+1:00, T+1:30, T+2:00) But if the interval is 50 ms, and this alarm is scheduled to fire at startTime T and stop time of T+100ms, it may fire only at ~T and ~T+50ms.

The count is reset to the number of intervals between the start time and stop time (if not running) or the number of remaining intervals between the current time and the stop time.

Specified by:

setStopTime in interface AlarmInterface

Parameters:

stopTimeMillis - the time the timer should stop, in number of milliseconds since the Epoch. If stopTimeMillis and count are 0 and interval is greater than zero, the timer will repeat indefinitely.

See Also:

stop(), start()

isRunning

public boolean isRunning()

Test if an alarm is running.

Specified by:

isRunning in interface TimerInterface

Returns:

true if stop() has not been called since start() was last called and this alarm has not reached it set stop time. false otherwise.

See Also:

stop(), start()

setRunning

public final void setRunning(boolean running)

Set the state of this alarm to be running or stopped.

Specified by:

setRunning in interface TimerInterface

Parameters:

running - the new running state. If this is the same as the current state, nothing happens. Otherwise, if true, then call start(), else call stop(). This method is an alias for calling start() and stop(), and is therefore final. If you extend the Alarm class, you should override those methods to change behavior.

See Also:

stop(), start()

getDuration

public long getDuration()

Return the number of milliseconds this alarm has been running. If this alarm has been stopped, this is the difference bewteen the stop time and the start time. If this alarm has not been stopped, this is the difference bewteen the current time and the start time.

Specified by:

getDuration in interface TimerInterface

Returns:

the number of milliseconds this alarm has been running. If this alarm has never been started, return 0.

getInterval

public long getInterval()

Return this alarm's interval, which measures the time interval at which this alarm repeats.

Specified by:

getInterval in interface AlarmInterface

Returns:

this alarm's interval. This alarm fires approximately every interval milliseconds.

See Also:

setInterval(long)

setInterval

public void setInterval(long intervalMillis)

Set the interval at which this alarm fires. If the new interval is shorter than the current interval, and this alarm is running, this alarm may fire sooner than previously scheduled. This is necessary, for instance, if you change the interval form ONE_HOUR to ONE_SECOND; you don't want to have to wait up to an hour for the new interval to take effect. If the new interval is larger than the current interval and this alarm is running, this alarm will still fire as previously scheduled, then assume the new interval.

Specified by:

setInterval in interface AlarmInterface

Parameters:

intervalMillis - the new alarm interval, in milliseconds. Setting the interval to 0 or a negative integer has the effect of stopping the alarm.

See Also:

getInterval(), stop(), start()

setDelay

public void setDelay(long millisecondDelay)

Set the initial amount of time this alarm will wait before first firing when started. Note that to compute the delay between the current time and a specific java.util.Calendar, you can use Util.millisUntil(java.util.Calendar)

Specified by:

setDelay in interface AlarmInterface

Parameters:

millisecondDelay - this alarm delay, in milliseconds.

setCount

public void setCount(int alarmCount)

Set the number of times this alarm will fire. The count is decremented each time the alarm fires. Note that if there is a stop time has been set, this alarm will stop if it reaches that stop time before the count reaches zero.

Specified by:

setCount in interface AlarmInterface

Parameters:

alarmCount - the number of times this alarm will fire. alarmCount is valid only if the interval is non-zero.

getCount

public int getCount()

Get the number of times this alarm will fire before stopping.

Specified by:

getCount in interface AlarmInterface

Returns:

this alarm's count

getDelay

public long getDelay()

Get the amount of time this alarm will wait before firing following a start(). This delay is not reset to 0 after a stop().

Specified by:

getDelay in interface AlarmInterface

Returns:

this alarm's delay, in milliseconds.

start

public void start()

Start this alarm. If this alarm is already running, this resets the start time.

Specified by:

start in interface TimerInterface

See Also:

stop(), setRunning(boolean)

stop

public void stop()

Stop this alarm if it is running.

Specified by:

stop in interface TimerInterface

See Also:

start(), setRunning(boolean)

onStop

protected void onStop()

Respond to a stop. This method runs after the alarm has stopped. It fires property change events for the "running" and "stopTime" properties.

addAlarmListener

public void addAlarmListener(AlarmListener listener)

Add a listener for the AlarmEvent event.

Specified by:

addAlarmListener in interface AlarmInterface

Specified by:

addAlarmListener in interface AlarmSource

Parameters:

listener - an object which handles AlarmEvent events the listener is not added a second time if it already exists in the list of listeners for this event.

See Also:

AlarmSource

removeAlarmListener

public void removeAlarmListener(AlarmListener listener)

Remove a listener for the AlarmEvent event. Nothing happens if the listener is not in the list of listeners for this event.

Specified by:

removeAlarmListener in interface AlarmInterface

Specified by:

removeAlarmListener in interface AlarmSource

Parameters:

listener - an object which handles AlarmEvent events

See Also:

AlarmSource

reset

protected void reset()

Reset this alarm. This stores the current time in timeLastFired, the variable which record the time the alarm was last fired.

fireAlarm

protected void fireAlarm(AlarmEvent event)

Send an alarm event to all listeners.

Parameters:

event - an AlarmEvent to send to the listeners.

decrementCount

protected int decrementCount()

Decrement the count, but only at run time, not at design time.

Returns:

the new alarm count value.

triggerAlarm

protected void triggerAlarm()

Trigger this alarm. If this alarm is enabled, fire the AlarmEvent and then reschedule this alarm if it is recurring.

toString

public java.lang.String toString()

Return a string representation of the alarm.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the alarm.