Threads and Swing

NOTE: This article about multithreading in Swing was archived in April 1998. A month later, we published another article expanding on the subject. For a better understanding of how multithreading works in Swing, we recommend that you read both this article and the newer one, which is titled "Using a Swing Worker Thread".

Later, the Swing team updated the classes used in both articles, so that they conform to the Swing 1.1 API and reflect feedback from threads experts. See "Using a Swing Worker Thread" for details.

The Swing API was designed to be powerful, flexible, and easy to use. In particular, we wanted to make it easy for programmers to build new Swing components, whether from scratch or by extending components that we provide.

For this reason, we do not require Swing components to support access from multiple threads. Instead, we make it easy to send requests to a component so that the requests run on a single thread.

This article gives you information about threads and Swing components. The purpose is not only to help you use the Swing API in a thread-safe way, but also to explain why we took the thread approach we did.

Here are the sections of this article:

• The single-thread rule: Swing components can be accessed by only one thread at a time. Generally, this thread is the event-dispatching thread.
   
• Exceptions to the rule: A few operations are guaranteed to be thread-safe.
   
• Event dispatching: If you need access to the UI from outside event-handling or drawing code, then you can use the SwingUtilities invokeLater()or invokeAndWait() method.
   
• Creating threads: If you need to create a thread -- for example, to handle a job that's computationally expensive or I/O bound -- you can use a thread utility class such as SwingWorker or Timer.
   
• Why did we implement Swing this way?: This article ends with some background information about Swing's thread safety.

Here's the rule:

Once a Swing component has been realized, all code that might affect or depend on the state of that component should be executed in the event-dispatching thread.

This rule might sound scary, but for many simple programs, you don't have to worry about threads. Before we go into detail about how to write Swing code, let's define two terms: realized and event-dispatching thread.

Realized means that the component's paint() method has been or might be called. A Swing component that's a top-level window is realized by having one of these methods invoked on it: setVisible(true), show(), or (this might surprise you) pack(). Once a window is realized, all components that it contains are realized. Another way to realize a component is to add it to a container that's already realized. You'll see examples of realizing components later.

The event-dispatching thread is the thread that executes drawing and event-handling code. For example, the paint() and actionPerformed() methods are automatically executed in the event-dispatching thread. Another way to execute code in the event-dispatching thread is to use the SwingUtilities invokeLater() method.

• A few methods are thread-safe: In the Swing API documentation, thread-safe methods are marked with this text:
  
  This method is thread safe, although most Swing methods are not. Please see "Threads and Swing" for more information.
   

An application's GUI can often be constructed and shown in the main thread: The following typical code is safe, as long as no components (Swing or otherwise) have been realized:

public class MyApplication {
public static void main(String[] args) {
   JFrame f = new JFrame("Labels");
   // Add components to
   // the frame here...
   f.pack();
   f.show();
   // Don't do any more GUI work here...
   }
}

All the code shown above runs on the "main" thread. The f.pack() call realizes the components under the JFrame. This means that, technically, the f.show() call is unsafe  and should be executed in the event-dispatching thread. However, as  long as the program doesn't already have a visible GUI, it's exceedingly  unlikely that the JFrame or its contents will receive a paint() call before f.show() returns. Because  there's no GUI code after the f.show() call, all GUI  work moves from the main thread to the event-dispatching thread, and  the preceding code is, in practice, thread-safe.
 

• An applet's GUI can be constructed and shown in the init() method: Existing browsers don't draw an applet until after its init() and start() methods have been called. Thus, constructing the GUI in the applet's init() method is safe, as long as you never call show() or setVisible(true) on the actual applet object.
  
  By the way, applets that use Swing components must be implemented as subclasses of JApplet, and components should be added to the JApplet content pane, rather than directly to the JApplet. As for any applet, you should never perform time-consuming initialization in the init() or start() method; instead, you should start a thread that performs the time-consuming task.
   
• The following JComponent methods are safe to call from any thread: repaint(), revalidate(), and invalidate(). The repaint() and revalidate() methods queue requests for the event-dispatching thread to call paint() and validate(), respectively. The invalidate() method just marks a component and all of its direct ancestors as requiring validation.
   
• Listener lists can be modified from any thread: It's always safe to call the addListenerTypeListener() and removeListenerTypeListener() methods. The add/remove operations have no effect on an event dispatch that's under way.

