FileDocCategorySizeDatePackage
Timer.javaAPI DocJava SE 6 API47713Tue Jun 10 00:26:20 BST 2008javax.management.timer

Timer

public class Timer extends NotificationBroadcasterSupport implements TimerMBean, MBeanRegistration
Provides the implementation of the timer MBean. The timer MBean sends out an alarm at a specified time that wakes up all the listeners registered to receive timer notifications.

This class manages a list of dated timer notifications. A method allows users to add/remove as many notifications as required. When a timer notification is emitted by the timer and becomes obsolete, it is automatically removed from the list of timer notifications.
Additional timer notifications can be added into regularly repeating notifications.

Note:

  1. When sending timer notifications, the timer updates the notification sequence number irrespective of the notification type.
  2. The timer service relies on the system date of the host where the Timer class is loaded. Listeners may receive untimely notifications if their host has a different system date. To avoid such problems, synchronize the system date of all host machines where timing is needed.
  3. The default behavior for periodic notifications is fixed-delay execution, as specified in {@link java.util.Timer}. In order to use fixed-rate execution, use the overloaded {@link #addNotification(String, String, Object, Date, long, long, boolean)} method.
  4. Notification listeners are potentially all executed in the same thread. Therefore, they should execute rapidly to avoid holding up other listeners or perturbing the regularity of fixed-delay executions. See {@link NotificationBroadcasterSupport}.
version
4.63 12/29/05
author
Sun Microsystems, Inc
since
1.5

Fields Summary
public static final long
ONE_SECOND
Number of milliseconds in one second. Useful constant for the addNotification method.
public static final long
ONE_MINUTE
Number of milliseconds in one minute. Useful constant for the addNotification method.
public static final long
ONE_HOUR
Number of milliseconds in one hour. Useful constant for the addNotification method.
public static final long
ONE_DAY
Number of milliseconds in one day. Useful constant for the addNotification method.
public static final long
ONE_WEEK
Number of milliseconds in one week. Useful constant for the addNotification method.
private static final String
dbgTag
private Map
timerTable
Table containing all the timer notifications of this timer, with the associated date, period and number of occurrences.
private boolean
sendPastNotifications
Past notifications sending on/off flag value. This attribute is used to specify if the timer has to send past notifications after start.
The default value is set to false.
private transient boolean
isActive
Timer state. The default value is set to false.
private transient long
sequenceNumber
Timer sequence number. The default value is set to 0.
private static final int
TIMER_NOTIF_INDEX
private static final int
TIMER_DATE_INDEX
private static final int
TIMER_PERIOD_INDEX
private static final int
TIMER_NB_OCCUR_INDEX
private static final int
ALARM_CLOCK_INDEX
private static final int
FIXED_RATE_INDEX
private int
counterID
The notification counter ID. Used to keep the max key value inserted into the timer table.
private Timer
timer
Constructors Summary
public Timer()
Default constructor.


    /*
     * ------------------------------------------
     *  CONSTRUCTORS
     * ------------------------------------------
     */
Methods Summary
public synchronized java.lang.IntegeraddNotification(java.lang.String type, java.lang.String message, java.lang.Object userData, java.util.Date date, long period, long nbOccurences, boolean fixedRate)
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurrences.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date.
For once-off notifications, the notification is delivered immediately.
For periodic notifications, the first notification is delivered immediately and the subsequent ones are spaced as specified by the period parameter.

Note that once the timer notification has been added into the list of notifications, its associated date, period and number of occurrences cannot be updated.

In the case of a periodic notification, the value of parameter fixedRate is used to specify the execution scheme, as specified in {@link java.util.Timer}.

param
type The timer notification type.
param
message The timer notification detailed message.
param
userData The timer notification user data object.
param
date The date when the notification occurs.
param
period The period of the timer notification (in milliseconds).
param
nbOccurences The total number the timer notification will be emitted.
param
fixedRate If true and if the notification is periodic, the notification is scheduled with a fixed-rate execution scheme. If false and if the notification is periodic, the notification is scheduled with a fixed-delay execution scheme. Ignored if the notification is not periodic.
return
The identifier of the new created timer notification.
exception
java.lang.IllegalArgumentException The date is {@code null} or the period or the number of occurrences is negative.
see
#addNotification(String, String, Object, Date, long, long)


        if (date == null) {
            throw new java.lang.IllegalArgumentException("Timer notification date cannot be null.");
        }

        // Check that all the timer notification attributes are valid.
        //

        // Invalid timer period value exception:
        // Check that the period and the nbOccurences are POSITIVE VALUES.
        //
        if ((period < 0) || (nbOccurences < 0)) {
            throw new java.lang.IllegalArgumentException("Negative values for the periodicity");
        }

        Date currentDate = new Date();

        // Update the date if it is before the current date.
        //
        if (currentDate.after(date)) {

          date.setTime(currentDate.getTime());
          if (isTraceOn()) {
            trace("addNotification", "update timer notification to add with:" +
                  "\n\tNotification date = " + date);
          }
        }

        // Create and add the timer notification into the timer table.
        //
        Integer notifID = null;
        notifID = new Integer(++counterID);

        // The sequenceNumber and the timeStamp attributes are updated
        // when the notification is emitted by the timer.
        //
        TimerNotification notif = new TimerNotification(type, this, 0, 0, message, notifID);
        notif.setUserData(userData);

        Object[] obj = new Object[6];

        TimerAlarmClock alarmClock;
        if (fixedRate)
        {
          alarmClock = new TimerAlarmClock(this, date);
        }
        else
        {
          alarmClock = new TimerAlarmClock(this, (date.getTime() - currentDate.getTime()));
        }

        // Fix bug 00417.B
        // The date registered into the timer is a clone from the date parameter.
        //
        Date d = new Date(date.getTime());

        obj[TIMER_NOTIF_INDEX] = (Object)notif;
        obj[TIMER_DATE_INDEX] = (Object)d;
        obj[TIMER_PERIOD_INDEX] = (Object) new Long(period);
        obj[TIMER_NB_OCCUR_INDEX] = (Object) new Long(nbOccurences);
        obj[ALARM_CLOCK_INDEX] = (Object)alarmClock;
        obj[FIXED_RATE_INDEX] = new Boolean(fixedRate);

        if (isTraceOn()) {
            trace("addNotification", "adding timer notification:" +
                  "\n\tNotification source = " + notif.getSource() +
                  "\n\tNotification type = " + notif.getType() +
                  "\n\tNotification ID = " + notifID +
                  "\n\tNotification date = " + d +
                  "\n\tNotification period = " + period +
                  "\n\tNotification nb of occurrences = " + nbOccurences +
                  "\n\tNotification executes at fixed rate = " + fixedRate);
        }

        timerTable.put(notifID, obj);

        // Update and start the TimerAlarmClock.
        //
        if (isActive == true) {
          if (fixedRate)
          {
	    timer.schedule(alarmClock, alarmClock.next);
          }
          else
          {
            timer.schedule(alarmClock, alarmClock.timeout);
          }
        }

        if (isTraceOn()) {
            trace("addNotification", "timer notification added");
        }
        return notifID;
public synchronized java.lang.IntegeraddNotification(java.lang.String type, java.lang.String message, java.lang.Object userData, java.util.Date date, long period, long nbOccurences)
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurrences.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date.
For once-off notifications, the notification is delivered immediately.
For periodic notifications, the first notification is delivered immediately and the subsequent ones are spaced as specified by the period parameter.

Note that once the timer notification has been added into the list of notifications, its associated date, period and number of occurrences cannot be updated.

In the case of a periodic notification, uses a fixed-delay execution scheme, as specified in {@link java.util.Timer}. In order to use a fixed-rate execution scheme, use {@link #addNotification(String, String, Object, Date, long, long, boolean)} instead.

param
type The timer notification type.
param
message The timer notification detailed message.
param
userData The timer notification user data object.
param
date The date when the notification occurs.
param
period The period of the timer notification (in milliseconds).
param
nbOccurences The total number the timer notification will be emitted.
return
The identifier of the new created timer notification.
exception
java.lang.IllegalArgumentException The date is {@code null} or the period or the number of occurrences is negative.
see
#addNotification(String, String, Object, Date, long, long, boolean)


      return addNotification(type, message, userData, date, period, nbOccurences, false);
public synchronized java.lang.IntegeraddNotification(java.lang.String type, java.lang.String message, java.lang.Object userData, java.util.Date date, long period)
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date and period and a null number of occurrences.

The timer notification will repeat continuously using the timer period using a fixed-delay execution scheme, as specified in {@link java.util.Timer}. In order to use a fixed-rate execution scheme, use {@link #addNotification(String, String, Object, Date, long, long, boolean)} instead.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date. The first notification is delivered immediately and the subsequent ones are spaced as specified by the period parameter.

param
type The timer notification type.
param
message The timer notification detailed message.
param
userData The timer notification user data object.
param
date The date when the notification occurs.
param
period The period of the timer notification (in milliseconds).
return
The identifier of the new created timer notification.
exception
java.lang.IllegalArgumentException The date is {@code null} or the period is negative.


        return (addNotification(type, message, userData, date, period, 0));
public synchronized java.lang.IntegeraddNotification(java.lang.String type, java.lang.String message, java.lang.Object userData, java.util.Date date)
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date and a null period and number of occurrences.

The timer notification will be handled once at the specified date.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date and the notification is delivered immediately.

param
type The timer notification type.
param
message The timer notification detailed message.
param
userData The timer notification user data object.
param
date The date when the notification occurs.
return
The identifier of the new created timer notification.
exception
java.lang.IllegalArgumentException The date is {@code null}.



        return (addNotification(type, message, userData, date, 0, 0));
voiddebug(java.lang.String clz, java.lang.String func, java.lang.String info)

        Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_TIMER, clz, func, info);
voiddebug(java.lang.String func, java.lang.String info)

        debug(dbgTag, func, info);
public synchronized java.util.VectorgetAllNotificationIDs()
Gets all timer notification identifiers registered into the list of notifications.

return
A vector of Integer objects containing all the timer notification identifiers.
The vector is empty if there is no timer notification registered for this timer MBean.

	return new Vector<Integer>(timerTable.keySet());
public java.util.DategetDate(java.lang.Integer id)
Gets a copy of the date associated to a timer notification.

param
id The timer notification identifier.
return
A copy of the date or null if the identifier is not mapped to any timer notification registered for this timer MBean.


        Object[] obj = (Object[])timerTable.get(id);
        if (obj != null) {
            Date date = (Date)obj[TIMER_DATE_INDEX];
            return (new Date(date.getTime()));
        }
        return null;
public java.lang.BooleangetFixedRate(java.lang.Integer id)
Gets a copy of the flag indicating whether a periodic notification is executed at fixed-delay or at fixed-rate.

param
id The timer notification identifier.
return
A copy of the flag indicating whether a periodic notification is executed at fixed-delay or at fixed-rate.


      Object[] obj = (Object[])timerTable.get(id);
      if (obj != null) {
        Boolean fixedRate = (Boolean)obj[FIXED_RATE_INDEX];
        return (new Boolean(fixedRate.booleanValue()));
      }
      return null;
public intgetNbNotifications()
Gets the number of timer notifications registered into the list of notifications.

return
The number of timer notifications.

        return timerTable.size();
public java.lang.LonggetNbOccurences(java.lang.Integer id)
Gets a copy of the remaining number of occurrences associated to a timer notification.

param
id The timer notification identifier.
return
A copy of the remaining number of occurrences or null if the identifier is not mapped to any timer notification registered for this timer MBean.


        Object[] obj = (Object[])timerTable.get(id);
        if (obj != null) {
            Long nbOccurences = (Long)obj[TIMER_NB_OCCUR_INDEX];
            return (new Long(nbOccurences.longValue()));
        }
        return null;
public synchronized java.util.VectorgetNotificationIDs(java.lang.String type)
Gets all the identifiers of timer notifications corresponding to the specified type.

param
type The timer notification type.
return
A vector of Integer objects containing all the identifiers of timer notifications with the specified type.
The vector is empty if there is no timer notifications registered for this timer MBean with the specified type.


        String s;

        Vector<Integer> v = new Vector<Integer>();

	for (Map.Entry<Integer,Object[]> entry : timerTable.entrySet()) {
	    Object[] obj = entry.getValue();
	    s = ((TimerNotification)obj[TIMER_NOTIF_INDEX]).getType();
	    if ((type == null) ? s == null : type.equals(s))
		v.addElement(entry.getKey());
	}
        return v;
public synchronized javax.management.MBeanNotificationInfo[]getNotificationInfo()

	Set<String> notifTypes = new TreeSet<String>();
	for (Iterator it = timerTable.values().iterator(); it.hasNext(); ) {
	    Object[] entry = (Object[]) it.next();
	    TimerNotification notif = (TimerNotification)
		entry[TIMER_NOTIF_INDEX];
	    notifTypes.add(notif.getType());
	}
	String[] notifTypesArray =
	    notifTypes.toArray(new String[0]);
	return new MBeanNotificationInfo[] {
	    new MBeanNotificationInfo(notifTypesArray,
				      TimerNotification.class.getName(),
				      "Notification sent by Timer MBean")
	};
public java.lang.StringgetNotificationMessage(java.lang.Integer id)
Gets the timer notification detailed message corresponding to the specified identifier.

param
id The timer notification identifier.
return
The timer notification detailed message or null if the identifier is not mapped to any timer notification registered for this timer MBean.


        Object[] obj = (Object[])timerTable.get(id);
        if (obj != null) {
            return ( (String)((TimerNotification)obj[TIMER_NOTIF_INDEX]).getMessage() );
        }
        return null;
public java.lang.StringgetNotificationType(java.lang.Integer id)
Gets the timer notification type corresponding to the specified identifier.

param
id The timer notification identifier.
return
The timer notification type or null if the identifier is not mapped to any timer notification registered for this timer MBean.


        Object[] obj = (Object[])timerTable.get(id);
        if (obj != null) {
            return ( (String)((TimerNotification)obj[TIMER_NOTIF_INDEX]).getType() );
        }
        return null;
public java.lang.ObjectgetNotificationUserData(java.lang.Integer id)
Gets the timer notification user data object corresponding to the specified identifier.

param
id The timer notification identifier.
return
The timer notification user data object or null if the identifier is not mapped to any timer notification registered for this timer MBean.

        Object[] obj = (Object[])timerTable.get(id);
        if (obj != null) {
            return ( ((TimerNotification)obj[TIMER_NOTIF_INDEX]).getUserData() );
        }
        return null;
public java.lang.LonggetPeriod(java.lang.Integer id)
Gets a copy of the period (in milliseconds) associated to a timer notification.

param
id The timer notification identifier.
return
A copy of the period or null if the identifier is not mapped to any timer notification registered for this timer MBean.


        Object[] obj = (Object[])timerTable.get(id);
        if (obj != null) {
            Long period = (Long)obj[TIMER_PERIOD_INDEX];
            return (new Long(period.longValue()));
        }
        return null;
public booleangetSendPastNotifications()
Gets the flag indicating whether or not the timer sends past notifications.
The default value of the past notifications sending on/off flag is false.

return
The past notifications sending on/off flag value.
see
#setSendPastNotifications

        return sendPastNotifications;
public booleanisActive()
Tests whether the timer MBean is active. A timer MBean is marked active when the {@link #start start} method is called. It becomes inactive when the {@link #stop stop} method is called.
The default value of the active on/off flag is false.

return
true if the timer MBean is active, false otherwise.

        return isActive;
booleanisDebugOn()

        return Trace.isSelected(Trace.LEVEL_DEBUG, Trace.INFO_TIMER);
public booleanisEmpty()
Tests whether the list of timer notifications is empty.

return
true if the list of timer notifications is empty, false otherwise.

        return (timerTable.isEmpty());
booleanisTraceOn()



    // TRACES & DEBUG
    //---------------

      
        return Trace.isSelected(Trace.LEVEL_TRACE, Trace.INFO_TIMER);
voidnotifyAlarmClock(javax.management.timer.TimerAlarmClockNotification notification)
This method is called by the timer each time the TimerAlarmClock has exceeded its timeout.

param
notification The TimerAlarmClock notification.


        TimerNotification timerNotification = null;
        Date timerDate = null;

        // Retrieve the timer notification associated to the alarm-clock.
        //
        TimerAlarmClock alarmClock = (TimerAlarmClock)notification.getSource();

	for (Object[] obj : timerTable.values()) {
            if (obj[ALARM_CLOCK_INDEX] == alarmClock) {
                timerNotification = (TimerNotification)obj[TIMER_NOTIF_INDEX];
                timerDate = (Date)obj[TIMER_DATE_INDEX];
                break;
            }
        }

        // Notify the timer.
        //
        sendNotification(timerDate, timerNotification);

        // Update the notification and the TimerAlarmClock timeout.
        //
        updateTimerTable(timerNotification.getNotificationID());
public voidpostDeregister()
Allows the timer MBean to perform any operations needed after having been unregistered by the MBean server.

Not used in this context.
public voidpostRegister(java.lang.Boolean registrationDone)
Allows the timer MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Not used in this context.
public voidpreDeregister()
Allows the timer MBean to perform any operations it needs before being unregistered by the MBean server.

Stops the timer.

exception
java.lang.Exception


        if (isTraceOn()) {
            trace("preDeregister", "stop the timer");
        }

        // Stop the timer.
        //
        stop();
public javax.management.ObjectNamepreRegister(javax.management.MBeanServer server, javax.management.ObjectName name)
Allows the timer MBean to perform any operations it needs before being registered in the MBean server.

Not used in this context.

param
server The MBean server in which the timer MBean will be registered.
param
name The object name of the timer MBean.
return
The name of the timer MBean registered.
exception
java.lang.Exception

        return name;
public synchronized voidremoveAllNotifications()
Removes all the timer notifications from the list of notifications and resets the counter used to update the timer notification identifiers.


        TimerAlarmClock alarmClock;

	for (Object[] obj : timerTable.values()) {

            // Stop the TimerAlarmClock.
            //
            alarmClock = (TimerAlarmClock)obj[ALARM_CLOCK_INDEX];
//             if (alarmClock != null) {
//                 alarmClock.interrupt();
//                 try {
//                     // Wait until the thread die.
//                     //
//                     alarmClock.join();
//                 } catch (InterruptedException ex) {
//                     // Ignore...
//                 }
	          // Remove the reference on the TimerAlarmClock.
                  //
// 	       }
            alarmClock.cancel();
            alarmClock = null;
        }

        // Remove all the timer notifications from the timer table.
        //
        if (isTraceOn()) {
            trace("removeAllNotifications", "removing all timer notifications");
        }

        timerTable.clear();

        if (isTraceOn()) {
            trace("removeAllNotifications", "all timer notifications removed");
        }

        // Reset the counterID.
        //
        counterID = 0;

        if (isTraceOn()) {
            trace("removeAllNotifications", "timer notification counter ID reset");
        }
public synchronized voidremoveNotification(java.lang.Integer id)
Removes the timer notification corresponding to the specified identifier from the list of notifications.

param
id The timer notification identifier.
exception
InstanceNotFoundException The specified identifier does not correspond to any timer notification in the list of notifications of this timer MBean.


        // Check that the notification to remove is effectively in the timer table.
        //
        if (timerTable.containsKey(id) == false) {
            throw new InstanceNotFoundException("Timer notification to remove not in the list of notifications");
        }

        // Stop the TimerAlarmClock.
        //
        Object[] obj = (Object[])timerTable.get(id);
        TimerAlarmClock alarmClock = (TimerAlarmClock)obj[ALARM_CLOCK_INDEX];
        if (alarmClock != null) {
//             alarmClock.interrupt();
//             try {
//                 // Wait until the thread die.
//                 //
//                 alarmClock.join();
//             } catch (InterruptedException e) {
//                 // Ignore...
//             }
//             // Remove the reference on the TimerAlarmClock.
//             //
	    alarmClock.cancel();
            alarmClock = null;
        }

        // Remove the timer notification from the timer table.
        //
        if (isTraceOn()) {
            trace("removeNotification", "removing timer notification:" +
                  "\n\tNotification source = " + ((TimerNotification)obj[TIMER_NOTIF_INDEX]).getSource() +
                  "\n\tNotification type = " + ((TimerNotification)obj[TIMER_NOTIF_INDEX]).getType() +
                  "\n\tNotification ID = " + ((TimerNotification)obj[TIMER_NOTIF_INDEX]).getNotificationID() +
                  "\n\tNotification date = " + obj[TIMER_DATE_INDEX] +
                  "\n\tNotification period = " + obj[TIMER_PERIOD_INDEX] +
                  "\n\tNotification nb of occurrences = " + obj[TIMER_NB_OCCUR_INDEX] +
                  "\n\tNotification executes at fixed rate = " + obj[FIXED_RATE_INDEX]);
        }

        timerTable.remove(id);

        if (isTraceOn()) {
            trace("removeNotification", "timer notification removed");
        }
public synchronized voidremoveNotifications(java.lang.String type)
Removes all the timer notifications corresponding to the specified type from the list of notifications.

param
type The timer notification type.
exception
InstanceNotFoundException The specified type does not correspond to any timer notification in the list of notifications of this timer MBean.


        Vector<Integer> v = getNotificationIDs(type);

        if (v.isEmpty())
            throw new InstanceNotFoundException("Timer notifications to remove not in the list of notifications");

        for (Integer i : v)
            removeNotification(i);
voidsendNotification(java.util.Date timeStamp, javax.management.timer.TimerNotification notification)
This method is used by the timer MBean to update and send a timer notification to all the listeners registered for this kind of notification.

param
timeStamp The notification emission date.
param
notification The timer notification to send.


        if (isTraceOn()) {
            trace("sendNotification", "sending timer notification:" +
                  "\n\tNotification source = " + notification.getSource() +
                  "\n\tNotification type = " + notification.getType() +
                  "\n\tNotification ID = " + notification.getNotificationID() +
                  "\n\tNotification date = " + timeStamp);
        }
        long curSeqNumber;
        synchronized(this) {
            sequenceNumber = sequenceNumber + 1;
	    curSeqNumber = sequenceNumber;
        }
        synchronized (notification) {
            notification.setTimeStamp(timeStamp.getTime());
            notification.setSequenceNumber(curSeqNumber);
            this.sendNotification((TimerNotification)notification.cloneTimerNotification());
        }

        if (isTraceOn()) {
            trace("sendNotification", "timer notification sent");
        }
private synchronized voidsendPastNotifications(java.util.Date currentDate, boolean currentFlag)
Sends or not past notifications depending on the specified flag.

param
currentDate The current date.
param
currentFlag The flag indicating if past notifications must be sent or not.


        TimerNotification notif;
        Integer notifID;
        Date date;

	for (Object[] obj : timerTable.values()) {

            // Retrieve the timer notification and the date notification.
            //
            notif = (TimerNotification)obj[TIMER_NOTIF_INDEX];
            notifID = notif.getNotificationID();
            date = (Date)obj[TIMER_DATE_INDEX];

            // Update the timer notification while:
            //  - the timer notification date is earlier than the current date
            //  - the timer notification has not been removed from the timer table.
            //
            while ( (currentDate.after(date)) && (timerTable.containsKey(notifID)) ) {

                if (currentFlag == true) {
                    if (isTraceOn()) {
                        trace("sendPastNotifications", "sending past timer notification:" +
                              "\n\tNotification source = " + notif.getSource() +
                              "\n\tNotification type = " + notif.getType() +
                              "\n\tNotification ID = " + notif.getNotificationID() +
                              "\n\tNotification date = " + date +
                              "\n\tNotification period = " + obj[TIMER_PERIOD_INDEX] +
                              "\n\tNotification nb of occurrences = " + obj[TIMER_NB_OCCUR_INDEX] +
                              "\n\tNotification executes at fixed rate = " + obj[FIXED_RATE_INDEX]);
                    }
                    sendNotification(date, notif);

                    if (isTraceOn()) {
                        trace("sendPastNotifications", "past timer notification sent");
                    }
                }

                // Update the date and the number of occurrences of the timer notification.
                //
                updateTimerTable(notif.getNotificationID());
            }
        }
public voidsetSendPastNotifications(boolean value)
Sets the flag indicating whether the timer sends past notifications or not.
The default value of the past notifications sending on/off flag is false.

param
value The past notifications sending on/off flag value.
see
#getSendPastNotifications

        sendPastNotifications = value;
public synchronized voidstart()
Starts the timer.

If there is one or more timer notifications before the time in the list of notifications, the notification is sent according to the sendPastNotifications flag and then, updated according to its period and remaining number of occurrences. If the timer notification date remains earlier than the current date, this notification is just removed from the list of notifications.


        if (isTraceOn()) {
            trace("start", "starting the timer");
        }

        // Start the TimerAlarmClock.
        //
        if (isActive == false) {

	    timer = new java.util.Timer();

            TimerAlarmClock alarmClock;
            Date date;

            Date currentDate = new Date();

            // Send or not past notifications depending on the flag.
            // Update the date and the number of occurrences of past notifications
            // to make them later than the current date.
            //
            sendPastNotifications(currentDate, sendPastNotifications);

            // Update and start all the TimerAlarmClocks.
            // Here, all the notifications in the timer table are later than the current date.
            //
	    for (Object[] obj : timerTable.values()) {

                // Retrieve the date notification and the TimerAlarmClock.
                //
                date = (Date)obj[TIMER_DATE_INDEX];

                // Update all the TimerAlarmClock timeouts and start them.
                //
                boolean fixedRate = ((Boolean)obj[FIXED_RATE_INDEX]).booleanValue();
                if (fixedRate)
                {
                  alarmClock = new TimerAlarmClock(this, date);
                  obj[ALARM_CLOCK_INDEX] = (Object)alarmClock;
                  timer.schedule(alarmClock, alarmClock.next);
                }
                else
                {
                  alarmClock = new TimerAlarmClock(this, (date.getTime() - currentDate.getTime()));
                  obj[ALARM_CLOCK_INDEX] = (Object)alarmClock;
                  timer.schedule(alarmClock, alarmClock.timeout);
                }
            }

            // Set the state to ON.
            //
            isActive = true;

            if (isTraceOn()) {
                trace("start", "timer started");
            }
        } else {
            if (isTraceOn()) {
                trace("start", "the timer is already activated");
            }
        }
public synchronized voidstop()
Stops the timer.


        if (isTraceOn()) {
            trace("stop", "stoping the timer");
        }

        // Stop the TimerAlarmClock.
        //
        if (isActive == true) {

            TimerAlarmClock alarmClock;

	    for (Object[] obj : timerTable.values()) {

                // Stop all the TimerAlarmClock.
                //
                alarmClock = (TimerAlarmClock)obj[ALARM_CLOCK_INDEX];
                if (alarmClock != null) {
//                     alarmClock.interrupt();
//                     try {
//                         // Wait until the thread die.
//                         //
//                         alarmClock.join();
//                     } catch (InterruptedException ex) {
//                         // Ignore...
//                     }
//                     // Remove the reference on the TimerAlarmClock.
//                     //

		    alarmClock.cancel();
                    alarmClock = null;
                }
            }

            timer.cancel();

            // Set the state to OFF.
            //
            isActive = false;

            if (isTraceOn()) {
                trace("stop", "timer stopped");
            }
        } else {
            if (isTraceOn()) {
                trace("stop", "the timer is already deactivated");
            }
        }
voidtrace(java.lang.String clz, java.lang.String func, java.lang.String info)

        Trace.send(Trace.LEVEL_TRACE, Trace.INFO_TIMER, clz, func, info);
voidtrace(java.lang.String func, java.lang.String info)

        trace(dbgTag, func, info);
private synchronized voidupdateTimerTable(java.lang.Integer notifID)
If the timer notification is not periodic, it is removed from the list of notifications.

If the timer period of the timer notification has a non null periodicity, the date of the timer notification is updated by adding the periodicity. The associated TimerAlarmClock is updated by setting its timeout to the period value.

If the timer period has a defined number of occurrences, the timer notification is updated if the number of occurrences has not yet been reached. Otherwise it is removed from the list of notifications.

param
notifID The timer notification identifier to update.


        // Retrieve the timer notification and the TimerAlarmClock.
        //
        Object[] obj = (Object[])timerTable.get(notifID);
        Date date = (Date)obj[TIMER_DATE_INDEX];
        Long period = (Long)obj[TIMER_PERIOD_INDEX];
        Long nbOccurences = (Long)obj[TIMER_NB_OCCUR_INDEX];
        Boolean fixedRate = (Boolean)obj[FIXED_RATE_INDEX];
        TimerAlarmClock alarmClock = (TimerAlarmClock)obj[ALARM_CLOCK_INDEX];

        if (period.longValue() != 0) {

            // Update the date and the number of occurrences of the timer notification
            // and the TimerAlarmClock time out.
            // NOTES :
            //   nbOccurences = 0 notifies an infinite periodicity.
            //   nbOccurences = 1 notifies a finite periodicity that has reached its end.
            //   nbOccurences > 1 notifies a finite periodicity that has not yet reached its end.
            //
            if ((nbOccurences.longValue() == 0) || (nbOccurences.longValue() > 1)) {

                date.setTime(date.getTime() + period.longValue());
                obj[TIMER_NB_OCCUR_INDEX] = new Long(java.lang.Math.max(0L, (nbOccurences.longValue() - 1)));
                nbOccurences = (Long)obj[TIMER_NB_OCCUR_INDEX];

                if (isActive == true) {
                  if (fixedRate.booleanValue())
                  {
                    alarmClock = new TimerAlarmClock(this, date);
                    obj[ALARM_CLOCK_INDEX] = (Object)alarmClock;
		    timer.schedule(alarmClock, alarmClock.next);
                  }
                  else
                  {
                    alarmClock = new TimerAlarmClock(this, period.longValue());
                    obj[ALARM_CLOCK_INDEX] = (Object)alarmClock;
		    timer.schedule(alarmClock, alarmClock.timeout);
                  }
                }
                if (isTraceOn()) {
                    TimerNotification notif = (TimerNotification)obj[TIMER_NOTIF_INDEX];
                    trace("updateTimerTable", "update timer notification with:" +
                          "\n\tNotification source = " + notif.getSource() +
                          "\n\tNotification type = " + notif.getType() +
                          "\n\tNotification ID = " + notifID +
                          "\n\tNotification date = " + date +
                          "\n\tNotification period = " + period +
                          "\n\tNotification nb of occurrences = " + nbOccurences +
                          "\n\tNotification executes at fixed rate = " + fixedRate);
                }
            }
            else {
                if (alarmClock != null) {
//                     alarmClock.interrupt();
//                     try {
//                         // Wait until the thread die.
//                         //
//                         alarmClock.join();
//                     } catch (InterruptedException e) {
//                         // Ignore...
//                     }
		    alarmClock.cancel();
                    // Remove the reference on the TimerAlarmClock.
                    //
                    alarmClock = null;
                }
                timerTable.remove(notifID);
            }
        }
        else {
            if (alarmClock != null) {
//                 alarmClock.interrupt();
//                 try {
//                     // Wait until the thread die.
//                     //
//                     alarmClock.join();
//                 } catch (InterruptedException e) {
//                     // Ignore...
//                 }

		   alarmClock.cancel();

                // Remove the reference on the TimerAlarmClock.
                //
                alarmClock = null;
            }
            timerTable.remove(notifID);
        }