ShowTable of Contents
In contrast to real
JavaScript background jobs which run completely separated from an XPages application and go on running even if the XPages application is closed, a
Monitoring Job is a job that does nothing but monitor and visualize the progress of server-side JavaScript code, e.g. executed when a user clicks on a button in an XPage.
The purpose is both to give the user visual feedback about the execution progress, e.g. in a progress dialog, and to offer a way to cancel a long running background operation. Since your code is running in a normal Ajax request, you've got full access to the scope maps (e.g. applicationScope, sessionScope) and you can use the @formula methods that IBM provides in their JavaScript engine.
Job progress dialog
You create a new Monitoring Job by calling the method createMonitoringJob(String) of the Jobs API tools class with the preferred Job name (which will be visible in the title of the progress dialog):
var conn=X2E.createConnection();
var jTools=com.x2e.JobAPI.getTools(conn);
//a monitoring job does not execute any code itself, but is used
//to display progress in the Notes client; its only purpose is
//to monitor calls on its progress monitor and pass them to Eclipse
var job=jTools.createMonitoringJob(jobName);
//optional call to display a progress dialog (otherwise, the progress would only be visible on the Job progress page of the Notes Client):
job.setUser(true);
There are two methods to influence the visibility of the job in the Notes Client. Calling job.setUser(true) will display a job progress dialog, otherwise the job will only be visible in the Job tab. And by calling job.setSystem(true), you can further reduce the job visibility so that it only shows up in the Job tab, when the option "Show sleeping and system operations" is checked in the Job tab preferences:
Next, you read the so called Progress Monitor from the job by calling the method job.getProgressMonitor(). The Progress Monitor will be used in your code to report the current progress to the Monitoring Job, provide a status message and to check if the user has pressed the cancel button.
As the final step before we can enter a long running code block, we launch the Monitoring Job by calling job.schedule(), which makes the job appear in the Notes client.
var progressMon=job.getProgressMonitor();
job.schedule();
Notify Monitoring Job about execution progress
Now that the Monitoring Job is running, your code can enter a long running loop. We are using the
progressMon object to keep the Monitoring Job informed about the current status:
//announce a new task; -1 means that we don't know exactly how many work units need to be processed, which makes the progress bar flash back und forth
progressMon.beginTask("Opening view", -1);
var nrOfEntries=openView();
//change the task name and tell the progress monitor that nrOfEntries work units need to be processed
progressMon.beginTask("Processing entries", nrOfEntries);
for (var i=0; i<nrOfEntries; i++) {
//check if the user has canceled the operation
if (progressMon.isCanceled())
break;
processViewEntry(i);
//report 1 work unit as processed; updates the progress bar to the current progress
progressMon.worked(1);
}
//Notify that we are done and the Monitoring job can be stopped and hidden
progressMon.done();
In the code snippet above you see most of the available methods in the Progress Monitor class used. Further information can be found in the
Eclipse documentation for IProgressMonitor
, which is the Eclipse object that XPages2Eclipse uses internally.