NOTE: The revalidate() method is new. The important difference between revalidate() and validate() is that revalidate() queues requests that might be coalesced into a single validate() call. This is similar to the way that repaint() queues paint requests that might be coalesced.

 
Most post-initialization GUI work naturally occurs in the event-dispatching thread. Once the GUI is visible, most programs are driven by events such as button actions or mouse clicks, which are always handled in the event-dispatching thread.

However, some programs need to perform non-event-driven GUI work after the GUI is visible. Here are some examples:

• Programs that must perform a lengthy initialization operation
  before they can be used: This kind of program should generally show some GUI while the initialization is occurring, and then update or change the GUI. The initialization should not occur in the event-dispatching thread; otherwise, repainting and event dispatch would stop. However, after initialization the GUI update/change should occur in the event-dispatching thread, for thread-safety reasons.
   
• Programs whose GUI must be updated as the result of non-AWT events: For example, suppose a server program can get requests from other programs that might be running on different machines. These requests can come at any time, and they result in one of the server's methods being invoked in some possibly unknown thread. How can that method update the GUI? By executing the GUI update code in the event-dispatching thread.

The SwingUtilities class provides two methods to help you run code in the event-dispatching thread:

• invokeLater(): Requests that some code be executed in the event-dispatching thread. This method returns immediately, without waiting for the code to execute.
   
• invokeAndWait(): Acts like invokeLater(), except that this method waits for the code to execute. As a rule, you should use invokeLater() instead of this method.

This page gives you some examples of using this API. Also see the BINGO example in The Java Tutorial, especially the following classes: CardWindow, ControlPane, Player, and OverallStatusPane.

You can call invokeLater() from any thread to request the event-dispatching thread to run certain code. You must put this code in the run() method of a Runnable object and specify the Runnable object as the argument to

invokeLater(). The invokeLater method returns immediately, without waiting for the event-dispatching thread to execute the code. Here's an example of using invokeLater():

Runnable doWorkRunnable = new Runnable() {
    public void run() { doWork(); }
};
SwingUtilities.invokeLater(doWorkRunnable);

The invokeAndWait() method is just like invokeLater(), except that invokeAndWait() doesn't return until the event-dispatching thread has executed the specified code. Whenever possible, you should use invokeLater() instead of invokeAndWait(). If you use invokeAndWait(), make sure that the thread that calls invokeAndWait() does not hold any locks that other threads might need while the call is occurring.

Here's an example of using invokeAndWait():

void showHelloThereDialog()
        throws Exception {
    Runnable showModalDialog = new
      Runnable() {
        public void run() {
            JOptionPane.showMessageDialog(
               myMainFrame, "Hello There");
        }
    };
    SwingUtilities.invokeAndWait
       (showModalDialog);
}

Similarly, a thread that needs access to GUI state, such as the contents of a pair of text fields, might have the following code:

void printTextField() throws Exception {
    final String[] myStrings =
       new String[2];

    Runnable getTextFieldText =
      new Runnable() {
        public void run() {
            myStrings[0] =
               textField0.getText();
            myStrings[1] =
               textField1.getText();
        }
    };
    SwingUtilities.invokeAndWait
      (getTextFieldText);

    System.out.println(myStrings[0]
                       + " " + myStrings[1]);
}

If you can get away with it, avoid using threads. Threads can be difficult to use, and they make programs harder to debug. In general, they just aren't necessary for strictly GUI work, such as updating component properties.

However, sometimes threads are necessary. Here are some typical situations where threads are used:

• To perform a time-consuming task without locking up the event-dispatching thread. Examples include making extensive calculations, doing something that results in many classes being loaded (initialization, for example), and blocking for network or disk I/O.
   
• To perform an operation repeatedly, usually with some predetermined period of time between operations.
   
• To wait for messages from clients.

You can use two classes to help you implement threads:

• SwingWorker:  Creates a background thread to execute time-consuming operations.
   
• Timer: Creates a thread that executes some code one or more times, with a user-specified delay between executions.

The SwingWorker class is implemented in SwingWorker.java, which is not in the Swing release.

SwingWorker does all the dirty work of implementing a background thread. Although many programs don't need background threads, background threads are sometimes useful for performing time-consuming operations, which can improve the perceived performance of a program.

To use the SwingWorker class, you first create a subclass of it. In the subclass, you must implement the construct() method so that it contains the code to perform your lengthy operation. When you instantiate your SwingWorker subclass, the SwingWorker creates a thread that calls your construct() method. When you need the object returned by the construct() method, you call the SwingWorker's get() method. Here's an example of using SwingWorker:

