java.lang.Objectjavax.swing.SwingWorker<T,V>
public abstract class SwingWorker<T,V>
An abstract class 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):
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.
SwingWorker is designed for situations where you need to have a long running task run in a background thread and provide updates to the UI either when done, or while processing. Subclasses of SwingWorker must implement the doInBackground() method to perform the background computation.
Workflow
There are three threads involved in the life cycle of a SwingWorker :
Current thread: The execute() method is called on this thread. It schedules SwingWorker for the execution on a worker thread and returns immediately. One can wait for the SwingWorker to complete using the get methods.
Worker thread: The doInBackground() method is called on this thread. This is where all background activities should happen. To notify PropertyChangeListeners about bound properties changes use the firePropertyChange and getPropertyChangeSupport() methods. By default there are two bound properties available: state and progress.
Event Dispatch Thread
: All Swing related activities occur on this thread. SwingWorker invokes the
process
process
and
done()
methods and notifies any PropertyChangeListeners on this thread.
Often, the Current thread is the Event Dispatch Thread .
Before the doInBackground method is invoked on a worker thread, SwingWorker notifies any PropertyChangeListeners about the state property change to StateValue.STARTED. After the doInBackground method is finished the done method is executed. Then SwingWorker notifies any PropertyChangeListeners about the state property change to StateValue.DONE.
SwingWorker is only designed to be executed once. Executing a SwingWorker more than once will not result in invoking the doInBackground method twice.
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 extends SwingWorker<String, Object> { @Override public String doInBackground() { return findTheMeaningOfLife(); } @Override protected void done() { try { label.setText(get()); } catch (Exception ignore) { } } } (new MeaningOfLifeFinder()).execute();
The next example is useful in situations where you wish to process data as it is ready on the Event Dispatch Thread .
Now we want to find the first N prime numbers and display the results in a JTextArea. While this is computing, we want to update our progress in a JProgressBar. Finally, we also want to print the prime numbers to System.out.
class PrimeNumbersTask extends SwingWorker<List<Integer>, Integer> { PrimeNumbersTask(JTextArea textArea, int numbersToFind) { //initialize } @Override public List<Integer> doInBackground() { while (! enough && ! isCancelled()) { number = nextPrimeNumber(); publish(number); setProgress(100 * numbers.size() / numbersToFind); } } return numbers; } @Override protected voidprocess(List<Integer>
process(Integer...chunks) { for (int number : chunks) { textArea.append(number + "\n"); } } } JTextArea textArea = new JTextArea(); final JProgressBar progressBar = new JProgressBar(0, 100); PrimeNumbersTask task = new PrimeNumbersTask(textArea, N); task.addPropertyChangeListener( new PropertyChangeListener() { public void propertyChange(PropertyChangeEvent evt) { if ("progress".equals(evt.getPropertyName())) { progressBar.setValue((Integer)evt.getNewValue()); } } }); task.execute(); System.out.println(task.get()); //prints all prime numbers we have got
Because SwingWorker implements Runnable, a SwingWorker can be submitted to an Executor for execution.
Nested Class Summary | |
---|---|
static class |
SwingWorker.StateValue
Values for the state bound property. |
Constructor Summary | |
---|---|
SwingWorker
() Constructs this SwingWorker. |
Method Summary | |
---|---|
void |
addPropertyChangeListener
(
PropertyChangeListener
listener) Adds a PropertyChangeListener to the listener list. |
boolean |
cancel
(boolean mayInterruptIfRunning) Attempts to cancel execution of this task. |
protected abstract T |
doInBackground
() Computes a result, or throws an exception if unable to do so. |
protected void |
done
() Executed on the Event Dispatch Thread after the doInBackground method is finished. |
void |
execute
() Schedules this SwingWorker for execution on a worker thread. |
void |
firePropertyChange
(
String
propertyName,
Object
oldValue,
Object
newValue) Reports a bound property update to any registered listeners. |
T |
get
() Waits if necessary for the computation to complete, and then retrieves its result. |
T |
get
(long timeout,
TimeUnit
unit) Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available. |
int |
getProgress
() Returns the progress bound property. |
PropertyChangeSupport |
getPropertyChangeSupport
() Returns the PropertyChangeSupport for this SwingWorker. |
SwingWorker.StateValue |
getState
() Returns the SwingWorker state bound property. |
boolean |
isCancelled
() Returns true if this task was cancelled before it completed normally. |
boolean |
isDone
() Returns true if this task completed. |
protected void |
![]() ![]() ![]() ![]() Receives data chunks from the publish method asynchronously on the Event Dispatch Thread . |
protected void |
publish
(
V
Sends data chunks to the ![]() ![]() |
void |
removePropertyChangeListener
(
PropertyChangeListener
listener) Removes a PropertyChangeListener from the listener list. |
void |
run
() Sets this Future to the result of computation unless it has been cancelled. |
protected void |
setProgress
(int progress) Sets the progress bound property. |
Methods inherited from class java.lang. Object |
---|
clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait |
Constructor Detail |
---|
public SwingWorker()
Method Detail |
---|
protected abstract T doInBackground() throws Exception
Note that this method is executed only once.
Note: this method is executed in a background thread.
public final void run()
protected final void publish(V... chunks)
Because the process method is invoked asynchronously on the Event Dispatch Thread multiple invocations to the publish method might occur before the process method is executed. For performance purposes all these invocations are coalesced into one invocation with concatenated arguments.
For example:
publish("1"); publish("2", "3"); publish("4", "5", "6");might result in:
process("1", "2", "3", "4", "5", "6")
Sample Usage . This code snippet loads some tabular data and updates DefaultTableModel with it. Note that it safe to mutate the tableModel from inside the process method because it is invoked on the Event Dispatch Thread .
class TableSwingWorker extends SwingWorker<DefaultTableModel, Object[]> { private final DefaultTableModel tableModel; public TableSwingWorker(DefaultTableModel tableModel) { this.tableModel = tableModel; } @Override protected DefaultTableModel doInBackground() throws Exception { for (Object[] row = loadData(); ! isCancelled() && row != null; row = loadData()) { publish((Object[]) row); } return tableModel; } @Override protected voidprocess(List<Object[]>
process(Object[]...chunks) { for (Object[] row : chunks) { tableModel.addRow(row); } } }
protected void process(List
V<
V
> chunks)
... chunks)
Please refer to the publish(V...) method for more details.
protected void done()
protected final void setProgress(int progress)
Because PropertyChangeListeners are notified asynchronously on the Event Dispatch Thread multiple invocations to the setProgress method might occur before any PropertyChangeListeners are invoked. For performance purposes all these invocations are coalesced into one invocation with the last invocation argument only.
For example, the following invokations:
setProgress(1); setProgress(2); setProgress(3);might result in a single PropertyChangeListener notification with the value 3.
public final int getProgress()
public final void execute()
Note: SwingWorker is only designed to be executed once. Executing a SwingWorker more than once will not result in invoking the doInBackground method twice.
public final boolean cancel(boolean mayInterruptIfRunning)
After this method returns, subsequent calls to Future.isDone() will always return true . Subsequent calls to Future.isCancelled() will always return true if this method returned true .
public final boolean isCancelled()
public final boolean isDone()
public final T get() throws InterruptedException, ExecutionException
Note: calling get on the Event Dispatch Thread blocks all events, including repaints, from being processed until this SwingWorker is complete.
When you want the SwingWorker to block on the Event Dispatch Thread we recommend that you use a modal dialog .
For example:
class SwingWorkerCompletionWaiter extends PropertyChangeListener { private JDialog dialog; public SwingWorkerCompletionWaiter(JDialog dialog) { this.dialog = dialog; } public void propertyChange(PropertyChangeEvent event) { if ("state".equals(event.getPropertyName()) && SwingWorker.StateValue.DONE == event.getNewValue()) { dialog.setVisible(false); dialog.dispose(); } } } JDialog dialog = new JDialog(owner, true); swingWorker.addPropertyChangeListener( new SwingWorkerCompletionWaiter(dialog)); swingWorker.execute(); //the dialog will be visible until the SwingWorker is done dialog.setVisible(true);
public final T get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
Please refer to get() for more details.
public final void addPropertyChangeListener(PropertyChangeListener listener)
Note: This is merely a convenience wrapper. All work is delegated to PropertyChangeSupport from getPropertyChangeSupport() .
public final void removePropertyChangeListener(PropertyChangeListener listener)
Note: This is merely a convenience wrapper. All work is delegated to PropertyChangeSupport from getPropertyChangeSupport() .
public final void firePropertyChange(String propertyName, Object oldValue, Object newValue)
This SwingWorker will be the source for any generated events.
When called off the Event Dispatch Thread PropertyChangeListeners are notified asynchronously on the Event Dispatch Thread .
Note: This is merely a convenience wrapper. All work is delegated to PropertyChangeSupport from getPropertyChangeSupport() .
public final PropertyChangeSupport getPropertyChangeSupport()
This SwingWorker will be the source for any generated events.
Note: The returned PropertyChangeSupport notifies any PropertyChangeListeners asynchronously on the Event Dispatch Thread in the event that firePropertyChange or fireIndexedPropertyChange are called off the Event Dispatch Thread .
public final SwingWorker.StateValue getState()