/*
 * Copyright 2011-2023 MicroEJ Corp. All rights reserved.
 * This library is provided in source code for use, modification and test, subject to license terms.
 * Any modification of the source code will break MicroEJ Corp. warranties on the whole library.
 */
package ej.bon;

import java.util.Date;

/**
 * A task that can be scheduled for one-time or repeated execution by a Timer.
 */
public abstract class TimerTask implements Runnable {

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

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

    /**
     * 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 run 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.
     *
     * @return <code>true</code> if this task is scheduled for one-time execution
     *         and has not yet run, or this task is scheduled for repeated
     *         execution. Returns <code>false</code> 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 canceled (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();
    }

    /**
     * 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.)
     * <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 (CurrentTime.get() - scheduledExecutionTime() &gt;= MAX_TARDINESS)
     * 		return; // Too late; skip this execution.
     * 	// Perform the task
     * }
     * </pre>
     *
     * <p>
     * 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.
     *
     * @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();
    }

    /**
     * Method invoked when this {@link TimerTask} terminates due to an uncaught
     * exception thrown by {@link TimerTask#run()}.
     * <p>
     * The default implementation of this method handles the uncaught exception as
     * following:
     * <ol>
     * <li>if the {@link Timer} instance has a registered handler, this handler is
     * invoked,</li>
     * <li>otherwise, if the {@link Timer} class has a registered default handler,
     * this handler is invoked,</li>
     * <li>otherwise, the task is canceled and {@link Throwable#printStackTrace()}
     * is invoked on the given exception.
     * </ol>
     * <p>
     * Any exception thrown by this method will be ignored.
     *
     * @param timer
     *            The {@link Timer} on which this {@link TimerTask} is scheduled.
     * @param e
     *            The uncaught exception.
     * @see Timer#setDefaultUncaughtExceptionHandler(Thread.UncaughtExceptionHandler)
     * @see Timer#setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler)
     */
    public void uncaughtException(Timer timer, Throwable e) {
        throw new RuntimeException();
    }
}