Recently I had to learn a little bit about how to report the progress of an operation. I mean this component which is shown below and which you possibly very often see while using Eclipse:
Never before I had to take care about this, so I knew only that, there were some progress monitors, which I had to pass to some methods. I started digging into the web and found two very good articles:
How to Correctly and Uniformly Use Progress Monitors and
FAQ How do I use progress monitors? . Both documents contain very useful information and give nice examples. However, these two papers describe the approach in which class
SubProgressMonitor is used. This solution is good, but why use good solution, when better one can be used? Since Eclipse 3.3 class
SubMonitor is available (in the project
org.eclipse.equinox.common in package
org.eclipse.core.runtime) and this is a very good news. Why?
Basically because:
- we don't have to call methods beginTask() and done() on the instance of SubMonitor class
- it is easier now to create submonitors (there is a method newChild(int totalWork))
- in SubMonitor we can find method setWorkRemining() which allows us to redistribute the remaining space on the progress monitor
- SubMonitor protects the caller from common progress reporting bugs in a called method
I was trying to find some information in the Web concerning
SubMonitor, but I failed. Fortunately I found useful info in the javadoc, so I decided to make it more public to make this solution more popular.
First of all we have to convert any other kind of progress monitor into
SubMonitor. This is very easy, because we can use one of two static methods:
public static SubMonitor convert(IProgressMonitor monitor, int work)and
public static SubMonitor convert(IProgressMonitor monitor, String taskName, int work)So after invoking:
SubMonitor progress = SubMonitor.convert(monitor, 100);we can benefit from all the advances of SubMonitor class.
The basic example of using SubMonitor could look like this:
void someOperation(IProgressMonitor monitor) {
// Convertion of the given monitor
SubMonitor progressSubMonitor = SubMonitor.convert(monitor, 100);
// 70% of work is consumed
doSomeWork(progressSubMonitor.newChild(70));
// 30% of work is consumed
progressSubMonitor.worked(30);
}
My main concern about reporting the progress was how to manipulate the number of work items, when some operation will or will not be executed (so when we have a condition). Fortunately with SubMonitor it is pretty easy. The example below shows how to do this:
void someOperation(IProgressMonitor monitor) { SubMonitor progressSubMonitor = SubMonitor.convert(monitor, 100);
if (condition) {
// 50% of work is consumed
doSomeWork(progressSubMonitor.newChild(40));
}
//if there is any work item resumed from the first 40% then use it
progress.setWorkRemaining(40); // the rest of work items is consumed
doSomeWork(progress.newChild(60));
}
It is also easy to handle the loop case:
void someOperation(IProgressMonitor monitor, Collection someCollection) { SubMonitor progressSubMonitor = SubMonitor.convert(monitor, 100);
// Create a new progress monitor that uses 70% of the total progress
SubMonitor loopProgress = progressSubMonitor.newChild(70);
// Allocate one tick for each element of the given collection.
loopProgress.setWorkRemaining(someCollection.size());
for (Iterator iter = someCollection.iterator(); iter.hasNext();) {
Object next = iter.next();
//Do something with the element from collection and
//consume one work item
doSomeWorkOnElement(next, loopProgress.newChild(1));
}
// Use the remaining 30% of the progress monitor to do some work outside
// the loop
doSomeWork(progressSubMonitor .newChild(30));
}
Have fun with using SubMonitor ;-)
