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.
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.
return true if the process appears to support cancel. Many processes use a monitor to provide status feedback, but do not check if the human operator has pressed cancel.
Notifies the ProgressMonitor that the task
being monitored should be canceled. After this method is
called, implementations should return true on
any subsequent calls to {@link #isCancelled()} and should
throw an IllegalStateException on any subsequent calls to
{@link #setTaskProgress(long)}.
Notifies the ProgressMonitor that the task
being monitored has finished. This must only be called once, and note that isFinished() must return
the state of this monitor.
Return the label string displayed, which is a concise string that describes the task being performed. This is primarily to aid in debugging, and this method need not return the string set by setLabel.
return a monitor to use for a subtask. This is provided mostly as a convenience. setTaskProgress calls to the subtask monitor are mapped to this monitor. A label can also be specified for the subtask to improve user experience. If the parent process is not supporting cancel, then subprocesses cannot support cancel.
Returns the current progress of the monitored task.
Return the size of the task. The units are arbitrary
Returns true if the operation being tracked
should be cancelled. For example, the human operator has pressed
the cancel button indicating that the process should be stopped. Note
that if the process is not checking the cancel status, the cancel button
should be disabled.
true if the operation being tracked
should be cancelled.
true if the process has indicated that it is finished
true if the process has indicated that it has started.
Set a concise string that describes the task being performed. Monitors don't necessarily need to display this label, and this request may be ignored. It is only provided so a process can describe the task that is going on. This is usually set by the client of the process to indicate what service we are waiting for. e.g. "Loading Data"
Provides additional feedback as to what's going on in the process. This message should be set by the service provider, not the client, and refer to the implementation of the task. e.g. "Reading file myData.dat"
Notifies the ProgressMonitor of a change in the progress of the task.
Sets the maximum value for the task progress of this
ProgressMonitor.
Notifies the ProgressMonitor that the task
being monitored has started. If the ProgressMonitor
is in a cancelled state when this method is called, that
ProgressMonitor should be 'uncancelled'.