org.cishell.framework.algorithm
Interface ProgressMonitor

public interface ProgressMonitor

A class to monitor the progress of an algorithm. It allows for notification of progress, notification of cancellation, notification of pausing, and description of current work during execution. Except for the setter methods, the methods are generally only called by the algorithm with the CIShell application providing the progress monitor implementation.

Author:

Bruce Herr (bh2@bh2.net)

Field Summary

static int	CANCELLABLE Capability constant specifying that this algorithm can be cancelled (value is 1<<2)
static ProgressMonitor	NULL_MONITOR A monitor with empty methods for use by algorithms when no ProgressMonitor has been given to it.
static int	PAUSEABLE Capability constant specifying that this algorithm can be paused (value is 1<<3)
static int	WORK_TRACKABLE Capability constant specifying that this algorithm can update its work progress (value is 1<<1)

Method Summary

void	describeWork(String currentWork) Method to describe what the algorithm is currently doing for the benefit of the users of the algorithm as it progresses during execution
void	done() The algorithm is finished executing
boolean	isCanceled() Returns whether cancellation of algorithm execution is requested.
boolean	isPaused() Returns whether pausing of algorithm execution is requested.
void	setCanceled(boolean value) Sets or clears a flag for cancellation of this algorithm's execution.
void	setPaused(boolean value) Sets or clears a flag for pausing of this algorithm's execution.
void	start(int capabilities, int totalWorkUnits) Notifies the start of execution of the algorithm in addition to revealing how many work units will be used
void	worked(int work) Notifies that a certain number of units of work has been completed

Field Detail

NULL_MONITOR

static final ProgressMonitor NULL_MONITOR

A monitor with empty methods for use by algorithms when no ProgressMonitor has been given to it. This helps to eliminate spurious null checks to ensure the progress monitor is not null.

WORK_TRACKABLE

static final int WORK_TRACKABLE

Capability constant specifying that this algorithm can update its work progress (value is 1<<1)

See Also:

Constant Field Values

CANCELLABLE

static final int CANCELLABLE

Capability constant specifying that this algorithm can be cancelled (value is 1<<2)

See Also:

Constant Field Values

PAUSEABLE

static final int PAUSEABLE

Capability constant specifying that this algorithm can be paused (value is 1<<3)

See Also:

Constant Field Values

Method Detail

start

void start(int capabilities,
           int totalWorkUnits)

Notifies the start of execution of the algorithm in addition to revealing how many work units will be used

Parameters:

capabilities - An OR'ed int that tells the monitor what the algorithm is capable of with respect to the monitor. The OR'ed values are taken from the int constants specified in this interface.

totalWorkUnits - The number of work units, -1 if the algorithm does not provide progress information

worked

void worked(int work)

Notifies that a certain number of units of work has been completed

Parameters:

work - The number of units of work completed since last notification

done

void done()

The algorithm is finished executing

setCanceled

void setCanceled(boolean value)

Sets or clears a flag for cancellation of this algorithm's execution. An algorithm developer can ignore or clear this flag if it cannot stop midstream. This is one of the methods that can be called by something other than the algorithm.

Parameters:

value - Set or clear the cancellation request

isCanceled

boolean isCanceled()

Returns whether cancellation of algorithm execution is requested. An algorithm that can be cancelled should poll this method when convenient to see if it should cancel.

Returns:

Whether cancellation of algorithm execution is requested

setPaused

void setPaused(boolean value)

Sets or clears a flag for pausing of this algorithm's execution. An algorithm developer can ignore or clear this flag if it cannot pause midstream. This is one of the methods that can be called by something other than the algorithm.

Parameters:

value - Set or clear the pause request

isPaused

boolean isPaused()

Returns whether pausing of algorithm execution is requested. An algorithm that can be paused should poll this method when convenient to see if it should pause.

Returns:

Whether pausing of algorithm execution is requested

describeWork

void describeWork(String currentWork)

Method to describe what the algorithm is currently doing for the benefit of the users of the algorithm as it progresses during execution

Parameters:

currentWork - A short description of the current work the algorithm is doing