A type of
SwingWorker that represents an application
background task. Tasks add descriptive properties that can
be shown to the user, a new set of methods for customizing
task completion, support for blocking input to the GUI while
the Task is executing, and a
TaskListener that
enables one to monitor the three key SwingWorker methods:
doInBackground,
process and
done.
When a Task completes, the final done method invokes
one of succeeded, cancelled, interrupted,
or failed. The final done method invokes
finished when the completion method returns or throws
an exception.
Tasks should provide localized values for the title,
description, and message properties in a
ResourceBundle for the Task subclass. A
ResourceMap is
loaded automatically using the Task subclass as the
startClass and Task.class the stopClass.
This ResourceMap is also used to look up format strings used in
calls to message, which is used to set
the message property.
For example: given a Task called MyTask defined like this:
class MyTask extends Task {
protected MyResultType doInBackground() {
message("startMessage", getPlannedSubtaskCount());
// do the work ... if an error is encountered:
message("errorMessage");
message("finishedMessage", getActualSubtaskCount(), getFailureCount());
// .. return the result
}
}
Typically the resources for this class would be defined in the
MyTask ResourceBundle, @{code resources/MyTask.properties}:
title = My Task
description = A task of mine for my own purposes.
startMessage = Starting: working on %s subtasks...
errorMessage = An unexpected error occurred, skipping subtask
finishedMessage = Finished: completed %1$s subtasks, %2$s failures
Task subclasses can override resource values in their own ResourceBundles:
class MyTaskSubclass extends MyTask {
}
# resources/MyTaskSubclass.properties
title = My Task Subclass
description = An appropriate description
# ... all other resources are inherited
Tasks can specify that input to the GUI is to be blocked while
they're being executed. The inputBlocker property specifies
what part of the GUI is to be blocked and how that's accomplished.
The inputBlocker is set automatically when an @Action
method that returns a Task specifies a Task.BlockingScope value
for the block annotation parameter. To customize the way
blocking is implemented you can define your own Task.InputBlocker.
For example, assume that busyGlassPane is a component
that consumes (and ignores) keyboard and mouse input:
class MyInputBlocker extends InputBlocker {
BusyIndicatorInputBlocker(Task task) {
super(task, Task.BlockingScope.WINDOW, myGlassPane);
}
protected void block() {
myFrame.setGlassPane(myGlassPane);
busyGlassPane.setVisible(true);
}
protected void unblock() {
busyGlassPane.setVisible(false);
}
}
// ...
myTask.setInputBlocker(new MyInputBlocker(myTask));
All of the settable properties in this class are bound, i.e. a
PropertyChangeEvent is fired when the value of the property changes.
As with the SwingWorker superclass, all
PropertyChangeListeners run on the event dispatching thread.
This is also true of TaskListeners.
Unless specified otherwise specified, this class is thread-safe.
All of the Task properties can be get/set on any thread.