Long running jobs (those lasting more than a second) should report progress to the IProgressMonitor passed to the
job's run method. The workbench progress view will
show all progress messages and units of completed work given
to this monitor. The supplied progress monitor is also used to respond to
cancelation requests made from the progress view. When a user
(or plug-in) attempts to cancel a job, the method IProgressMonitor.isCanceled
will return true. When this occurs, it is the job's responsibility to
respond to the cancelation by exiting the run method as soon as possible.
Here is a sample run method from a job that reports progress and responds
to cancelation:
public IStatus run(IProgressMonitor monitor) {
final int ticks = 6000;
monitor.beginTask("Doing some work", ticks);
try {
for (int i = 0; i < ticks; i++) {
if (monitor.isCanceled())
return Status.CANCEL_STATUS;
monitor.subTask("Processing tick #" + i);
//... do some work ...
monitor.worked(1);
}
} finally {
monitor.done();
}
return Status.OK_STATUS;
}
In the progress view, the string supplied to beginTask will appear
after the job name, and the subTask messages will appear as
a child in the progress tree. The progress view will calculate and display a
percent completion based on the number of worked calls that
have occurred. Here is a snapshot of the progress view while the above
job is running:
If your job is an implementation detail that you do not want to show to users,
you can flag your job as a system job. A system job is just like any
other job, except it does not appear in the progress view or cause the progress
busy indicator in the status line to animate. If your job is not either directly
initiated by a user, or a periodic task that can be configured by a user, then your
job should be a system job. Making your job a system job is easy as pie:
class TrivialJob extends Job {
public TrivialJob() {
super("Trivial Job");
setSystem(true);
}
...
}
[The remainder of this document is under construction]
Other topics to be covered in this section: