001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013:
014: package org.itsnat.core.event;
015:
016: import org.itsnat.core.ItsNatTimer;
017: import org.itsnat.core.ItsNatUserData;
018:
019: /**
020: * Represents a scheduled/timer task by an {@link ItsNatTimer}
021: *
022: * @author Jose Maria Arranz Santamaria
023: */
024: public interface TimerHandle extends ItsNatUserData {
025: /**
026: * Returns the timer manager this scheduled task belongs to.
027: *
028: * @return the timer manager.
029: */
030: public ItsNatTimer getItsNatTimer();
031:
032: /**
033: * Returns the time, in the format returned by <code>Date.getTime()</code>, at which
034: * the task was (or is going to be) executed by the first time.
035: *
036: * @return the time of the first time.
037: */
038: public long getFirstTime();
039:
040: /**
041: * Returns the time in milliseconds between successive task executions.
042: *
043: * @return the period in milliseconds. 0 if the task is executed only once.
044: */
045: public long getPeriod();
046:
047: /**
048: * Cancels this timer task. If the task has been scheduled for one-time
049: * execution and has not yet run, or has not yet been scheduled, it will
050: * never run. If the task has been scheduled for repeated execution, it
051: * will never run again. (If the task is running when this call occurs,
052: * the task will run to completion, but will never run again.)
053: *
054: * <p>Note that calling this method from within the
055: * <code>EventListener.handleEvent(Event)</code>
056: * method of a repeating timer task absolutely guarantees that the timer task will
057: * not run again.
058: *
059: * <p>This method may be called repeatedly; the second and subsequent
060: * calls have no effect.
061: *
062: * <p>Note: documentation copied (and slightly modified) from
063: * <code>java.util.TimerTask.cancel()</code>.</p>
064: *
065: * @return true if this task is scheduled for one-time execution and has
066: * not yet run, or this task is scheduled for repeated execution.
067: * Returns false if the task was scheduled for one-time execution
068: * and has already run, or if the task was never scheduled, or if
069: * the task was already cancelled. (Loosely speaking, this method
070: * returns <tt>true</tt> if it prevents one or more scheduled
071: * executions from taking place.)
072: */
073: public boolean cancel();
074:
075: /**
076: * Returns the <i>scheduled</i> execution time of the most recent
077: * <i>actual</i> execution of this task. (If this method is invoked
078: * while task execution is in progress, the return value is the scheduled
079: * execution time of the ongoing task execution.)
080: *
081: * <p>This method is typically invoked from within a task's
082: * <code>EventListener.handleEvent(Event)</code>
083: * method, to determine whether the current execution of the task is sufficiently
084: * timely to warrant performing the scheduled activity:
085: * <pre>
086: * public void run() {
087: * if (System.currentTimeMillis() - scheduledExecutionTime() >=
088: * MAX_TARDINESS)
089: * return; // Too late; skip this execution.
090: * // Perform the task
091: * }
092: * </pre>
093: * This method is typically <i>not</i> used in conjunction with
094: * <i>fixed-delay execution</i> repeating tasks, as their scheduled
095: * execution times are allowed to drift over time, and so are not terribly
096: * significant.
097: *
098: * <p>Note: documentation copied (and slightly modified) from
099: * <code>java.util.TimerTask.scheduledExecutionTime()</code>.</p>
100: *
101: * @return the time at which the most recent execution of this task was
102: * scheduled to occur, in the format returned by Date.getTime().
103: * The return value is the same as {@link #getFirstTime()} if the task has yet to commence
104: * its first execution.
105: */
106: public long scheduledExecutionTime();
107: }
|