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}