/*
 * Java
 *
 * Copyright 2010-2024 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.
 * This document has been released and published by E-S-R consortium, a non-profit entity.
 * To learn more about E-S-R consortium, please visit http://www.e-s-r.net/.
 * The matter contained in this document is not subject to copyright; you are free to use it for any purpose, for more information see E-S-R consortium policies.
 */
package ej.microui;

/**
 * The <code>MicroUI</code> class offers basic services in the MicroUI implementation.<br>
 * MicroUI is started explicitly by calling {@link #start()}. MicroUI may also be stopped with {@link #stop()}.
 * <p>
 * MicroUI is using a dedicated thread to read the input events and to manage the display serialized event mechanism.
 * This thread is started when method {@link #start()} is called.
 * <p>
 * This internal thread can call application methods (such as event callback). All exceptions thrown during this peace
 * of code are caught and redirected to the thread uncaught exception handler
 * ({@link Thread#getUncaughtExceptionHandler()}) or to the {@link Thread#getDefaultUncaughtExceptionHandler()} when no
 * specific handler is configured. If no handler is configured, a call to {@link Exception#printStackTrace()} is
 * performed.
 */
public abstract class MicroUI {

    /**
     * Starts MicroUI.<br>
     * It implies starting event serialization as well as rendering mechanisms.<br>
     * This method does nothing if MicroUI is already started.<br>
     *
     * @throws SecurityException
     *             if a security manager exists and does not allow the caller to start MicroUI.
     */
    public static void start() {
        throw new RuntimeException();
    }

    /**
     * Stops MicroUI.<br>
     * It implies stopping any potential event serialization as well as rendering mechanisms.<br>
     * This method does nothing if MicroUI is already stopped.<br>
     *
     * @throws SecurityException
     *             if a security manager exists and does not allow the caller to stop MicroUI.
     */
    public static void stop() {
        throw new RuntimeException();
    }

    /**
     * Checks if MicroUI has been started.<br>
     *
     * @return true when MicroUI is running.
     */
    public static boolean isStarted() {
        throw new RuntimeException();
    }

    /**
     * Gets whether the given thread is the MicroUI thread.
     *
     * @param thread
     *            the thread to check
     *
     * @return <code>true</code> if the given thread is the MicroUI thread, <code>false</code> otherwise.
     * @throws MicroUIException
     *             if MicroUI is not started
     */
    public static boolean isUIThread(Thread thread) {
        throw new RuntimeException();
    }

    /**
     * Gets whether the current thread is the MicroUI thread.
     *
     * @return <code>true</code> if the current thread is the MicroUi thread, <code>false</code> otherwise.
     * @throws MicroUIException
     *             if MicroUI is not started
     */
    public static boolean isUIThread() {
        throw new RuntimeException();
    }

    /**
     * Serializes a call event in the system event stream. When the event is processed, the <code>run()</code> method of
     * the <code>Runnable</code> object is called.<br>
     * Multiple call events may be requested with <code>callSerially()</code>: they will occur in the order in which
     * they were requested (first in first out policy).<br>
     * The call to the <code>run()</code> method of the <code>Runnable</code> object is performed asynchronously
     * Therefore <code>callSerially()</code> will never block waiting for the <code>run()</code> method to finish.<br>
     * The <code>run()</code> method should return quickly, as with other callback methods.<br>
     * The <code>callSerially()</code> mechanism may be used by applications as a synchronization tool in the event
     * stream.
     *
     * @param run
     *            a <code>Runnable</code> object to call
     * @throws MicroUIException
     *             if MicroUI is not started
     */
    public static void callSerially(Runnable run) {
        throw new RuntimeException();
    }
}