ProgressMonitor defines a set of methods that are useful for
keeping track of the progress of an operation. This interface also allows
the operation being tracked to be notified if the user wishes to cancel the
operation. Code using this interface to track progress should call
{@link #isCancelled()} prior to calling {@link #setTaskProgress(long)}.
Implementations of this interface should throw an
IllegalArgumentException when setTaskProgress(int)
is called after the operation has been cancelled.
Code using the ProgressMonitor should call {@link #started()}
before setTaskProgress(long) is called for the first time.
setTaskProgress() should not be called after
cancel() or finished() has been called. Therefore,
monitored processes should check isCancelled() before setTaskProgress(long)
is called. An
implementation may throw an IllegalArgumentException if
setTaskProgress(int) is called before started() or
after finished() is called. Note if isCancelled is not called
by the process, then the cancel button will become disabled.
TODO: consider allowing the client to specify that an unchecked exception is allowed, and he can then catch the exception. 1. The caller knows that the service provider's work can be ignored, and this would work. 2. The service provider knows that the service must be cleaned up with a try/finally block. Should CancelledOperationException be a an unchecked exception? See https://bugs-pw.physics.uiowa.edu/mantis/view.php?id=457
A client codes receiving a monitor must do one of two things. It should either call setTaskSize(long), started(), setTaskProgress(long) zero or more times, then finished(); or it should do nothing with the monitor, possibly passing the monitor to a subprocess. This is to ensure that it's easy to see that the monitor lifecycle is properly performed.