001package jmri;
002
003import java.util.List;
004
005import java.util.concurrent.Callable;
006import javax.annotation.Nonnull;
007import javax.annotation.CheckForNull;
008import jmri.beans.PropertyChangeProvider;
009
010/**
011 * Manage tasks to be completed when the program shuts down normally.
012 * <p>
013 * Implementations of this interface allow other objects to register and
014 * deregister {@link ShutDownTask} objects, which are invoked in an orderly way
015 * when the program is is commanded to terminate. There is no requirement a
016 * ShutDownTask not interact with the user interface, and an assumption that,
017 * barring a headless application, that ShutDownTasks may interact with the user
018 * interface.
019 * <p>
020 * There can only be one instance of this operating, and it is generally
021 * obtained via the instance manager.
022 * <p>
023 * ShutDownTasks should leave the system in a state that can continue, in case a
024 * later task aborts the shutdown.
025 * <p>
026 * An instance of this is normally obtained from the instance manager, using may
027 * assume that one is always present.
028 *
029 * @author Bob Jacobsen Copyright (C) 2008
030 */
031public interface ShutDownManager extends PropertyChangeProvider {
032
033    /**
034     * Register a task object for later execution. An attempt to register an
035     * already registered task will be silently ignored.
036     *
037     * @param task the task to execute
038     * @throws NullPointerException if the task is null
039     */
040    void register(@Nonnull ShutDownTask task);
041
042    /**
043     * Register a task for verification that JMRI should stop. An attempt to
044     * register an already register task will be silently ignored.
045     *
046     * @param task the verification task
047     * @throws NullPointerException if the task is null
048     */
049    void register(@Nonnull Callable<Boolean> task);
050
051    /**
052     * Register a task that runs when JMRI is stopping. An attempt to
053     * register an already register task will be silently ignored.
054     *
055     * @param task the execution task
056     * @throws NullPointerException if the task is null
057     */
058    void register(@Nonnull Runnable task);
059
060    /**
061     * Deregister a task. Attempts to deregister a task that is not
062     * registered are silently ignored.
063     *
064     * @param task the task not to execute
065     */
066    void deregister(@CheckForNull ShutDownTask task);
067
068    /**
069     * Deregister a task. Attempts to deregister a task that is not
070     * registered are silently ignored.
071     *
072     * @param task the task not to call
073     */
074    void deregister(@CheckForNull Callable<Boolean> task);
075
076    /**
077     * Deregister a task. Attempts to deregister a task that is not
078     * registered are silently ignored.
079     *
080     * @param task the task not to run
081     */
082    void deregister(@CheckForNull Runnable task);
083
084    @Nonnull
085    List<Callable<Boolean>> getCallables();
086
087    @Nonnull
088    List<Runnable> getRunnables();
089
090    /**
091     * Run the shutdown tasks, and then terminate the program with status 210 if
092     * not aborted. Does not return under normal circumstances. Returns false if
093     * the shutdown was aborted by the user, in which case the program should
094     * continue to operate.
095     * <p>
096     * By exiting the program with status 210, the batch file (MS Windows) or
097     * shell script (Linux/macOS/UNIX) can catch the exit status and tell the
098     * operating system to restart.
099     */
100    void restartOS();
101
102    /**
103     * Run the shutdown tasks, and then terminate the program with status 100 if
104     * not aborted. Does not return under normal circumstances. Returns false if
105     * the shutdown was aborted by the user, in which case the program should
106     * continue to operate.
107     * <p>
108     * By exiting the program with status 100, the batch file (MS Windows) or
109     * shell script (Linux/macOS/UNIX) can catch the exit status and restart the
110     * JMRI java program.
111     */
112    void restart();
113
114    /**
115     * Run the shutdown tasks, and then terminate the program with status 200 if
116     * not aborted. Does not return under normal circumstances. Returns false if
117     * the shutdown was aborted by the user, in which case the program should
118     * continue to operate.
119     * <p>
120     * By exiting the program with status 200, the batch file (MS Windows) or
121     * shell script (Linux/macOS/UNIX) can catch the exit status and shutdown the OS
122     */
123    void shutdownOS();
124
125    /**
126     * Run the shutdown tasks, and then terminate the program with status 0 if
127     * not aborted. Does not return under normal circumstances. Returns false if
128     * the shutdown was aborted by the user, in which case the program should
129     * continue to operate.
130     */
131    void shutdown();
132
133    /**
134     * Allow components that normally request confirmation to shutdown to
135     * determine if the shutdown is already underway so as not to request
136     * confirmation.
137     *
138     * @return true if shutting down or restarting
139     */
140    boolean isShuttingDown();
141}