org.netbeans.spi.wizard
Class DeferredWizardResult

java.lang.Object
  extended by org.netbeans.spi.wizard.DeferredWizardResult
Direct Known Subclasses:
WizardPanelNavResult

public abstract class DeferredWizardResult
extends java.lang.Object

Object which can be returned from WizardPage.WizardResultProducer.finish() or WizardPanelProvider.finish(). A DeferredWizardResult does not immediately calculate its result; it is used for cases where some time consuming work needs to be performed to compute the result (such as creating files on disk), and a progress bar should be shown until the work is completed.

Author:
Tim Boudreau
See Also:
ResultProgressHandle

Constructor Summary
Constructor and Description
DeferredWizardResult()
          Creates a new instance of DeferredWizardResult which cannot be aborted and shows a progress bar.
DeferredWizardResult(boolean canAbort)
          Creates a new instance of DeferredWizardResult which may or may not be able to be aborted.
DeferredWizardResult(boolean canAbort, boolean useBusy)
          Creates a new instance of DeferredWizardResult which may or may not be able to be aborted, and which may simply disable the wizard's UI instead of showing a progress bar while the background work runs.
 
Method Summary
Modifier and Type Method and Description
 void abort()
          Abort computation of the result.
 boolean canAbort()
          If true, the background thread can be aborted.
 boolean isUseBusy()
          Determine if the UI should be completely disabled while the background work is running (i.e.
abstract  void start(java.util.Map settings, ResultProgressHandle progress)
          Begin computing the result.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DeferredWizardResult

public DeferredWizardResult()
Creates a new instance of DeferredWizardResult which cannot be aborted and shows a progress bar.


DeferredWizardResult

public DeferredWizardResult(boolean canAbort)
Creates a new instance of DeferredWizardResult which may or may not be able to be aborted.

Parameters:
canAbort - determine if background computation can be aborted by calling the abort() method

DeferredWizardResult

public DeferredWizardResult(boolean canAbort,
                            boolean useBusy)
Creates a new instance of DeferredWizardResult which may or may not be able to be aborted, and which may simply disable the wizard's UI instead of showing a progress bar while the background work runs.

Parameters:
canAbort -
useBusy -
Method Detail

start

public abstract void start(java.util.Map settings,
                           ResultProgressHandle progress)
Begin computing the result. This method is called on a background thread, not the AWT event thread, and computation can immediately begin. Use the progress handle to set progress as the work progresses. IMPORTANT: This method MUST call either progress.finished with the result, or progress.failed with an error message. If this method returns without calling either of those methods, it will be assumed to have failed.

Parameters:
settings - The settings gathered over the course of the wizard
progress - A handle which can be used to affect the progress bar.

canAbort

public final boolean canAbort()
If true, the background thread can be aborted. If it is possible to abort, then the UI may allow the dialog to be closed while the result is being computed.


abort

public void abort()
Abort computation of the result. This method will usually be called on the event thread, after start() has been called, and before finished() has been called on the ResultProgressHandle that is passed to start(), for example, if the user clicks the close button on the dialog showing the wizard while the result is being computed.

This method does nothing by default - it is left empty so that people who do not want to support aborting background work do not have to override it. It is up to the implementor to set a flag or otherwise notify the background thread to halt computation. A simple method for doing so is as follows:

 volatile Thread thread;
 public void start (Map settings, ResultProgressHandle handle) {
 try {
  synchronized (this) {
     thread = Thread.currentThread();
  }
  
  //do the background computation, update progress.  Every so often, 
  //check Thread.interrupted() and exit if true
 } finally {
    synchronized (this) {
       thread = null;
    }
  }
 }
 
 public synchronized void abort() {
  if (thread != null) thread.interrupt();
 }
 
or you can use a volatile boolean flag that you set in abort() and periodically check in the body of start().


isUseBusy

public final boolean isUseBusy()
Determine if the UI should be completely disabled while the background work is running (i.e. you do not want a progress bar, you just want all navigation disabled [note on some window managers, the user will still be able to click the dialog's window drag-bar close button, so you still should override abort() to stop computation if possible]).

Returns:
true if no progress bar should be displayed and the UI should just disable itself