Reporting and listening to progress

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:

Job progress view

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:

Copyright IBM Corporation and others 2000, 2003.