001    /*
002     * Copyright 2002-2006 the original author or authors.
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005     * use this file except in compliance with the License. You may obtain a copy of
006     * the License at
007     * 
008     * http://www.apache.org/licenses/LICENSE-2.0
009     * 
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012     * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013     * License for the specific language governing permissions and limitations under
014     * the License.
015     */
016    package org.springframework.richclient.progress;
017    
018    /**
019     * A interface for monitoring task progress.
020     * 
021     * @author Keith Donald
022     */
023    public interface ProgressMonitor {
024    
025        /**
026         * Notifies that the main task is beginning.
027         * 
028         * @param name
029         *            the name (or description) of the main task
030         * @param totalWork
031         *            the total number of work units into which the main task is
032         *            been subdivided. If the value is 0 or UNKNOWN the
033         *            implemenation is free to indicate progress in a way which
034         *            doesn't require the total number of work units in advance. In
035         *            general users should use the UNKNOWN value if they don't know
036         *            the total amount of work units.
037         */
038        public void taskStarted(String name, int totalWork);
039    
040        /**
041         * Notifies that a subtask of the main task is beginning. Subtasks are
042         * optional; the main task might not have subtasks.
043         * 
044         * @param name
045         *            the name (or description) of the subtask
046         */
047        public void subTaskStarted(String name);
048    
049        /**
050         * Notifies that a percentage of the work has been completed. This is called
051         * by clients when the work is performed and is used to update the progress
052         * monitor.
053         * 
054         * @param work
055         *            the percentage complete (0..100)
056         */
057        public void worked(int work);
058    
059        /**
060         * Notifies that the work is done; that is, either the main task is
061         * completed or the user cancelled it.
062         * 
063         * done() can be called more than once; an implementation should be prepared
064         * to handle this case.
065         */
066        public void done();
067    
068        /**
069         * Returns true if the user does some UI action to cancel this operation.
070         * (like hitting the Cancel button on the progress dialog). The long running
071         * operation typically polls isCanceled().
072         */
073        public boolean isCanceled();
074    
075        /**
076         * Attempts to cancel the monitored task.
077         */
078        public void setCanceled(boolean b);
079    
080    }