...//in the main method:
    final SwingWorker worker =
      new SwingWorker() {
        public Object construct() {
            return new
               expensiveDialogComponent();
        }
    };

...//in an action event handler:
    JOptionPane.showMessageDialog
        (f, worker.get());

When the program's main() method creates the SwingWorker object, the SwingWorker immediately starts a new thread that instantiates ExpensiveDialogComponent. The main() method also constructs a GUI that consists of a window with a button.

When the user clicks the button, the program blocks, if necessary, until the ExpensiveDialogComponent has been created. The program then shows a modal dialog containing the ExpensiveDialogComponent. You can find the entire program in MyApplication.java.

The Timer class works with an ActionListener to perform an operation one or more times. When you create a timer, you specify how often the timer should perform the operation, and you specify which object is the listener for the timer's action events. Once you start the timer, the action listener's actionPerformed() method is invoked one or more times to perform its operation.

 The actionPerformed() method defined in the Timer's action listener is invoked in the event-dispatching thread. That means that you never have to use the invokeLater() method in it.

Here's an example of using a Timer to implement an animation loop:

public class AnimatorApplicationTimer
  extends JFrame implements
  ActionListener {
    ...//where instance variables
    ...//are declared:
    Timer timer;

    public AnimatorApplicationTimer(...) {
        ...
        // Set up a timer that calls this 
        // object's action handler.
        timer = new Timer(delay, this);
        timer.setInitialDelay(0);
        timer.setCoalesce(true);
        ...
    }

    public void startAnimation() {
        if (frozen) {
            // Do nothing.  The user has
            // requested that we stop
            // changing the image.
        } else {
            //Start (or restart) animating!
            timer.start();
        }
    }

    public void stopAnimation() {
        //Stop the animating thread.
        timer.stop();
    }

    public void actionPerformed
      (ActionEvent e) {
        //Advance the animation frame.
        frameNumber++;

        //Display it.
        repaint();
    }
    ...
}

There are several advantages in executing all of the user interface code in a single thread:

• Component developers do not have to have an in-depth understanding of threads programming: Toolkits like ViewPoint and Trestle, in which all components must fully support multithreaded access, can be difficult to extend, particularly for developers who are not expert at threads programming. Many of the toolkits developed more recently, such as SubArctic and IFC, have designs similar to Swing's.
   
• Events are dispatched in a predictable order: The runnable objects enqueued by invokeLater() are dispatched from the same event queue as mouse and keyboard events, timer events, and paint requests. In toolkits where components support multithreaded access, component changes are interleaved with event processing at the whim of the thread scheduler. This makes comprehensive testing difficult or impossible.
   
• Less overhead: Toolkits that attempt to carefully lock critical sections can spend a substantial amount of time and space managing locks. Whenever the toolkit calls a method that might be implemented in client code (for example, any public or protected method in a public class), the toolkit must save its state and release all locks so that the client code can grab locks if necessary. When control returns from the method, the toolkit must regrab its locks and restore its state. All applications bear the cost of this, even though most applications do not require concurrent access to the GUI.
  
  Here's a description, written by the authors of the SubArctic Java Toolkit, of the problem of supporting multithreaded access in a toolkit:

It is our basic belief that extreme caution is warranted when designing and building multi-threaded applications, particularly those which have a GUI component. Use of threads can be very deceptive. In many cases they appear to greatly simplify programming by allowing design in terms of simple autonomous entities focused on a single task. In fact in some cases they do simplify design and coding. However, in almost all cases they also make debugging, testing, and maintenance vastly more difficult and sometimes impossible. Neither the training, experience, or actual practices of most programmers, nor the tools we have to help us, are designed to cope with the non-determinism. For example, thorough testing (which is always difficult) becomes nearly impossible when bugs are timing dependent. This is particularly true in Java where one program can run on many different types of machines and OS platforms, and where each program must work under both preemptive or non-preemptive scheduling.

As a result of these inherent difficulties, we urge you to think twice about using threads in cases where they are not absolutely necessary. However, in some cases threads are necessary (or are imposed by other software packages) and so subArctic provides a thread-safe access mechanism. This section describes this mechanism and how to use it to safely manipulate the interactor tree from an independent thread.

The thread-safe mechanism they're referring to is very similar to the invokeLater() and invokeAndWait() methods provided by the SwingUtilities class.