Adding an IAction to a Job

How do you show the partial results of a background job that is not yet completed? Quick answer is by adding an Action to that Job. The long answer is this tip.

The Progress view shows all the jobs that are scheduled. It also shows the progress bar which is updated with the amount of work done. Consider this snippet:

Job job = new Job("My Job") {
    @Override
    protected IStatus run(IProgressMonitor monitor) {
        monitor.beginTask("My job is working...", 100);
        for (int i = 0; i < 100; i++) {
            try {
                Thread.sleep(200);
            } catch (InterruptedException e) {} // ignore
            monitor.worked(1);
        }
        monitor.done();
        return new Status(IStatus.OK, Activator.PLUGIN_ID, "Job finished");
    }

};
job.schedule();

The Progress view shows this job like this:

 

Jobs allow user defined key-value pair properties to be set on them. The key would be QualifiedName and the value will be any Object. The Progress view identifies certain properties set on the job and acts accordingly. One of the properties is IProgressConstants.ACTION_PROPERTY. The value should be an IAction.

job.setProperty(IProgressConstants.ACTION_PROPERTY, new Action() {
    @Override
    public void run() {
        MessageDialog.openInformation(new Shell(), "Job Status", "Some partial results processed can be displayed here");    
        }
    });
}

When you set an action on a job as above, the Progress view finds it and gives you the visual hint:

The progress text becomes a hyperlink. When you click on it, the associated action will be executed. You can probably open up a dialog with the results of the job which is completed so far.

As soon as the job is over, the Progress view removes it from the view. Is there a way to reuse this same action to show the complete set of results even after the job is finished? Yes. The Progress view understands another property called IProgressConstants.KEEP_PROPERTY. Its a boolean property, and when its set, the Job stays in the Progress view even after its finished.

job.setProperty(IProgressConstants.KEEP_PROPERTY, true);

Since the ProgressMonitor is done, the text for the hyperlink is now taken from the IStatus that is returned from the Job.

All is fine when the job finishes normally. But what if the return status is an error? Progress view opens up a Dialog and shows you the status. It might be intrusive sometimes. Is there a way to suppress the dialog so that the user can go back to the Progress view and check the status? Again Yes. Just set the boolean property IProgressConstants.NO_IMMEDIATE_ERROR_PROMPT_PROPERTY, there won't be any dialogs. The Progress view icon in the status bar will indicate the user that some job did not complete normally. When the user clicks on the job, can reuse the same action to display what went wrong.

job.setProperty(IProgressConstants.NO_IMMEDIATE_ERROR_PROMPT_PROPERTY, true);

 
Did you see the other job in the above pictures? It has a nice looking icon. So how do we associate an icon with our job? Yes, what you think is right. The Progress view also understands an another property IProgressConstants.ICON_PROPERTY thru which you can set your icon:

job.setProperty(IProgressConstants.ICON_PROPERTY, getJobImageDescriptor());

There you go:

Next time you create a long running background job, consider setting these properties.

Update [28-Oct-09]: Starting from 3.6 M3, you can now associate a Command also