org.das2.util.monitor

Interface ProgressMonitor

All Known Implementing Classes:

AbstractProgressMonitor, AlertNullProgressMonitor, AutoplotDataServer.D2SMonitor, AutoplotDataServer.QStreamMonitor, ConsoleTextProgressMonitor, DasProgressLabel, DasProgressPanel, DasProgressWheel, 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. 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.

Field Summary

Fields

Modifier and Type	Field and Description
static long	SIZE_INDETERMINATE

Method Summary

Modifier and Type	Method and Description
boolean	canBeCancelled() return true if the process appears to support cancel.
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, which is a concise string that describes the task being performed.
ProgressMonitor	getSubtaskMonitor(int start, int end, java.lang.String label) return a monitor to use for a subtask.
ProgressMonitor	getSubtaskMonitor(java.lang.String label) get the subtask monitor when the current task length is indeterminate.
long	getTaskProgress() Returns the current progress of the monitored task.
long	getTaskSize() Return the size of the task.
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 concise 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

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 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"

Parameters:

label - the label describing the task.

getLabel

java.lang.String getLabel()

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.

Returns:

the label.

getTaskSize

long getTaskSize()

Return the size of the task. The units are arbitrary

Returns:

the size of the task.

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. This must only be called once, and note that isFinished() must return the state of this monitor.

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

Returns:

true if the operation being tracked should be cancelled.

canBeCancelled

boolean canBeCancelled()

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.

Returns:

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)"

Parameters:

s - the message, such as (50KB/s)

isStarted

boolean isStarted()

true if the process has indicated that it has started.

Returns:

true if the process has indicated that it has started.

isFinished

boolean isFinished()

true if the process has indicated that it is finished

Returns:

true if the process has indicated that it is finished

getSubtaskMonitor

ProgressMonitor getSubtaskMonitor(int start,
                                  int end,
                                  java.lang.String label)

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.

Parameters:

start - start position on this monitor.

end - end position on this monitor (exclusive).

label - a label for the subtask, often this is handled as progress message; or null.

Returns:

a new progress monitor. (generally type SubTaskMonitor)

getSubtaskMonitor

ProgressMonitor getSubtaskMonitor(java.lang.String label)

get the subtask monitor when the current task length is indeterminate. This avoids clients having to put in dummy numbers that will cause problems in the future. The subtask can set the taskSize and taskProgress and these should be conveyed to the parent.

Parameters:

label - a label for the subtask, often this is handled as progress message; or null.

Returns:

a new progress monitor. (generally type SubTaskMonitor)