Using the Lotus Expeditor Progress Monitor

A neat way of instrumenting a longer running task in a Lotus Expeditor/Eclipse RCP environment is to use the Progress Monitor feature. This allows the progress of the task in hand to be monitored by the user using a progress bar and descriptive text for each step in the process. The user can then choose to minimise this monitor to the status bar or indeed show/hide the amount of detail displayed. Furthermore, the UI construct also allows the user to cancel the task, should they choose to do so. In the following example, the Progress Monitor can be seen behind the modal dialog box complete with progress bar, Run in Background, Cancel and Details >> buttons.

image

The purpose of this utility was to send a JMS message via the micro broker to a WebSphere Process Server process and receive the response. Each step of the process is displayed using the Expeditor Progress Monitor. There are a number of snippets in this utility (as well as this pattern of unit testing) that might be of general use elsewhere.

Creating a unit of work to be instrumented

Core to the concept of using the Progress Monitor is the Eclipse Jobs APIs. Eclipse defines an abstract Job super-class sub-classes of which implement the work to be done. The sub-class is passed an IProgressMonitor instance that provides the mechanism for updating the status text and progress on the UI. The application specifies an integer number representing the whole unit of work such that the progress meter can accurately reflect the proportion of work done and left to do.

Job job = new Job("Sending a test message via JMS...") {
   protected IStatus run(IProgressMonitor monitor) {
      monitor.beginTask("Creating JMS objects...", 5);
      monitor.worked(0);
      monitor.setTaskName("Connecting to the micro broker and creating a session...");
      ...
      monitor.worked(1);
      ...
      if(monitor.isCanceled()) {
         return Status.CANCEL_STATUS;
      } else {
         return Status.OK_STATUS;
      }
   }
};

In this case we have 5 steps so when we signal our intent of starting the work with beginTask we signal 5 as the total amount of “work” to be done. Each time a piece of work is completed, the worked method allows us to signal how far through the total amount of work we have progressed. In this case this is the step number i.e. 1 of 5, 2 of 5 and so on. The UI will then reflect this accordingly on the progress bar. Notice that the Job class knows nothing about the UI representation, we are hidden behind the IProgressMonitor. To execute the Job therefore, we will need to hitch it onto the UI.

Connecting the Job to the UI and kicking it off

Eclipse provides a very simple API for applications to hitch a given Job onto the Workbench Progress Monitor (i.e. the one shown above).

PlatformUI.getWorkbench().getProgressService().showInDialog(Display.getCurrent().getActiveShell(), job);

Finally all that remains is for us to kick off the job which is done using the inherited schedule method.

job.schedule();

Threading with the UI

Note that the above example uses the Job superclass which is not executed on the UI thread. In this way, any activity within run that blocks will not block the UI thread. However, you will need to use Display.asyncExec to do any UI related operations. An alternative superclass is provided within Eclipse called UIJob for work that specifically needs to be run on the UI thread. Note however that blocking in this kind of job will block (i.e. freeze) the UI.

Advertisements

2 responses to “Using the Lotus Expeditor Progress Monitor

  1. Martin, what a brilliant piece of work. I can go have a cuppa and my phone’ll vibrate when my computer has finished extracting a large piece of code, downloading a new release, or installing a product.

    Look forward to seeing more knowledge posts from you.

    Ben

    • Thanks Ben, glad you found it useful. It was one of those things that always looked slick on the UI but I’d never written down before.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s