## org.das2.util.monitor.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 {@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.

## SIZE_INDETERMINATE

## canBeCancelled

canBeCancelled( ) → boolean

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:

a boolean
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## cancel

cancel( ) → void

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

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## finished

finished( ) → void

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.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getLabel

getLabel( ) → String

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getSubtaskMonitor

getSubtaskMonitor( int start, int end, String label ) → ProgressMonitor

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)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getSubtaskMonitor

getSubtaskMonitor( String label ) → ProgressMonitor

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)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getTaskProgress

getTaskProgress( ) → long

Returns the current progress of the monitored task.

### Returns:

the current progress of the monitored task.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getTaskSize

getTaskSize( ) → long

Return the size of the task. The units are arbitrary

### Returns:

the size of the task.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isCancelled

isCancelled( ) → boolean

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isFinished

isFinished( ) → boolean

true if the process has indicated that it is finished

### Returns:

true if the process has indicated that it is finished
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isStarted

isStarted( ) → boolean

true if the process has indicated that it has started.

### Returns:

true if the process has indicated that it has started.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setAdditionalInfo

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

## setLabel

setLabel( String label ) → void

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.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setProgressMessage

setProgressMessage( String message ) → void

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.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setTaskProgress

setTaskProgress( long position ) → void

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

### Parameters

position - the current task position

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setTaskSize

setTaskSize( long taskSize ) → void

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.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## started

started( ) → void

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

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]