E4/Doc/Reporting Progress

THIS IS OLD DOCUMENTATION THAT DOES NOT FOLLOW THE NEW FORMAT AND HAS NOT HAD THE "SERVICE INTERVIEW" PERFORMED YET

Under Construction: Please read first!

The evolution of this document is a collaborative effort between a team of students at the University of Manitoba and the wider Eclipse community. Details about the project can be found here and on our Blog.

Your input is not just welcome; it is needed! Please contribute as your expertise allows, while adhering to our template. To send your feedback and any questions or comments you may have please email us. Also, while we do our very best to be as accurate and precise as possible, it is worth noting that we are students with limited exposure to the Eclipse platform, so if you see any incorrect technical details please let us know.

Description

It is often useful to report the progress of a job. As the name implies, progress reporting tracks and displays the completion of a job. Although many background tasks do not require progress reporting, user-initiated tasks are often good candidates for this service. A progress monitor gives a user something to watch while a task completes, and it provides a means by which a user can cancel a long-running operation.

Consumer

Progress reporting is not yet implemented in e4, but plans exist for a simplification of the service. In Eclipse 3.x, the API for progress reporting provides a poor separation of concerns. The same code that invokes actual 'work' and updates an IProgressMonitor must also be concerned with the context in which progress reporting is occurring. This context could be a Job (for display in the Progress View), an IRunnableWithProgress (for display in a wizard), or some other custom solution.

In e4, the goal is to separate this running context from the logic that invoke work and updates the progress monitor.

Usage

Several implementations of progress monitoring have been proposed in e4.

Code Samples

Java

In this proposed implementation, an object with the ability to run a monitored job is injected with a StatusHandler and a RunnableContext. The RunnableContext provides an IProgressMonitor, and the StatusHandler is used to report errors.

@Inject Provider<StatusHandler> statusHandler;
@Inject Provider<RunnableContext> runnableContext;
IRunnable runnable = new Runnable("My long-running operation...") {
  protected IStatus run() {
    IProgressMonitor monitor = runnableContext.get().getProgressMonitor();
    monitor.beginTask("foo", 100);
    try {
       doFirstHalfFoo();
       monitor.worked(50);
       doSecondHalfFoo();
    } catch (FooException e) {
       statusHandler.get().handle(e, "foo failure message", runnableContext.get().getStatusReportingService()); 
    } finally {
       monitor.done();
    }
  }
};
runnableContext.get().run(runnable);

Eclipse 3.x

Java

In this example, progress is reported both in the Progress View and in another programmer-defined location. In addition, errors are reported locally. The example illustrates the complexity of customized progress reporting in Eclipse 3.x.

Job aJob = new Job("My long-running operation...") {
  protected IStatus run(IProgressMonitor monitor) {
    IStatus status = Status.OK_STATUS;
    IProgressMonitor wrappedMonitor = new ProgressMonitorWrapper(monitor) {
       // override everything so that you can report it locally, too
        public void beginTask(String name, int totalWork) {
		super.beginTask(name, totalWork);
                someLocalMonitor.beginTask(name, totalWork);
	}
    };
    wrappedMonitor.beginTask("foo", 100);
    try {
       doFirstHalfFoo();
       wrappedMonitor.worked(50);
       doSecondHalfFoo();
    } catch (FooException e) {
       status = new Status(IStatus.ERROR, "id", "foo failure message", e);
    } finally {
       wrappedMonitor.done();
    }
    return status;  }
};
// true to indicate that this job was initiated by a UI end user
aJob.setUser(true);
// don't report errors in a separate dialog
aJob.setProperty(IProgressConstants.NO_IMMEDIATE_ERROR_PROMPT_PROPERTY, Boolean.TRUE);
// report errors the way I want to
aJob.addJobListener(new JobChangeAdapter() {
  public void done(JobChangeEvent event) {
    if (!status.isOK()) {
      updateStatus(event.getResult());
    }
  }
});

Producer

e4 specific description of the service/ implementation details etc.

Usage

Code Samples

Eclipse 3.x

(this is not likely needed here)

Related Materials

Related Services

Related API's

See Also