001package jmri;
002
003import java.beans.PropertyChangeListener;
004import java.util.concurrent.Callable;
005
006/**
007 * Execute a specific task before the program terminates.
008 * <p>
009 * Tasks should leave the system in a state that can continue, in case a later
010 * task aborts the shutdown.
011 * <p>
012 * A ShutDownTask can listen to the "shuttingDown" property of the
013 * {@link ShutDownManager} to determine if any other ShutDownTask aborted the
014 * shutdown; the property will change from false to true in that case.
015 *
016 * @author Bob Jacobsen Copyright (C) 2008
017 */
018public interface ShutDownTask extends Callable<Boolean>, Runnable, PropertyChangeListener {
019
020    /**
021     * Ask if shut down is allowed.
022     * <p>
023     * The shut down manager must call this method first on all the tasks before
024     * starting to execute the method execute() on the tasks.
025     * <p>
026     * If this method returns false on any task, the shut down process must be
027     * aborted.
028     *
029     * @return true if it is OK to shut down, false to abort shut down.
030     * @deprecated since 4.21.1; use {@link #call()} instead
031     */
032    @Deprecated
033    public boolean isShutdownAllowed();
034
035    /**
036     * Ask if shut down is allowed.
037     * <p>
038     * The shut down manager calls this method first on all the tasks before
039     * starting to execute the method {@link #run()} on the tasks.
040     * <p>
041     * If this method returns false on any task, the shut down process must be
042     * aborted.
043     *
044     * @return true if it is OK to shut down, false to abort shut down.
045     * @throws Exception if there is an exception
046     */
047    @Override
048    public Boolean call() throws Exception;
049
050    /**
051     * Take the necessary action.
052     * <p>
053     * If the task is lengthy and can easily confirm that it should proceed
054     * (i.e., prompt the user to save, not save, or cancel shutting down), and
055     * spin itself off into a new thread, it should do so.
056     * <p>
057     * <strong>Note</strong> if a task is parallel, this method should return
058     * <em>after</em> any tests that might cause the shutdown to be aborted.
059     *
060     * @return true if the shutdown should continue, false to abort.
061     * @deprecated since 4.21.1; use {@link #run()} instead
062     */
063    @Deprecated
064    public boolean execute();
065
066    /**
067     * Take the necessary action. This method cannot abort the shutdown, and
068     * must not require user interaction to complete successfully. This method
069     * will be run in parallel to other ShutDownTasks.
070     */
071    @Override
072    public void run();
073
074    /**
075     * Name to be provided to the user when information about this task is
076     * presented.
077     *
078     * @return the name
079     */
080    public String getName();
081
082    /**
083     * Advise {@link jmri.ShutDownManager}s if {@link #execute()} may return
084     * before the task is complete.
085     * <p>
086     * <strong>Note</strong> if a task is parallel, {@link #execute()} should
087     * return <em>after</em> any tests that might cause the shutdown to be
088     * aborted.
089     *
090     * @return true if the task is run within its own Thread
091     * @deprecated since 4.21.1; this is ignored and all tasks are run in an
092     * independent Thread
093     */
094    @Deprecated
095    public boolean isParallel();
096
097    /**
098     * Advise {@link jmri.ShutDownManager}s that the task is complete.
099     *
100     * @return true if the task is complete
101     * @deprecated since 4.21.1; this is ignored as all tasks are run in an
102     * independent Thread that is independently monitored
103     */
104    @Deprecated
105    public boolean isComplete();
106}