Will the real Swing Single Threading Rule please stand up?

disclaimer: This entry isn’t intended for a general audience. If you’re not a Swing programmer, you’ll probably want to skip it.

This is what a Swing “hello world” program used to look like.

import javax.swing.*;

public class HelloWorld2002 {

	public static void main(String[] argv) {
		JLabel bulletin = new JLabel("Hello, world!", JLabel.CENTER);

		JFrame frame = new JFrame("Bulletin");
		frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
		frame.getContentPane().add(bulletin); // adds to CENTER
		frame.setSize(200, 150);
		frame.setVisible(true);
	}
}

This is pretty much the same as the code on page 85 of my book. In fact, just about all the examples in the book kick things off this way. They create JFrames and other JComponents in the main thread, either directly in main() or indirectly. Swing is not thread-safe (by design) so we have always had to be careful. For example, if we want to call bulletin.setForeground(Color.RED) after the frame is visible, we have to make sure it executes in the event-dispatching thread. If it executes in the main thread or some other thread it’s likely to work just fine, but there are no guarantees and it is possible that bad things (such as deadlock) may happen. Even if it seems to work on your development machine, it may fail intermittently, or it may even deterministically fail on some platform on which you haven’t tested or on some future release of the JDK.

Swing Single Threading Rule (through 2003)

Once a Swing component has been realized*, only the event-dispatching thread should affect or query the component.
*Realized means that the component has been painted onscreen, or is ready to be painted. The methods setVisible(true) and pack cause a window to be realized, which in turn causes the components it contains to be realized.

Several years ago I heard rumors that intermittent errors on the Solaris operating system could be worked-around by doing everything on the event-dispatching thread. By everything I mean not only the manipulation of realized components, but also of unrealized ones, and even the instantiation of the components themselves.

I never heard anything official in this regard, but it often pays to be cautious so I started doing this in most of my production code. I noticed that other Swing programmers started doing it in their code too.

Flash forward to last week. I was at a job interview. I had submitted a code sample that set up the GUI in the main thread, and now I was being asked about it. As a Swing expert, how could I have made such a common error?

I wasn’t worried about the code itself. I probably should have looked it over before submitting it as an interview code sample, but it had already served the purpose for which I had originally written it. But it did make for an awkward interview question. Obviously I had missed a decree from on high.

Or had I? If a decree had come down, I figured, a web search would find it easily. But no. I could find a few crumbs, but only a few, and nothing close to “official.” Hmm, that’s weird.

Eventually I was able to track down an archive of a page that no longer exists on java.sun.com. That link will let you view multiple versions of the page. Notice that the Oct 03, 2003 version gives the rule as quoted above, but starting with Apr 13, 2004 the rule changes.

Swing Single Threading Rule (2004 through 2006?)

To avoid the possibility of deadlock, you must take extreme care that Swing components and models are created, modified, and queried only from the event-dispatching thread. (emphasis added)

This is from the Java Tutorial, which would have to be considered “official.” Or at least it would be if the page (or one like it) still existed. It is interesting that they provide a note explaining why they made the change. It sounds like their ComponentEventDemo would occasionally deadlock (on Solaris only?) and rather than considering this a bug in the demo or in the (Solaris) JDK, they changed the Swing threading rule.

And thus every example program in my book and, for that matter, pretty much every Swing application and applet that had ever been written up to that point needed to be changed to be in compliance.

I’m not saying they changed the rule flippantly. I’ve met some of the Swing guys at Sun and they seemed conscientious. I’m sure that ComponentEventDemo itself didn’t have any threading bugs, and I’m willing to believe that there was no obvious way to update one or more JDKs to fix the problem. But I do wonder. Where is the sample code that exhibits why the change was needed? Where is the decree? Why is it so hard to find solid information on this topic?

It turns out the current Java Tutorial does agree with the new rule. It just doesn’t make as big a deal about it.

From the current Java Tutorial

Why doesn’t the initial thread simply create the GUI itself? Because almost all code that creates or interacts with Swing components must run on the event dispatch thread. This restriction is discussed further in the next section.
(Alas, the next section doesn’t actually discuss it much.)

By almost they mean that a few Swing methods are documented to be thread-safe. This has been true since the beginning of Swing.

Anyway, it seems that the Swing “hello world” app has become less intuitive for the beginner.

import javax.swing.*;

public class HelloWorld2005 {

	public static void main(String[] argv) {
		SwingUtilities.invokeLater(new Runnable() {
			public void run() {
				aggregate();
			}
		});
	}

	private static void aggregate() {
 		JLabel bulletin = new JLabel("Hello, world!", JLabel.CENTER);

		JFrame frame = new JFrame("Bulletin");
 		frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
 		frame.getContentPane().add(bulletin); // adds to CENTER
 		frame.setSize(200, 150);
 		frame.setVisible(true);
	}
}