org.opengis.util
Interface ProgressListener


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.

Here an example showing how to cancel:


      Iterator iterator = null;
      try {
          float size = size();
          float position = 0;
          progress.started();
          for (iterator = iterator(); !progress.isCanceled() && iterator.hasNext(); progress.progress(++position/size)) {
              try {
                  Feature feature = (Feature) iterator.next();
                  visitor.visit(feature);
              }
              catch (Exception erp) {
                  progress.exceptionOccurred(erp);
              }
          }
          progress.complete();
      }
      finally {
          close (iterator);
      }
 
Note the use of try and catch to report exceptions.

Since:
GeoAPI 2.1

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. Please use getTask().toString()
 InternationalString getTask()
          Return the current task being performed, or null if none.
 boolean isCanceled()
          Is this job canceled?
 void progress(float percent)
          Notifies this listener of progress in the lengthly operation.
 void setCanceled(boolean cancel)
          Indicate that progress should is canceled.
 void setDescription(String description)
          Deprecated. please use setTask
 void setTask(InternationalString task)
          Set the current task being performed.
 void started()
          Notifies this listener that the operation begins.
 void warningOccurred(String source, String margin, String warning)
          Reports a warning.
 

Method Detail

getDescription

String getDescription()
Deprecated. Please use getTask().toString()

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


getTask

InternationalString getTask()
Return 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:
task being performed.

setTask

void setTask(InternationalString task)
Set the current task being performed.

This task may be user visible and is represented as an international string for locale support.

Parameters:
task -

setDescription

void setDescription(String description)
Deprecated. please use setTask

Set 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.


complete

void complete()
Notifies this listener that the operation has finished. The progress indicator will shows 100% or disaspears, 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()
Is this job canceled?


setCanceled

void setCanceled(boolean cancel)
Indicate that progress should is canceled.

TODO:
Is it really listener job to cancel a task?

warningOccurred

void warningOccurred(String source,
                     String margin,
                     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.
margin - 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.
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.



Copyright © 1994-2008 Open Geospatial Consortium. All Rights Reserved.