org.itsnat.core.event

Interface ItsNatTimerHandle

All Superinterfaces:

ItsNatUserData

public interface ItsNatTimerHandle
extends ItsNatUserData

Represents a scheduled/timer task by an ItsNatTimer

Author:

Jose Maria Arranz Santamaria

Method Summary

Methods

Modifier and Type	Method and Description
boolean	cancel() Cancels this timer task.
long	getFirstTime() Returns the time, in the format returned by Date.getTime(), at which the task was (or is going to be) executed by the first time.
ItsNatTimer	getItsNatTimer() Returns the timer manager this scheduled task belongs to.
long	getPeriod() Returns the time in milliseconds between successive task executions.
boolean	isCancelled() Informs whether this timer task is cancelled
long	scheduledExecutionTime() Returns the scheduled execution time of the most recent actual execution of this task.

Methods inherited from interface org.itsnat.core.ItsNatUserData

containsUserValueName, getUserValue, getUserValueNames, removeUserValue, setUserValue

Method Detail

getItsNatTimer

ItsNatTimer getItsNatTimer()

Returns the timer manager this scheduled task belongs to.

Returns:

the timer manager.

getFirstTime

long getFirstTime()

Returns the time, in the format returned by Date.getTime(), at which the task was (or is going to be) executed by the first time.

Returns:

the time of the first time.

getPeriod

long getPeriod()

Returns the time in milliseconds between successive task executions.

Returns:

the period in milliseconds. 0 if the task is executed only once.

cancel

boolean cancel()

Cancels this timer task. If the task has been scheduled for one-time execution and has not yet run, or has not yet been scheduled, it will never run. If the task has been scheduled for repeated execution, it will never run again. (If the task is running when this call occurs, the task will run to completion, but will never run again.)

Note that calling this method from within the EventListener.handleEvent(Event) method of a repeating timer task absolutely guarantees that the timer task will not run again.

This method may be called repeatedly; the second and subsequent calls have no effect.

Note: documentation copied (and slightly modified) from java.util.TimerTask.cancel().

Returns:

true if this task is scheduled for one-time execution and has not yet run, or this task is scheduled for repeated execution. Returns false if the task was scheduled for one-time execution and has already run, or if the task was never scheduled, or if the task was already cancelled. (Loosely speaking, this method returns true if it prevents one or more scheduled executions from taking place.)

isCancelled

boolean isCancelled()

Informs whether this timer task is cancelled

Returns:

true if this task is cancelled.

See Also:

cancel()

scheduledExecutionTime

long scheduledExecutionTime()

Returns the scheduled execution time of the most recent actual execution of this task. (If this method is invoked while task execution is in progress, the return value is the scheduled execution time of the ongoing task execution.)

This method is typically invoked from within a task's EventListener.handleEvent(Event) method, to determine whether the current execution of the task is sufficiently timely to warrant performing the scheduled activity:

   public void run() {
       if (System.currentTimeMillis() - scheduledExecutionTime() >=
           MAX_TARDINESS)
               return;  // Too late; skip this execution.
       // Perform the task
   }
 

This method is typically not used in conjunction with fixed-delay execution repeating tasks, as their scheduled execution times are allowed to drift over time, and so are not terribly significant.

Note: documentation copied (and slightly modified) from java.util.TimerTask.scheduledExecutionTime().

Returns:

the time at which the most recent execution of this task was scheduled to occur, in the format returned by Date.getTime(). The return value is the same as getFirstTime() if the task has yet to commence its first execution.