/*
 * 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.io.PrintStream;
import java.lang.Thread.UncaughtExceptionHandler;
import java.util.Date;
import ej.annotation.Nullable;

/**
 * A facility for threads to schedule tasks for future execution in a background
 * thread. Tasks may be scheduled for one-time execution, or for repeated
 * execution at regular intervals.
 * <p>
 * Corresponding to each Timer object is a single background thread that is used
 * to execute all of the timer's tasks, sequentially. Timer tasks should
 * complete quickly. If a timer task takes excessive time to complete, it "hogs"
 * the timer's task execution thread. This can, in turn, delay the execution of
 * subsequent tasks, which may "bunch up" and execute in rapid succession when
 * (and if) the offending task finally completes.
 * <p>
 * By default, the task execution thread does not run as a daemon thread, so it
 * is capable of keeping an application from terminating. If a caller wants to
 * terminate a timer's task execution thread, the caller should invoke the
 * timer's cancel method.
 * <p>
 * If a task execution terminates unexpectedly, the uncaughtException method is
 * invoked on this task.
 * <p>
 * This class is thread-safe: multiple threads can share a single Timer object
 * without the need for external synchronization.
 * <p>
 * This class does not offer real-time guarantees: it schedules tasks using the
 * Object.wait(long) method. The resolution of the Timer is implementation and
 * device dependent.
 * <p>
 * Timers function only within a single VM and are canceled when the VM exits.
 * When the VM is started no timers exist, they are created only by application
 * request.
 */
public class Timer {

    /**
     * Creates a new timer. The associated thread does not run as a daemon thread,
     * which may prevent an application from terminating.
     */
    public Timer() {
        throw new RuntimeException();
    }

    /**
     * Creates a new timer.
     * <p>
     * If the given boolean is <code>true</code>, a thread is created to execute
     * this timer. The associated thread does not run as a daemon thread, which may
     * prevent an application from terminating. All the {@link TimerTask} scheduled
     * by the timer will be executed in the context of the associated thread.
     * <p>
     * Otherwise an applicative thread must call the {@link #run()} method in order
     * to execute tasks scheduling.
     *
     * @param automatic
     *            If <code>true</code> a thread is created to run this timer,
     *            otherwise the application must manage this timer.
     * @see #run()
     */
    public Timer(boolean automatic) {
        throw new RuntimeException();
    }

    /**
     * Schedules the specified task for execution after the specified delay.
     *
     * @param task
     *            task to be scheduled.
     * @param delay
     *            delay in milliseconds before task is to be executed. Note that the
     *            actual delay may be different from the amount requested since the
     *            resolution of the Timer is implementation and device dependent.
     * @throws IllegalArgumentException
     *             if delay is negative, or delay + CurrentTime.get() is negative.
     * @throws IllegalStateException
     *             if task was already scheduled or canceled, or timer was canceled.
     */
    public void schedule(TimerTask task, long delay) {
        throw new RuntimeException();
    }

    /**
     * Schedules the specified task for execution at the specified time. If the time
     * is in the past, the task is scheduled for immediate execution.
     *
     * @param task
     *            task to be scheduled.
     * @param time
     *            time at which task is to be executed.
     * @throws IllegalArgumentException
     *             if time.getTime() is negative.
     * @throws IllegalStateException
     *             if task was already scheduled or canceled, timer was canceled, or
     *             timer thread terminated.
     */
    public void schedule(TimerTask task, Date time) {
        throw new RuntimeException();
    }

    /**
     * Schedules the specified task for repeated fixed-delay execution, beginning
     * after the specified delay. Subsequent executions take place at approximately
     * regular intervals separated by the specified period. Note that the actual
     * delay may be different from the amount requested since the resolution of the
     * Timer is implementation and device dependent.
     * <p>
     * In fixed-delay execution, each execution is scheduled relative to the actual
     * execution time of the previous execution. If an execution is delayed for any
     * reason (such as garbage collection or other background activity), subsequent
     * executions will be delayed as well. In the long run, the frequency of
     * execution will generally be slightly lower than the reciprocal of the
     * specified period (assuming the system clock underlying Object.wait(long) is
     * accurate).
     * <p>
     * Fixed-delay execution is appropriate for recurring activities that require
     * "smoothness." In other words, it is appropriate for activities where it is
     * more important to keep the frequency accurate in the short run than in the
     * long run. This includes most animation tasks, such as blinking a cursor at
     * regular intervals. It also includes tasks wherein regular activity is
     * performed in response to human input, such as automatically repeating a
     * character as long as a key is held down.
     *
     * @param task
     *            task to be scheduled.
     * @param delay
     *            delay in milliseconds before task is to be executed. Note that the
     *            actual delay may be different from the amount requested since the
     *            resolution of the Timer is implementation and device dependent.
     * @param period
     *            time in milliseconds between successive task executions.
     *
     * @throws IllegalArgumentException
     *             if delay is negative, or delay + CurrentTime.get() is negative.
     * @throws IllegalStateException
     *             if task was already scheduled or canceled, timer was canceled, or
     *             timer thread terminated.
     */
    public void schedule(TimerTask task, long delay, long period) {
        throw new RuntimeException();
    }

