T - the result type returned by this SwingWorker's doInBackground and get methodsV - the type used for carrying out intermediate results by this SwingWorker's publish and
process methodspublic abstract class SwingWorker<T,V> extends Object implements Future<T>, Runnable
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 : 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. 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. SwingWorker invokes the
process and done() methods and notifies any PropertyChangeListeners on this thread.
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 void process(List<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.| Modifier and Type | Class and Description |
|---|---|
static class |
SwingWorker.StateValue
Values for the
state bound property. |
| Constructor and Description |
|---|
SwingWorker()
Constructs this
SwingWorker. |
| Modifier and Type | Method and Description |
|---|---|
void |
addPropertyChangeListener(PropertyChangeListener listener)
Adds a
PropertyChangeListener to the listener list. |
boolean |
cancel(boolean mayInterruptIfRunning) |
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()
Note: calling
get on the Event Dispatch Thread blocks all events, including repaints, from
being processed until this SwingWorker is complete. |
T |
get(long timeout,
TimeUnit unit)
Please refer to
get() for more details. |
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() |
boolean |
isDone() |
protected void |
process(List<V> chunks)
Receives data chunks from the
publish method asynchronously on the Event Dispatch Thread. |
protected void |
publish(V... chunks)
Sends data chunks to the
process(java.util.List<V>) method. |
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. |
protected abstract T doInBackground() throws Exception
Exception - if unable to compute a resultpublic final void run()
Future to the result of computation unless it has been cancelled.protected final void publish(V... chunks)
process(java.util.List<V>) method. This method is to be used from inside the doInBackground method to deliver intermediate results for processing on the Event Dispatch Thread inside
the process method.
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 void process(List<Object[]> chunks) {
for (Object[] row : chunks) {
tableModel.addRow(row);
}
}
}
chunks - intermediate results to processprocess(java.util.List<V>)protected void process(List<V> chunks)
publish method asynchronously on the Event Dispatch Thread.
Please refer to the publish(V...) method for more details.chunks - intermediate results to processpublish(V...)protected void done()
doInBackground method is finished. The default
implementation does nothing. Subclasses may override this method to perform completion actions on the Event
Dispatch Thread. Note that you can query status inside the implementation of this method to determine the
result of this task or whether this task has been cancelled.doInBackground(),
isCancelled(),
get()protected final void setProgress(int progress)
progress bound property. The value should be from 0 to 100.
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 invocations:
setProgress(1); setProgress(2); setProgress(3);might result in a single
PropertyChangeListener notification with the value 3.progress - the progress value to setIllegalArgumentException - is value not from 0 to 100public final int getProgress()
progress bound property.public final void execute()
SwingWorker for execution on a worker thread. There are a number of worker
threads available. In the event all worker threads are busy handling other SwingWorkers this
SwingWorker is placed in a waiting queue.
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)
public final boolean isCancelled()
isCancelled in interface Future<T>public final T get() throws InterruptedException, ExecutionException
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);
get in interface Future<T>InterruptedExceptionExecutionExceptionpublic final T get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
get() for more details.get in interface Future<T>InterruptedExceptionExecutionExceptionTimeoutExceptionpublic final void addPropertyChangeListener(PropertyChangeListener listener)
PropertyChangeListener to the listener list. The listener is registered for all properties. The
same listener object may be added more than once, and will be called as many times as it is added. If listener is null, no exception is thrown and no action is taken.
Note: This is merely a convenience wrapper. All work is delegated to PropertyChangeSupport from getPropertyChangeSupport().listener - the PropertyChangeListener to be addedpublic final void removePropertyChangeListener(PropertyChangeListener listener)
PropertyChangeListener from the listener list. This removes a PropertyChangeListener
that was registered for all properties. If listener was added more than once to the same event source, it
will be notified one less time after being removed. If listener is null, or was never added, no
exception is thrown and no action is taken.
Note: This is merely a convenience wrapper. All work is delegated to PropertyChangeSupport from getPropertyChangeSupport().listener - the PropertyChangeListener to be removedpublic final void firePropertyChange(String propertyName, Object oldValue, Object newValue)
old and new are
equal and non-null.
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().propertyName - the programmatic name of the property that was changedoldValue - the old value of the propertynewValue - the new value of the propertypublic final PropertyChangeSupport getPropertyChangeSupport()
PropertyChangeSupport for this SwingWorker. This method is used when flexible access
to bound properties support is needed.
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.PropertyChangeSupport for this SwingWorkerpublic final SwingWorker.StateValue getState()
SwingWorker state bound property.Copyright © 2017. All rights reserved.