org.das2.util.monitor

Class SubTaskMonitor

java.lang.Object

org.das2.util.monitor.SubTaskMonitor

All Implemented Interfaces:

ProgressMonitor

public class SubTaskMonitor
extends java.lang.Object
implements ProgressMonitor

creates a ProgressMonitor that maps its progress to a parent's progress. For example, if a process takes a progress monitor, but is implemented in two steps that each take a progress monitor, then two subtask monitors can be created to monitor each step, and the client who passed in the monitor will see the whole deal as one process. Note we would often abuse monitors, handing them off to several processes that would each take the monitor through its lifecycle. Now we require the lifecycle be performed once, so that machines can use the monitors to monitor processes. In this case, SubTaskMonitors should be used, and getSubtaskMonitor was added. Note too that this class should not be called directly, because getSubtaskMonitor allows the source class to return a monitor of its own design.

See Also:

ProgressMonitor.getSubtaskMonitor(int, int, java.lang.String), ProgressMonitor.getSubtaskMonitor(java.lang.String)

Field Summary

Fields inherited from interface org.das2.util.monitor.ProgressMonitor

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.
static SubTaskMonitor	create(ProgressMonitor parent, boolean cancelChecked) mode for when parent is indeterminate
static SubTaskMonitor	create(ProgressMonitor parent, long min, long max) create the subtask monitor.
static SubTaskMonitor	create(ProgressMonitor parent, long min, long max, boolean cancelChecked) create the subtask monitor.
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.
void	setLabel(java.lang.String label) Set a concise string that describes the task being performed.
void	setProgressMessage(java.lang.String message) these messages are lost, unless doEchoToParent is set.
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.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

create

public static SubTaskMonitor create(ProgressMonitor parent,
                                    long min,
                                    long max)

create the subtask monitor.

Parameters:

parent - parent monitor

min - minium

max - maximum

Returns:

SubTaskMonitor

create

public static SubTaskMonitor create(ProgressMonitor parent,
                                    long min,
                                    long max,
                                    boolean cancelChecked)

create the subtask monitor.

Parameters:

parent - parent monitor

min - minium

max - maximum

cancelChecked - true if we should check the parent's cancel status

Returns:

SubTaskMonitor

create

public static SubTaskMonitor create(ProgressMonitor parent,
                                    boolean cancelChecked)

mode for when parent is indeterminate

Parameters:

parent -

cancelChecked -

Returns:

cancel

public void cancel()

Description copied from interface: ProgressMonitor

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

Specified by:

cancel in interface ProgressMonitor

finished

public void finished()

Description copied from interface: ProgressMonitor

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.

Specified by:

finished in interface ProgressMonitor

isFinished

public boolean isFinished()

Description copied from interface: ProgressMonitor

true if the process has indicated that it is finished

Specified by:

isFinished in interface ProgressMonitor

Returns:

true if the process has indicated that it is finished

getTaskProgress

public long getTaskProgress()

Description copied from interface: ProgressMonitor

Returns the current progress of the monitored task.

Specified by:

getTaskProgress in interface ProgressMonitor

Returns:

the current progress of the monitored task.

isCancelled

public boolean isCancelled()

Description copied from interface: ProgressMonitor

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.

Specified by:

isCancelled in interface ProgressMonitor

Returns:

true if the operation being tracked should be cancelled.

setAdditionalInfo

@Deprecated
public void setAdditionalInfo(java.lang.String s)

Deprecated.

Description copied from interface: ProgressMonitor

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

Specified by:

setAdditionalInfo in interface ProgressMonitor

Parameters:

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

setTaskProgress

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

Description copied from interface: ProgressMonitor

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

Specified by:

setTaskProgress in interface ProgressMonitor

Parameters:

position - the current task position

Throws:

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

setTaskSize

public void setTaskSize(long taskSize)

Description copied from interface: ProgressMonitor

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

Specified by:

setTaskSize in interface ProgressMonitor

Parameters:

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

getTaskSize

public long getTaskSize()

Description copied from interface: ProgressMonitor

Return the size of the task. The units are arbitrary

Specified by:

getTaskSize in interface ProgressMonitor

Returns:

the size of the task.

started

public void started()

Description copied from interface: 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'.

Specified by:

started in interface ProgressMonitor

isStarted

public boolean isStarted()

Description copied from interface: ProgressMonitor

true if the process has indicated that it has started.

Specified by:

isStarted in interface ProgressMonitor

Returns:

true if the process has indicated that it has started.

setLabel

public void setLabel(java.lang.String label)

Description copied from interface: ProgressMonitor

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"

Specified by:

setLabel in interface ProgressMonitor

Parameters:

label - the label describing the task.

getLabel

public java.lang.String getLabel()

Description copied from interface: ProgressMonitor

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.

Specified by:

getLabel in interface ProgressMonitor

Returns:

the label.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

setProgressMessage

public void setProgressMessage(java.lang.String message)

these messages are lost, unless doEchoToParent is set.

Specified by:

setProgressMessage in interface ProgressMonitor

Parameters:

message -

getSubtaskMonitor

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

Description copied from interface: 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.

Specified by:

getSubtaskMonitor in interface ProgressMonitor

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

public ProgressMonitor getSubtaskMonitor(java.lang.String label)

Description copied from interface: 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.

Specified by:

getSubtaskMonitor in interface ProgressMonitor

Parameters:

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

Returns:

a new progress monitor. (generally type SubTaskMonitor)

canBeCancelled

public boolean canBeCancelled()

Description copied from interface: ProgressMonitor

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.

Specified by:

canBeCancelled in interface ProgressMonitor

Returns: