org.das2.util.monitor
Interface ProgressMonitor

All Known Implementing Classes:

DasProgressPanel, NullProgressMonitor, SubTaskMonitor

public interface ProgressMonitor

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 isCancelled() prior to calling 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 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.

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.

TODO: check this, I think it's legal now for a process to ignore cancelled, and the monitor should disable the client's ability to cancel in this case. TODO: what about exceptions and the monitor lifecycle?

Field Summary

static ProgressMonitor	NULL Deprecated. this should not be used. Instead use new NullProgressMonitor();
static long	SIZE_INDETERMINATE

Method Summary

void	cancel() Notifies the ProgressMonitor that the task being monitored should be canceled.
void	finished() Notifies the ProgressMonitor that the task being monitored has finished.
java.lang.String	getLabel() Return the label string displayed.
long	getTaskProgress() Returns the current progress of the monitored task.
long	getTaskSize()
boolean	isCancelled() Returns true if the operation being tracked should be cancelled.
boolean	isFinished() true if the process has indicated that it is finished
boolean	isStarted() true if the process has indicated that it has started.
void	setAdditionalInfo(java.lang.String s) Deprecated. setProgressMessage should be used by the service provider to indicate how the process is being implemented.
void	setLabel(java.lang.String label) Set a consise string that describes the task being performed.
void	setProgressMessage(java.lang.String message) Provides additional feedback as to what's going on in the process.
void	setTaskProgress(long position) Notifies the ProgressMonitor of a change in the progress of the task.
void	setTaskSize(long taskSize) Sets the maximum value for the task progress of this ProgressMonitor.
void	started() Notifies the ProgressMonitor that the task being monitored has started.

Field Detail

NULL

static final ProgressMonitor NULL

Deprecated. this should not be used. Instead use new NullProgressMonitor();

Use NULL when you do not need or wish to use a progressMonitor. It simply ignores the progress messages.

SIZE_INDETERMINATE

static final long SIZE_INDETERMINATE

See Also:

Constant Field Values

Method Detail

setTaskSize

void setTaskSize(long taskSize)

Sets the maximum value for the task progress of this ProgressMonitor.

Parameters:

taskSize - maximum value for the task progress. A taskSize of -1 indicates the taskSize is indeterminate.

setTaskProgress

void setTaskProgress(long position)
                     throws java.lang.IllegalArgumentException

Notifies the ProgressMonitor of a change in the progress of the task.

Parameters:

position - the current task position

Throws:

java.lang.IllegalArgumentException - if isCancelled() returns true or, possibly if started() has not been called or finished() has been called.

setProgressMessage

void setProgressMessage(java.lang.String message)

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"

Parameters:

message - the message describing the state of progress.

getTaskProgress

long getTaskProgress()

Returns the current progress of the monitored task.

Returns:

the current progress of the monitored task.

setLabel

void setLabel(java.lang.String label)

Set a consise 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"

getLabel

java.lang.String getLabel()

Return the label string displayed. This is primarily to aid in debugging, and this method need not return the string set by setLabel.

getTaskSize

long getTaskSize()

started

void started()

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'.

finished

void finished()

Notifies the ProgressMonitor that the task being monitored has finished.

cancel

void 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 isCancelled() and should throw an IllegalStateException on any subsequent calls to setTaskProgress(long).

isCancelled

boolean isCancelled()

Returns true if the operation being tracked should be cancelled.

Returns:

true if the operation being tracked should be cancelled.

setAdditionalInfo

void setAdditionalInfo(java.lang.String s)

Deprecated. setProgressMessage should be used by the service provider to indicate how the process is being implemented.

additional information to be displayed alongside the progress. That might be of interest. "85 of 100 (50KB/s)"

isStarted

boolean isStarted()

true if the process has indicated that it has started.

isFinished

boolean isFinished()

true if the process has indicated that it is finished