org.geotools.util
Interface ProgressListener

All Known Implementing Classes:

NullProgressListener, ProgressMailer, ProgressPrinter, ProgressWindow

public interface ProgressListener

Monitor the progress of some lengthly operation. This interface makes no assumption about the output device. It may be the standard output stream (see ProgressPrinter implementation), a window (ProgressWindow) or mails automatically sent to some address (ProgressMailer). Additionnaly, this interface provides support for non-fatal warning and exception reports.

All implementations are multi-thread safe, even the Swing implemention. can be invoked from any thread, which never need to be the Swing's thread. This is usefull for performing lenghtly operation in a background thread. Example:

  ProgressListener p = new ProgressPrinter();
  p.setDecription("Loading data");
  p.start();
  for (int j=0; j<1000; j++) {
      // ... some process...
      if ((j & 255) == 0)
          p.progress(j/10f);
  }
  p.complete();
 

Note: The line if ((j & 255) == 0) is used for reducing the amount of calls to progress(float) (only once every 256 steps). This is not mandatory, but may speed up the process.

Here is another 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:

2.0

Version:

$Id: ProgressListener.java 17702 2006-01-23 00:08:55Z desruisseaux $

Author:

Martin Desruisseaux

See Also:

ProgressPrinter, ProgressMailer, ProgressWindow, ProgressMonitor

Method Summary

void	complete() Notifies this listener that the operation has finished.
void	dispose() Release any resources used by this listener.
void	exceptionOccurred(java.lang.Throwable exception) Reports an exception.
java.lang.String	getDescription() Returns the description for the lengthly operation to be reported, or 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(java.lang.String description) Set the description for the lenghtly operation to be reported.
void	started() Notifies this listener that the operation begins.
void	warningOccurred(java.lang.String source, java.lang.String margin, java.lang.String warning) Reports a warning.

Method Detail

getDescription

public java.lang.String getDescription()

Returns the description for the lengthly operation to be reported, or if none.

setDescription

public void setDescription(java.lang.String description)

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 if none.

started

public void started()

Notifies this listener that the operation begins.

progress

public 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

public 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

public void dispose()

Release any resources used by this listener. If the progress were reported in a window, this window may be disposed.

isCanceled

public boolean isCanceled()

Is this job canceled?

setCanceled

public void setCanceled(boolean cancel)

Indicate that progress should is canceled.

warningOccurred

public void warningOccurred(java.lang.String source,
                            java.lang.String margin,
                            java.lang.String warning)

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

Parameters:

source - The source of the warning, or 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 if none. This is typically the line number where the error occured in the file.

warning - The warning message.

exceptionOccurred

public void exceptionOccurred(java.lang.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.