org.jboss.dna.common.monitor
Interface ProgressMonitor

All Known Implementing Classes:

LoggingProgressMonitor, ProgressMonitorWrapper, SimpleProgressMonitor, SubProgressMonitor

public interface ProgressMonitor

A basic progress monitor that facilitates the updating and monitoring of progress towards the completion of an activity. Documentation hereafter will refer to the code in an application that updates progress as the Updater, and code that monitors progress as an Observer.

The progress of each activity is started when the Updater calls beginTask(double, I18n, Object...), continues with a mixture of work (worked(double)) and subtasks (createSubtask(double)), and finishes when the activity is completed (done()) or cancelled (setCancelled(boolean)).

If an activity is interrupted before its normal completion due to a cancellation request by an Observer, it is still the responsibility of the Updater to mark the activity as completed. Similarly, if an activity cannot be cancelled before its normal completion, the Updater must deny any previous cancellation request by calling setCancelled(false).

Author:

Randall Hauch, John Verhaeg

Method Summary

void	beginTask(double totalWork, I18n name, Object... params) Called by the Updater to indicate work has started on the task, specifying the total amount of work that this task constitutes.
ProgressMonitor	createSubtask(double subtaskWork) Called by the Updater to create a subtask with the given about of work.
void	done() Called by the Updater to mark this activity as complete.
String	getActivityName() Get the name of the activity.
Problems	getProblems() Return the problems encountered during the progress made towards completing the associated activity.
ProgressStatus	getStatus(Locale locale) Return the current status of this activity, localized to the specified locale.
boolean	isCancelled() Return whether a request was made by an Observer to cancel this activity.
boolean	isDone() Return whether this activity has completed.
void	setCancelled(boolean value) Called by an Observer to request the cancellation of this activity, or by the Updater to deny a prior cancellation request (i.e., when the activity completes before the Updater recognizes a cancellation request by an Observer).
void	worked(double work) Called by the Updater to report work completed for this task.

Method Detail

getActivityName

String getActivityName()

Get the name of the activity. This should never change for a progress monitor, and all subtasks should have the same name.

Returns:

the activity's name

beginTask

void beginTask(double totalWork,
               I18n name,
               Object... params)

Called by the Updater to indicate work has started on the task, specifying the total amount of work that this task constitutes.

Parameters:

totalWork - the total number of work units for the task

name - the name of the task

params - the parameters for localization

worked

void worked(double work)

Called by the Updater to report work completed for this task.

Parameters:

work - the number of work units that have been worked

createSubtask

ProgressMonitor createSubtask(double subtaskWork)

Called by the Updater to create a subtask with the given about of work. The resulting progress monitor must be started (beginTask(double, I18n, Object...)) and finished (done()).

Parameters:

subtaskWork - the number of work units for this subtask

Returns:

the progress monitor for the subtask

done

void done()

Called by the Updater to mark this activity as complete. This method must be called, even if the activity has been cancelled.

isDone

boolean isDone()

Return whether this activity has completed.

Returns:

true if this activity has completed.

setCancelled

void setCancelled(boolean value)

Called by an Observer to request the cancellation of this activity, or by the Updater to deny a prior cancellation request (i.e., when the activity completes before the Updater recognizes a cancellation request by an Observer).

Parameters:

value - true if requesting the activity be cancelled.

isCancelled

boolean isCancelled()

Return whether a request was made by an Observer to cancel this activity.

Returns:

true if this activity has been requested to be cancelled.

getStatus

ProgressStatus getStatus(Locale locale)

Return the current status of this activity, localized to the specified locale. This method returns an immutable but consistent snapshot of the status for this activity. Note that if this instance is a subtask, this method returns the status of the subtask.

Parameters:

locale - the locale in which the status is to be represented; if null, the default locale will be used

Returns:

the status of this activity

getProblems

Problems getProblems()

Return the problems encountered during the progress made towards completing the associated activity.

Returns:

the list of problems