    /**
     * Schedules the specified task for repeated fixed-delay execution, beginning at
     * the specified time. Subsequent executions take place at approximately regular
     * intervals, separated by the specified period.
     * <p>
     * In fixed-delay execution, each execution is scheduled relative to the actual
     * execution time of the previous execution. If an execution is delayed for any
     * reason (such as garbage collection or other background activity), subsequent
     * executions will be delayed as well. In the long run, the frequency of
     * execution will generally be slightly lower than the reciprocal of the
     * specified period (assuming the system clock underlying Object.wait(long) is
     * accurate).
     * <p>
     * Fixed-delay execution is appropriate for recurring activities that require
     * "smoothness." In other words, it is appropriate for activities where it is
     * more important to keep the frequency accurate in the short run than in the
     * long run. This includes most animation tasks, such as blinking a cursor at
     * regular intervals. It also includes tasks wherein regular activity is
     * performed in response to human input, such as automatically repeating a
     * character as long as a key is held down.
     *
     * @param task
     *            task to be scheduled.
     * @param firstTime
     *            First time at which task is to be executed.
     * @param period
     *            time in milliseconds between successive task executions.
     *
     * @throws IllegalArgumentException
     *             if time.getTime() is negative.
     * @throws IllegalStateException
     *             if task was already scheduled or canceled, timer was canceled, or
     *             timer thread terminated.
     */
    public void schedule(TimerTask task, Date firstTime, long period) {
        throw new RuntimeException();
    }

    /**
     * Schedules the specified task for repeated fixed-rate execution, beginning
     * after the specified delay. Subsequent executions take place at approximately
     * regular intervals, separated by the specified period.
     * <p>
     * In fixed-rate execution, each execution is scheduled relative to the
     * scheduled execution time of the initial execution. If an execution is delayed
     * for any reason (such as garbage collection or other background activity), two
     * or more executions will occur in rapid succession to "catch up." In the long
     * run, the frequency of execution will be exactly the reciprocal of the
     * specified period (assuming the system clock underlying Object.wait(long) is
     * accurate).
     * <p>
     * Fixed-rate execution is appropriate for recurring activities that are
     * sensitive to absolute time, such as ringing a chime every hour on the hour,
     * or running scheduled maintenance every day at a particular time. It is also
     * appropriate for for recurring activities where the total time to perform a
     * fixed number of executions is important, such as a countdown timer that ticks
     * once every second for ten seconds. Finally, fixed-rate execution is
     * appropriate for scheduling multiple repeating timer tasks that must remain
     * synchronized with respect to one another.
     *
     * @param task
     *            task to be scheduled.
     * @param delay
     *            delay in milliseconds before task is to be executed. Note that the
     *            actual delay may be different from the amount requested since the
     *            resolution of the Timer is implementation and device dependent.
     * @param period
     *            time in milliseconds between successive task executions.
     *
     * @throws IllegalArgumentException
     *             if delay is negative, or delay + CurrentTime.get() is negative.
     * @throws IllegalStateException
     *             if task was already scheduled or canceled, timer was canceled, or
     *             timer thread terminated.
     */
    public void scheduleAtFixedRate(TimerTask task, long delay, long period) {
        throw new RuntimeException();
    }

