org.geotoolkit.process
Class ProgressController

Object
  ProgressController

All Implemented Interfaces:

EventListener, ProcessListener, Localized

Direct Known Subclasses:

ProgressMailer, ProgressPrinter, ProgressWindow

@ThreadSafe
public abstract class ProgressController
extends Object
implements Localized, ProcessListener

Monitors the progress of some lengthly operation, and allows cancellation. This abstract class makes no assumption about the output device. Additionally, this class provides support for non-fatal warning and exception reports.

All implementations should be multi-thread safe, even the ones that provide feedback to a user interface thread.

Usage example:

float scale = 100f / maximumCount;
controller.started();
for (int counter=0; counter<maximumCount; counter++) {
    if (controller.isCanceled()) {
        break;
    }
    controller.progress(scale * counter);
    try {
        // Do some work...
    } catch (NonFatalException e) {
        controller.exceptionOccurred(e);
    }
}
controller.complete();

Since:

3.19 (derived from 2.0)

Version:

3.19

Author:

Martin Desruisseaux (IRD, Geomatys), Jody Garnet (Refractions Research)

Module:

utility/geotk-utility (download)

View source code for this class

Constructor Summary

protected

ProgressController() Constructs a progress controller which will format messages in the system default locale.

Method Summary

void	cancel() Indicates that this job should be canceled.
abstract void	completed() Notifies this controller that the operation has finished.
void	completed(ProcessEvent event) Notifies this controller that the operation has finished and sets the states of this controller according the given event.
abstract void	exceptionOccurred(Throwable exception) Reports an exception.
void	failed(ProcessEvent event) Notifies this controller that the operation has failed and sets the states of this controller according the given event.
Locale	getLocale() Returns the locale used for formatting messages.
float	getProgress() Returns the current progress as a percent completed.
InternationalString	getTask() Returns the description of the current task being performed, or null if none.
boolean	isCanceled() Returns true if this job is canceled.
void	progressing(ProcessEvent event) Updates the task and progress state, and reports the exception if any.
void	setProgress(float percent) Notifies this controller of progress in the lengthly operation.
void	setTask(CharSequence task) Sets the description of the current task being performed.
abstract void	started() Notifies this controller that the operation begins.
void	started(ProcessEvent event) Notifies this controller that the operation begins and sets the states of this controller according the given event.
abstract void	warningOccurred(String source, String location, String warning) Reports a warning.

Methods inherited from class Object

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

Constructor Detail

ProgressController

protected ProgressController()

Constructs a progress controller which will format messages in the system default locale.

Method Detail

getLocale

public Locale getLocale()

Returns the locale used for formatting messages. The default value is the system default locale.

Specified by:

getLocale in interface Localized

Returns:

The locale.

getTask

public InternationalString getTask()

Returns the description of the current task being performed, or null if none. It is assumed that if the task is null applications may simply report that the process is "in progress" or "working" as represented in the current locale.

Returns:

Description of the task being performed, or null if none.

setTask

public void setTask(CharSequence task)

Sets the description of the current task being performed. This method is usually invoked before any progress begins. However, it is legal to invoke this method at any time during the operation, in which case the task label is updated without any change to the percentage accomplished.

Parameters:

task - Description of the task being performed as a String or InternationalString, or null if none.

started

public abstract void started()

Notifies this controller that the operation begins.

started

public void started(ProcessEvent event)

Notifies this controller that the operation begins and sets the states of this controller according the given event. The default implementation first invokes started(), then invokes progressing(event).

Specified by:

started in interface ProcessListener

Parameters:

event - The progress event, or null if none.

Since:

3.19

getProgress

public float getProgress()

Returns the current progress as a percent completed.

Returns:

Percent completed between 0 and 100 inclusive.

setProgress

public void setProgress(float percent)

Notifies this controller of progress in the lengthly operation. Progresses are reported as a value between 0 and 100 inclusive. Values out of bounds will be clamped.

Parameters:

percent - The progress as a value between 0 and 100 inclusive.

progressing

public void progressing(ProcessEvent event)

Updates the task and progress state, and reports the exception if any. More specifically:

• The new task is set to the ProcessEvent.getTask() value unless the later method returned null, in which case this ProgressController task is left unchanged.
• The new progress is set to the ProcessEvent.getProgress() value unless the later method returned Float.NaN, in which case this ProgressController progress state is left unchanged.
• If ProcessEvent.getException() returns a non-null value, then that value is given to exceptionOccurred(Throwable).

Specified by:

progressing in interface ProcessListener

Parameters:

event - The progress event, or null if none.

Since:

3.19

completed

public abstract void completed()

Notifies this controller that the operation has finished. The progress indicator will shows 100% or disappears, at implementor choice. If warning messages were pending, they will be displayed now.

completed

public void completed(ProcessEvent event)

Notifies this controller that the operation has finished and sets the states of this controller according the given event. The default implementation first invokes progressing(event), then invokes completed().

Specified by:

completed in interface ProcessListener

Parameters:

event - The progress event, or null if none.

Since:

3.19

failed

public void failed(ProcessEvent event)

Notifies this controller that the operation has failed and sets the states of this controller according the given event. The default implementation just delegates to progressing(event). Note that the above progressing method pass the exception declared by the event (if any) to the exceptionOccurred(Throwable) method.

Specified by:

failed in interface ProcessListener

Parameters:

event - The progress event, or null if none.

Since:

3.19

cancel

public void cancel()

Indicates that this job should be canceled.

isCanceled

public boolean isCanceled()

Returns true if this job is canceled.

Returns:

true if this job is canceled.

warningOccurred

public abstract void warningOccurred(String source,
                                     String location,
                                     String warning)

Reports a warning. This warning may be logged, printed to the standard error stream, appears in a windows or be ignored, at implementor choice.

Parameters:

source - Name of the warning source, or null if none. This is typically the name of the file being parsed, or the URL of the data being processed.

location - Text to write on the left side of the warning message, or null if none. This is typically the line number where the error occurred in the source file or the feature ID of the feature that produced the message.

warning - The warning message.

exceptionOccurred

public abstract void exceptionOccurred(Throwable exception)

Reports an exception. This method may prints the stack trace to the standard error stream or display it in a dialog box, at implementor choice.

Parameters:

exception - The exception to report.