org.opengis.util
Interface ProgressListener

All Known Subinterfaces:
ProgressListener
All Known Implementing Classes:
DefaultProgressListener, DelegateProgressListener, DummyProgressListener, JProgressWindow, NullProgressListener, ProgressWindow, SubProgressListener

@Extension
public interface ProgressListener

Monitor the progress of some lengthly operation, and allows cancelation. This interface makes no assumption about the output device. Additionnaly, this interface 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;
 listener.started();
 for (int counter=0; counter<maximumCount; counter++) {
     if (listener.isCanceled()) {
         break;
     }
     listener.progress(scale * counter);
     try {
         // Do some work...
     } catch (NonFatalException e) {
         listener.exceptionOccurred(e);
     }
 }
 listener.complete();
 

Since:
GeoAPI 2.1
Author:
Martin Desruisseaux, Jody Garnet

Method Summary
 void complete()
          Notifies this listener that the operation has finished.
 void dispose()
          Releases any resources used by this listener.
 void exceptionOccurred(Throwable exception)
          Reports an exception.
 String getDescription()
          Deprecated. Replaced by getTask().toString()
 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 cancelled.
 void progress(float percent)
          Notifies this listener of progress in the lengthly operation.
 void setCanceled(boolean cancel)
          Indicates that task should be cancelled.
 void setDescription(String description)
          Deprecated. Replaced by setTask
 void setTask(InternationalString task)
          Sets the description of the current task being performed.
 void started()
          Notifies this listener that the operation begins.
 void warningOccurred(String source, String location, String warning)
          Reports a warning.
 

Method Detail

getTask

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.

getDescription

@Deprecated
String getDescription()
Deprecated. Replaced by getTask().toString()

Description for the lengthly operation to be reported, or null if none.

Returns:
The task description.

setTask

void setTask(InternationalString 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 description display is updated without any change to the percentage accomplished.

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

setDescription

@Deprecated
void setDescription(String description)
Deprecated. Replaced by setTask

Sets the description for the lenghtly operation to be reported. 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 description display is updated without any change to the percentage accomplished.

Parameters:
description - The new description, or null if none.

started

void started()
Notifies this listener that the operation begins.


progress

void progress(float percent)
Notifies this listener of progress in the lengthly operation. Progress 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.

getProgress

float getProgress()
Returns the current progress as a percent completed.

Returns:
Percent completed between 0 and 100 inclusive.
Since:
GeoAPI 2.2

complete

void complete()
Notifies this listener 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.


dispose

void dispose()
Releases any resources used by this listener. If the progress were reported in a window, this window may be disposed.


isCanceled

boolean isCanceled()
Returns true if this job is cancelled.

Returns:
true if this job is cancelled.

setCanceled

void setCanceled(boolean cancel)
Indicates that task should be cancelled.

Parameters:
cancel - true for cancelling the task.

warningOccurred

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 filename in process of 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 occured in the source file or the feature ID of the feature that produced the message
warning - The warning message.

exceptionOccurred

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.


Copyright © 1996-2014 Geotools. All Rights Reserved.