In the BEAM API, progress monitors (com.bc.ceres.core.ProgressMonitor) are used to observe the progress made in long running tasks. Usually they are passed into (abstract) operation whose implementation are expected to take a certain amount of time to return, e.g. data readers, writers, or operators. A common code pattern to use a progress monitor is
public class FilterOp extends Operator { public void computeTile(Band targetBand, Tile targetTile, ProgressMonitor pm) { int totalWork; // Here: compute totalWork pm.beginTask("Applying filter", totalWork); try { for (int i = 0; i < totalWork; i++) { // Here: do the incremental work pm.worked(1); // notify monitor about the work done } } finally { pm.done(); } } }
Note that the actual progress notification pm.worked() is incremental; its parameter is the work units done per step. The sum of work units must be equal to totalWork.
Sometimes the method which uses a progress monitor calls methods which again expect a progress monitor as input, this, providing its own progress monitoring. In this case, the called method provides some sub-progress (com.bc.ceres.core.SubProgressMonitor). For example
public class FilterOp extends Operator { public void computeTile(Band targetBand, Tile targetTile, ProgressMonitor pm) { int totalWork; // Here: compute totalWork pm.beginTask("Applying filter", 20 + totalWork); try { filter.prepare(SubProgressMonitor.create(pm, 20)); for (int i = 0; i < totalWork; i++) { // Here: do the incremental work pm.worked(1); // notify monitor about the work done } } finally { pm.done(); } } }
Note: In the BEAM API, progress monitors never must be null. If sub-progress monitoring is not wanted, a com.bc.ceres.core.NullProgressMonitor (or better ProgressMonitor.NULL) can be used instead.