org.jdesktop.swingx
[Java] Class BackgroundWorker

java.lang.Object
  org.jdesktop.beans.AbstractBean
      org.jdesktop.swingx.BackgroundWorker

public class BackgroundWorker
extends org.jdesktop.beans.AbstractBean

A JavaBean to perform lengthy GUI-interacting tasks in a dedicated thread.

When writing a multi-threaded application using Swing, there are two constraints to keep in mind: (refer to How to Use Threads for more details):

• Time-consuming tasks should not be run on the Event Dispatch Thread. Otherwise the application becomes unresponsive.
• Swing components should be accessed on the Event Dispatch Thread only.

These constraints mean that a GUI application with time intensive computing needs at least two threads: 1) a thread to perform the lengthy task and 2) the Event Dispatch Thread (EDT) for all GUI-related activities. This involves inter-thread communication which can be tricky to implement.

BackgroundWorker is a non visual JavaBean that simplifies writing these multithreaded tasks from within a GUI Builder environment. It is built upon SwingWorker, and exhibits most of the same API features as SwingWorker.

Workflow

There are two threads involved in the life cycle of a BackgroundWorker (unlike SwingWorker which can operate with three threads):

• Event Dispatch Thread: All Swing related activities occur on this thread. BackgroundWorker invokes the process and done events and notifies any PropertyChangeListeners on this thread. In addition, the execute method must be called on this thread

• Worker thread: The doInBackground event is called on this thread. This is where all background activities should happen..

A single BackgroundWorker instance may be used more than once. You cannot however call execute while the BackgroundWorker is in progress.

You can retrieve and set progress information on the BackgroundWorker at any time. There are two complementary methods for doing so, setProgress(float) and setProgressPercent(int). The first method accepts a float between the range of 0 to 1 while the second method accepts an int between the values of 0 and 100.

You may also specify the exact ExecutorService to use for the background task. This allows you to specify a thread pool, default thread priority, and other such attributes of the background task. See the ExecutorService API for more information.

BackgroundWorker operates on the basis of callbacks. You first register a BackgroundListener with the BackgroundWorker, and implement the relevant methods. For example, you implement the doInBackground method if you have tasks that must be performed on the background thread.

From within the doInBackground method you may call the publish method of your BackgroundWorker to place some data on a queue to be processed on the Event Dispatch Thread. At some point the process event will be fired with this data available within the BackgroundEvent object. In this event handler you may freely modify the GUI.

Sample Usage

The following example illustrates the simplest use case. Some processing is done in the background and when done you update a Swing component.

Say we want to find the "Meaning of Life" and display the result in a JLabel.

   final JLabel label;
   class MeaningOfLifeFinder implements BackgroundListener {
       public void doInBackground(BackgroundEvent evt) {
           String meaningOfLife = findTheMeaningOfLife();
           evt.getWorker().publish(meaningOfLife);
       }

       public void process(BackgroundEvent evt) {
           label.setText("" + evt.getData());
       }

       public void done(BackgroundEvent evt) {}
       public void started(BackgroundEvent evt) {}
   }
 
   (new MeaningOfLifeFinder()).execute();
 

Authors:

rbair

delegate

private BackgroundWorker.DelegateWorker delegate

The SwingWorker delegate. The delegate is used for almost everything: maintaining state information, progress information, and so forth.

executor

private ExecutorService executor

If specified, this ExecutorService will be used to run the SwingWorker

listeners

private List listeners

List of Background listeners

running

private boolean running

True if execute() has been called, and the background task has not yet finished

BackgroundWorker

public BackgroundWorker()

Creates a new instance of BackgroundWorker

addBackgroundListener

public void addBackgroundListener(BackgroundListener listener)

Adds a BackgroundListener

execute

public void execute()

Executes the BackgroundWorker, causing it to begin processing. This method MUST be called on the EDT, and MUST NOT be called if the BackgroundWorker is already running.

Execution follows these steps:

1. The running and done states are updated and PropertyChangeEvents are fired for them if necessary
2. The started event of the BackroundListener is called
3. The doInBackground event of the BackgroundListener is called. This is where background tasks must be performed. If you want to publish some data to the Event Dispatch Thread (EDT), then you must call the publish method of the BackgroundWorker. Calling the publish method will in turn cause the process event handler to be called on the EDT. From this event handler you are free to update the Swing GUI in any way. If you need to update the progress state, you may do so directly from the doInBackground event handler. Updates to the progress will be set via PropertyChangeEvents on the EDT.
4. Once concluded, the done event will be called. Subsequent to handling the event, the running and done states are updated and PropertyChangeEvents are fired for them if necessary

fireDoInBackgroundEvent

private void fireDoInBackgroundEvent()

fireDoneEvent

private void fireDoneEvent()

fireProcessEvent

private void fireProcessEvent(Object[] data)

fireStartedEvent

private void fireStartedEvent()

getBackgroundListeners

public BackgroundListener[] getBackgroundListeners()

getExecutorService

protected final ExecutorService getExecutorService()

Returns the executorService bound property. This method may be called from any thread.

Returns:

the executorService bound property.

getProgress

public final float getProgress()

Returns the progress bound property. This method may be called from any thread.

Returns:

the progress bound property.

getProgressPercent

public final int getProgressPercent()

Returns the progressPercent bound property. This method may be called from any thread.

Returns:

the progressPercent bound property.

isDone

public boolean isDone()

returns:

true if the BackgroundWorker has finished an execution. If the BackgroundWorker has not yet been executed, this will return false. If the BackgroundWorker has been executed, finishes, and is re-executed then this will be false until the new execution finishes. This is a bound property.

isRunning

public final boolean isRunning()

Returns:

true if the BackgroundWorker is currently running, false otherwise

publish

public void publish(Object... chunks)

Causes the given "chunks" of data to be published on the Event Dispatch Thread. This method causes the process event handler to be called. That event handler is guaranteed to be called on the EDT. This method MUST be called on the background thread.

removeBackgroundListener

public void removeBackgroundListener(BackgroundListener listener)

Returns an array of all BackgroundListeners registered with this object

setExecutorService

protected final void setExecutorService(ExecutorService svc)

Sets the executorService bound property. This property, if not null, will specify the ExecutorService to use for running the background task. If null, then the default ExecutorService of SwingWorker will be used instead. This method must only be called on the EDT, and may not be called while the BackgroundWorker is running.

setProgress

public final void setProgress(float progress)

Set the progress of this worker based on a value between 0 and 1 where 0 represents 0% and 1 represents 100%. If the progress has changed a percentage point, then a property change event will be fired. Not that changes from 0.1 to 0.11 will not be registered. This is a convenience method, and is analogous to the setProgressPercent method. This method may be called from any thread.

setProgressPercent

public final void setProgressPercent(int percent)

Set the progress of this worker based on a value between 0 and 100 where 0 represents 0% and 100 represents 100%. If the progress has changed a percentage point, then a property change event will be fired. This method may be called from any thread.

Groovy Documentation