ProgressMonitor.java

// License: GPL. For details, see LICENSE file.
package org.openstreetmap.josm.gui.progress;

import java.awt.Component;

/**
 * Typical use case is:
 * <pre>
 *   monitor.beginTask()
 *   try {
 *     .. do some work
 *     monitor.worked()
 *     monitor.subTask()/monitor.intermediateTask()
 *     .. do some work
 *     monitor.worked()
 *   } finally {
 *     monitor.finishTask();
 *   }
 * </pre>
 *
 * {@link #subTask(String)} and {@link #indeterminateSubTask(String)} has nothing to do with logical
 * structure of the work, they just show task title to the user.
 *
 * If task consists of multiple tasks then {@link #createSubTaskMonitor(int, boolean)} may be used. It
 * will create new ProgressMonitor, then can be passed to the subtask. Subtask doesn't know whether
 * it runs standalone or as a part of other task. Progressbar will be updated so that total progress is
 * shown, not just progress of the subtask
 *
 * All ProgressMonitor implementations should be thread safe.
 *
 */
public interface ProgressMonitor {

    @FunctionalInterface
    interface CancelListener {
        void operationCanceled();
    }

    /** Ticks count used, when no other value is supplied */
    int DEFAULT_TICKS = 10_000;

    /**
     * Can be used with {@link #worked(int)} and {@link #createSubTaskMonitor(int, boolean)} to
     * express that the task should use all remaining ticks
     */
    int ALL_TICKS = -1;

    /**
     * Starts this progress monitor. Must be called exactly once
     * Ticks count is set to default value
     * @param title title text of the task
     */
    void beginTask(String title);

    /**
     * Starts this progress monitor. Must be called exactly once
     * @param title title text of the task
     * @param ticks number of work units (see {@link #setTicksCount(int ticks)})
     */
    void beginTask(String title, int ticks);

    /**
     * Finish this progress monitor, close the dialog or inform the parent progress monitor
     * that it can continue with other tasks. Must be called at least once (if called multiply times
     * then further calls are ignored)
     */
    void finishTask();

    /**
     * Can be used if method receive ProgressMonitor but it's not interested progress monitoring.
     * Basically replaces {@link #beginTask(String)} and {@link #finishTask()}
     *
     * This method can be also used in finally section if method expects that some exception
     * might prevent it from passing progressMonitor away. If {@link #beginTask(String)} was
     * already called then this method does nothing.
     */
    void invalidate();

    /**
     * Set the total number of work units
     * @param ticks Number of total work units
     */
    void setTicksCount(int ticks);

    /**
     * Get the total number of work units
     * @return Number of total work units
     */
    int getTicksCount();

    /**
     * Set the current number of work units
     * @param ticks Number of work units already done
     */
    void setTicks(int ticks);

    /**
     * Get the current number of work units
     * @return Number of work units already done
     */
    int getTicks();

    /**
     * Increase number of already done work units by ticks
     * @param ticks number of ticks to add
     */
    void worked(int ticks);

    /**
     * Subtask that will show progress running back and forth
     * @param title Can be {@code null}, in that case task title is not changed
     */
    void indeterminateSubTask(String title);

    /**
     * Normal subtask
     * @param title Can be {@code null}, in that case task title is not changed
     */
    void subTask(String title);

    /**
     * Shows additional text
     * @param text custom text
     */
    void setCustomText(String text);

    /**
     * Show extra text after normal task title. Hack for ProgressInputStream to show number of kB already downloaded
     * @param text extra text
     */
    void setExtraText(String text);

    /**
     * Creates subtasks monitor.
     * @param ticks Number of work units that should be done when subtask finishes
     * @param internal If true then subtask can't modify task title/custom text
     * @return subtasks monitor
     */
    ProgressMonitor createSubTaskMonitor(int ticks, boolean internal);

    /**
     * Returns the state of user aborts
     * @return {@code true} if user aborted operation
     */
    boolean isCanceled();

    /**
     * Abort current operation, usually called when user somehow requested an abort
     */
    void cancel();

    /**
     * Add listener for user abort action
     * @param listener the listener for cancel operation
     */
    void addCancelListener(CancelListener listener);

    /**
     * Remove listener for user abort action
     * @param listener the listener for cancel operation
     */
    void removeCancelListener(CancelListener listener);

    /**
     * Appends a message to the log managed by the progress monitor.
     *
     * @param message the log message. Ignored if null or white space only.
     */
    void appendLogMessage(String message);

    /**
     * Set the task ID of the progress dialog
     * Should be used only by PleaseWaitRunnable. If taskId {@code <> null} then "In background" button will be shown
     * @param taskId the task ID
     */
    void setProgressTaskId(ProgressTaskId taskId);

    /**
     * Returns the task ID of the progress dialog
     * Should be used only by PleaseWaitRunnable
     * @return the task ID
     */
    ProgressTaskId getProgressTaskId();

    /**
     * Return the parent windows of progress dialog
     * @return component suitable as parent for dialogs that wants to be shown in front of progress dialog
     */
    Component getWindowParent();
}