com.jalios.jdring
Class AlarmManager

java.lang.Object
  com.jalios.jdring.AlarmManager

public class AlarmManager
extends Object

This class implements an alarm manager similar to Unix cron and at daemons. It is intended to fire events when alarms' date and time match the current ones. Alarms are added dynamically and can be one-shot or repetitive (i.e. rescheduled when matched). Time unit is seconds. Alarms scheduled less than one second to the current time are rejected (a PastDateException is thrown).

The alarm scheduler has been designed to manage a large quantity of alarms (it uses a priority queue to optimize alarm dates selection) and to reduce the use of the CPU time (the AlarmManager's thread is started only when there are alarms to be managed and it sleeps until the next alarm date).

Note : because of clocks' skews some alarm dates may be erroneous, particularly if the next alarm date is scheduled for a remote time (e.g. more than a few days). In order to avoid that problem, well-connected machines can use the Network Time Protocol (NTP) to synchronize their clock.

Example of use:

  // Creates a new AlarmManager
  AlarmManager mgr = new AlarmManager();

  // Date alarm (non repetitive)
  mgr.addAlarm(new Date(System.currentTimeMillis() + 300000),
               new AlarmListener() {
    public void handleAlarm(AlarmEntry entry) {
      System.out.println("5 minutes later");
    }
  });
  
  Calendar cal = Calendar.getInstance();
  cal.add(Calendar.WEEK_OF_YEAR, 1);
  mgr.addAlarm(cal.getTime(), new AlarmListener() {
    public void handleAlarm(AlarmEntry entry) {
      System.out.println("One week later");
    }
  });

  // Alarm with a delay (in minute) relative to the current time.
  mgr.addAlarm(1, true, new AlarmListener() {
    public void handleAlarm(AlarmEntry entry) {
      System.out.println("1 more minute ! (" + new Date() + ")");
    }
  });

  // Cron-like alarm (minute, hour, day of month, month, day of week, year)
  // Repetitive when the year is not specified.
  
  mgr.addAlarm(-1, -1, -1, -1, -1, -1, new AlarmListener() {
    public void handleAlarm(AlarmEntry entry) {
      System.out.println("Every minute (" + new Date() + ")");
    }
  });

  mgr.addAlarm(5, -1, -1, -1, -1, -1, new AlarmListener() {
    public void handleAlarm(AlarmEntry entry) {
      System.out.println("Every hour at 5' (" + new Date() + ")");
    }
  });

  mgr.addAlarm(00, 12, -1, -1, -1, -1, new AlarmListener() {
    public void handleAlarm(AlarmEntry entry) {
      System.out.println("Lunch time (" + new Date() + ")");
    }
  });
  
  mgr.addAlarm(07, 14, 1, Calendar.JANUARY, -1, -1, new AlarmListener() {
    public void handleAlarm(AlarmEntry entry) {
      System.out.println("Happy birthday Lucas !");
    }
  });

  mgr.addAlarm(30, 9, 1, -1, -1, -1, new AlarmListener() {
    public void handleAlarm(AlarmEntry entry) {
      System.out.println("On the first of every month at 9:30");
    }
  });

  mgr.addAlarm(00, 18, -1, -1, Calendar.FRIDAY, -1, new AlarmListener() {
    public void handleAlarm(AlarmEntry entry) {
      System.out.println("On every Friday at 18:00");
    }
  });

  mgr.addAlarm(00, 13, 1, Calendar.AUGUST, -1, 2001,  new AlarmListener() {
    public void handleAlarm(AlarmEntry entry) {
      System.out.println("2 years that this class was programmed !");
    }
  });
 

Version:

$Revision: 27867 $

Author:

Olivier Dedieu, David Sims, Jim Lerner

Field Summary

protected boolean	isDaemon
protected SortedSet<AlarmEntry>	queue
static String	REVISION
protected String	threadName
protected AlarmWaiter	waiter

Constructor Summary

AlarmManager()
Creates a new AlarmManager.

AlarmManager(boolean isDaemon, String threadName)
Creates a new AlarmManager.

Method Summary

void	addAlarm(AlarmEntry entry) Adds an alarm for a specified AlarmEntry
AlarmEntry	addAlarm(Date date, AlarmListener listener) Adds an alarm for a specified date.
AlarmEntry	addAlarm(int delay, boolean isRepetitive, AlarmListener listener) Adds an alarm for a specified delay.
AlarmEntry	addAlarm(int minute, int hour, int dayOfMonth, int month, int dayOfWeek, int year, AlarmListener listener) Adds an alarm for a specified date.
boolean	containsAlarm(AlarmEntry alarmEntry) Tests whether the supplied AlarmEntry is in the manager.
void	executeNextAlarmNow() Do not wait for the next alarm and executes it right now.
void	executeNextAlarmNow(boolean executeInCurrentThread) Do not wait for the next alarm and executes it right now.
protected void	finalize() Stops the waiter thread before ending.
List<AlarmEntry>	getAllAlarms() Returns a copy of all alarms in the manager.
AlarmEntry	getNextAlarm() Returns the next alarm present in queue but don't remove it from queue
protected void	notifyListeners() This is method is called when an alarm date is reached.
boolean	removeAlarm(AlarmEntry entry) Removes the specified AlarmEntry.
void	removeAllAlarms() Removes all the alarms.
void	triggerAllAlarms() Trigger all the alarms now

Methods inherited from class java.lang.Object

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

Field Detail

REVISION

public static final String REVISION

See Also:

Constant Field Values

waiter

protected AlarmWaiter waiter

queue

protected SortedSet<AlarmEntry> queue

isDaemon

protected boolean isDaemon

threadName

protected String threadName

Constructor Detail

AlarmManager

public AlarmManager(boolean isDaemon,
                    String threadName)

Creates a new AlarmManager. The waiter thread will be started only when the first alarm listener will be added.

Parameters:

isDaemon - true if the waiter thread should run as a daemon.

threadName - the name of the waiter thread

AlarmManager

public AlarmManager()

Creates a new AlarmManager. The waiter thread will be started only when the first alarm listener will be added. The waiter thread will not run as a daemon.

Method Detail

addAlarm

public AlarmEntry addAlarm(Date date,
                           AlarmListener listener)
                    throws PastDateException

Adds an alarm for a specified date.

Parameters:

date - the alarm date to be added.

listener - the alarm listener.

Returns:

the AlarmEntry.

Throws:

PastDateException - if the alarm date is in the past or less than 1 second closed to the current date).