    /**
     * Schedules the specified task for repeated fixed-rate execution, beginning at
     * the specified time. Subsequent executions take place at approximately regular
     * intervals, separated by the specified period.
     * <p>
     * In fixed-rate execution, each execution is scheduled relative to the
     * scheduled execution time of the initial execution. If an execution is delayed
     * for any reason (such as garbage collection or other background activity), two
     * or more executions will occur in rapid succession to "catch up." In the long
     * run, the frequency of execution will be exactly the reciprocal of the
     * specified period (assuming the system clock underlying Object.wait(long) is
     * accurate).
     * <p>
     * Fixed-rate execution is appropriate for recurring activities that are
     * sensitive to absolute time, such as ringing a chime every hour on the hour,
     * or running scheduled maintenance every day at a particular time. It is also
     * appropriate for for recurring activities where the total time to perform a
     * fixed number of executions is important, such as a countdown timer that ticks
     * once every second for ten seconds. Finally, fixed-rate execution is
     * appropriate for scheduling multiple repeating timer tasks that must remain
     * synchronized with respect to one another.
     *
     * @param task
     *            task to be scheduled.
     * @param firstTime
     *            first time at which task is to be executed.
     * @param period
     *            time in milliseconds between successive task executions.
     *
     * @throws IllegalArgumentException
     *             if time.getTime() is negative.
     * @throws IllegalStateException
     *             if task was already scheduled or canceled, timer was canceled, or
     *             timer thread terminated.
     */
    public void scheduleAtFixedRate(TimerTask task, Date firstTime, long period) {
        throw new RuntimeException();
    }

    /**
     * Terminates this timer, discarding any currently scheduled tasks. Does not
     * interfere with a currently executing task (if it exists). Once a timer has
     * been terminated, its execution thread terminates gracefully, and no more
     * tasks may be scheduled on it.
     *
     * Note that calling this method from within the run method of a timer task that
     * was invoked by this timer absolutely guarantees that the ongoing task
     * execution is the last task execution that will ever be performed by this
     * timer.
     */
    public void cancel() {
        throw new RuntimeException();
    }

    /**
     * Executes {@link TimerTask} scheduling. This method must be called only for
     * {@link Timer} that are not automatic (i.e. no thread is automatically started
     * at {@link Timer} creation). This is the current thread that executes the
     * {@link Timer} scheduling loop.
     * <p>
     * This method can be called once on this {@link Timer} and returns only if
     * {@link #cancel()} is called.
     *
     * @throws IllegalStateException
     *             if this timer is already running or canceled.
     */
    public void run() {
        throw new RuntimeException();
    }

    /**
     * Sets the default handler for uncaught exceptions.
     *
     * @param h
     *            the new default handler, or <code>null</code> to remove the
     *            default {@link Timer} class handler.
     *
     * @throws SecurityException
     *             if a security manager exists and it denies
     *             <tt>{@link RuntimePermission}
     *         (&quot;setDefaultUncaughtExceptionHandler&quot;)</tt>
     *
     * @see #setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler)
     * @see TimerTask#uncaughtException(Timer, Throwable)
     */
    public static void setDefaultUncaughtExceptionHandler(@Nullable UncaughtExceptionHandler h) {
        throw new RuntimeException();
    }

    /**
     * Gets the default registered handler for uncaught exceptions.
     *
     * @return the default handler, or <code>null</code> if there is no default
     *         handler registered.
     * @see #setDefaultUncaughtExceptionHandler(Thread.UncaughtExceptionHandler)
     * @see TimerTask#uncaughtException(Timer, Throwable)
     */
    @Nullable
    public static UncaughtExceptionHandler getDefaultUncaughtExceptionHandler() {
        throw new RuntimeException();
    }

    /**
     * Sets the specific handler for uncaught exceptions on this {@link Timer}
     * instance.
     *
     * @param h
     *            the new handler, or <code>null</code> to remove the specific
     *            {@link Timer} handler.
     *
     * @see #setDefaultUncaughtExceptionHandler(Thread.UncaughtExceptionHandler)
     * @see TimerTask#uncaughtException(Timer, Throwable)
     */
    public void setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler h) {
        throw new RuntimeException();
    }

    /**
     * Gets the specific handler for uncaught exceptions on this {@link Timer}
     * instance.
     *
     * @return the handler, or <code>null</code> if there no registered handler.
     * @see TimerTask#uncaughtException(Timer, Throwable)
     */
    @Nullable
    public Thread.UncaughtExceptionHandler getUncaughtExceptionHandler() {
        throw new RuntimeException();
    }

    /**
     * Prints a status of this timer and its scheduled tasks to the specified print
     * stream. This method is used only for debugging.
     *
     * @param s
     *        {@code PrintStream} to use for output.
     */
    public void dump(PrintStream s) {
        throw new RuntimeException();
    }
}