package java.util;

/**
 * A task that can be scheduled for one-time or repeated execution by a Timer.
 *
 * @deprecated Please consider <code>ej.bon.TimerTask</code> from BON
 *             specification instead.
 */
@Deprecated
public abstract class TimerTask implements Runnable {

    /**
     * Creates a new timer task.
     */
    protected TimerTask() {
    }

    /**
     * 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.)
     *
     * <p>
     * Note that calling this method from within the <code>run</code> method of a
     * repeating timer task absolutely guarantees that the timer task will not run
     * again.
     *
     * <p>
     * This method may be called repeatedly; the second and subsequent calls have no
     * effect.
     *
     * @return 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 <code>true</code> if it
     *         prevents one or more scheduled executions from taking place.)
     */
    public boolean cancel() {
        throw new RuntimeException();
    }

    /**
     * The action to be performed by this timer task.
     */
    @Override
    public abstract void run();

    /**
     * Returns the <i>scheduled</i> execution time of the most recent <i>actual</i> 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.)
     *
     * <p>
     * This method is typically invoked from within a task's run method, to determine whether the
     * current execution of the task is sufficiently timely to warrant performing the scheduled
     * activity:
     *
     * <pre>
     * public void run() {
     * 	if (System.currentTimeMillis() - scheduledExecutionTime() &gt;= MAX_TARDINESS)
     * 		return; // Too late; skip this execution.
     * 	// Perform the task
     * }
     * </pre>
     *
     * This method is typically <i>not</i> used in conjunction with <i>fixed-delay execution</i>
     * repeating tasks, as their scheduled execution times are allowed to drift over time, and so are
     * not terribly significant.
     *
     * @return 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 undefined if the task has yet to
     *         commence its first execution.
     * @see Date#getTime()
     */
    public long scheduledExecutionTime() {
        throw new RuntimeException();
    }
}