Package com.jalios.jdring

Class AlarmManager

  • public class AlarmManager
extends java.lang.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: 102713 $
    Author:
    Olivier Dedieu, David Sims, Jim Lerner

    • Field Detail

      • queue

        protected java.util.SortedSet<AlarmEntry> queue

      • isDaemon

        protected boolean isDaemon

      • threadName

        protected java.lang.String threadName

    • Constructor Detail

      • AlarmManager

        public AlarmManager​(boolean isDaemon,
                    java.lang.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​(java.util.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 java.util.List<AlarmEntry> getAllAlarms()
        Returns a copy of all alarms in the manager.
        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 java.lang.Object