addAlarm

public AlarmEntry addAlarm(int delay,
                           boolean isRepetitive,
                           AlarmListener listener)
                    throws PastDateException

Adds an alarm for a specified delay.

Parameters:

delay - the alarm delay in minute (relative to now).

isRepetitive - true if the alarm must be reactivated, false otherwise.

listener - the alarm listener.

Returns:

the AlarmEntry.

Throws:

PastDateException - if the alarm date is in the past (or less than 1 second closed to the current date).

addAlarm

public AlarmEntry addAlarm(int minute,
                           int hour,
                           int dayOfMonth,
                           int month,
                           int dayOfWeek,
                           int year,
                           AlarmListener listener)
                    throws PastDateException

Adds an alarm for a specified date.

Parameters:

minute - minute of the alarm. Allowed values 0-59.

hour - hour of the alarm. Allowed values 0-23.

dayOfMonth - day of month of the alarm (-1 if every day). This attribute is exclusive with dayOfWeek. Allowed values 1-7 (1 = Sunday, 2 = Monday, ...). java.util.Calendar constants can be used.

month - month of the alarm (-1 if every month). Allowed values 0-11 (0 = January, 1 = February, ...). java.util.Calendar constants can be used.

dayOfWeek - day of week of the alarm (-1 if every day). This attribute is exclusive with dayOfMonth. Allowed values 1-31.

year - year of the alarm. When this field is not set (i.e. -1) the alarm is repetitive (i.e. it is rescheduled when reached).

listener - the alarm listener.

Returns:

the AlarmEntry.

Throws:

PastDateException - if the alarm date is in the past (or less than 1 second closed to the current date).

addAlarm

public void addAlarm(AlarmEntry entry)
              throws PastDateException

Adds an alarm for a specified AlarmEntry

Parameters:

entry - the AlarmEntry.

Throws:

PastDateException - if the alarm date is in the past (or less than one second too closed to the current date).

removeAlarm

public boolean removeAlarm(AlarmEntry entry)

Removes the specified AlarmEntry.

Parameters:

entry - the AlarmEntry that needs to be removed.

Returns:

true if there was an alarm for this date, false otherwise.

triggerAllAlarms

public void triggerAllAlarms()

Trigger all the alarms now

The alarm will be executed asynchronously in the dedicated AlarmWaiter thread as usual.

removeAllAlarms

public void removeAllAlarms()

Removes all the alarms. No more alarms, even newly added ones, will be fired.

containsAlarm

public boolean containsAlarm(AlarmEntry alarmEntry)

Tests whether the supplied AlarmEntry is in the manager.

Parameters:

alarmEntry - the alarmEntry

Returns:

boolean whether AlarmEntry is contained within the manager

getAllAlarms

public List<AlarmEntry> getAllAlarms()

Returns a copy of all alarms in the manager.

getNextAlarm

public AlarmEntry getNextAlarm()

Returns the next alarm present in queue but don't remove it from queue

Returns:

the next AlarmEntry or null if queue is empty

notifyListeners

protected void notifyListeners()

This is method is called when an alarm date is reached. It is only be called by the the AlarmWaiter or by itself (if the next alarm is in less than 1 second.)

executeNextAlarmNow

public void executeNextAlarmNow()

Do not wait for the next alarm and executes it right now. Warning : the alarm will be executed in the current thread (which is not what would have happend if the alarm had been triggered automatically).

executeNextAlarmNow

public void executeNextAlarmNow(boolean executeInCurrentThread)

Do not wait for the next alarm and executes it right now.

Parameters:

executeInCurrentThread - if set to true, the alarm will be executed in the current thread, if set to false, the alarm will be executed asynchronously in the dedicated AlarmWaiter thread as usual.

See Also:

executeNextAlarmNow(), triggerAllAlarms()

finalize

protected void finalize()

Stops the waiter thread before ending.

Overrides:

finalize in class Object