001package co.codewizards.cloudstore.core.progress;
002
003/**
004 * Interface to report the progress of an activity.
005 * This is used like org.eclipse.core.runtime.IProgressMonitor.
006 *
007 * @author Alexander Bieber <!-- alex [AT] nightlabs [DOT] de -->
008 */
009public interface ProgressMonitor {
010
011        /**
012         * Notifies that the main task is beginning.  This must only be called once
013         * on a given progress monitor instance.
014         *
015         * @param name the name (or description) of the main task
016         * @param totalWork the total number of work units into which
017         *  the main task is been subdivided. If the value is <code>UNKNOWN</code>
018         *  the implementation is free to indicate progress in a way which
019         *  doesn't require the total number of work units in advance.
020         */
021        public void beginTask(String name, int totalWork);
022
023        /**
024         * Notifies that the work is done; that is, either the main task is completed
025         * or the user canceled it. This method may be called more than once
026         * (implementations should be prepared to handle this case).
027         */
028        public void done();
029
030        /**
031         * Returns whether cancelation of current operation has been requested.
032         * Long-running operations should poll to see if cancelation
033         * has been requested.
034         * <p>
035         * If this is <code>true</code>, the long-running operation should
036         * throw an {@link OperationCanceledException}.
037         * </p>
038         *
039         * @return <code>true</code> if cancellation has been requested,
040         *    and <code>false</code> otherwise
041         * @see #setCanceled(boolean)
042         */
043        public boolean isCanceled();
044
045        /**
046         * Sets the cancel state to the given value.
047         *
048         * @param canceled <code>true</code> indicates that cancelation has
049         *     been requested (but not necessarily acknowledged);
050         *     <code>false</code> clears this flag
051         * @see #isCanceled()
052         */
053        public void setCanceled(boolean canceled);
054
055        /**
056         * Internal method to handle scaling correctly. This method
057         * must not be called by a client. Clients should
058         * always use the method </code>worked(int)</code>.
059         * <p>
060         * Note: EclipseRCP is strange!
061         *
062         * @param worked the amount of work done
063         */
064        public void internalWorked(double worked);
065
066        /**
067         * Sets the task name to the given value. This method is used to
068         * restore the task label after a nested operation was executed.
069         * Normally there is no need for clients to call this method.
070         *
071         * @param name the name (or description) of the main task
072         * @see #beginTask(java.lang.String, int)
073         */
074        public void setTaskName(String name);
075
076        /**
077         * Notifies that a subtask of the main task is beginning.
078         * Subtasks are optional; the main task might not have subtasks.
079         *
080         * @param name the name (or description) of the subtask
081         */
082        public void subTask(String name);
083
084        /**
085         * Notifies that a given number of work unit of the main task
086         * has been completed. Note that this amount represents an
087         * installment, as opposed to a cumulative amount of work done
088         * to date.
089         *
090         * @param work the number of work units just completed
091         */
092        public void worked(int work);
093}