A DESCRIPTION OF THE PROBLEM :
According to the documentation, java.awt.GraphicsEnvironment.isHeadless

"Tests whether or not a display, keyboard, and mouse can be supported in this environment."

However, such a test would involve attempting to connect to the native platform's window system, and that's not actually what isHeadless does - all it does is check the value of the java.awt.headless system property, and check for the existence of an X11 DISPLAY variable on Linux and Solaris.

This is partially acknowledged in a technical article entitled "Using Headless Mode in the Java SE Platform", which states:

"Note: The isHeadless() method checks the specific system property, java.awt.headless, instead of the system's hardware configuration."

http://java.sun.com/developer/technicalArticles/J2SE/Desktop/headless/

Thus, the JDK documentation is in error, and the exact specification of this routine is unclear, making it difficult to port to other platforms. Indeed, there doesn't seem to be a platform-independent way of determining whether the environment is truly headless or not, which makes the isHeadless test rather pointless and potentially misleading.

(On Mac OS X, if a Java application is unable to connect to the window server, an internal error results. Whether this is a bug or not depends on the specification of isHeadless - the Mac OS X implementation behaves correctly if java.awt.headless is set to true, but otherwise, isHeadless returns false, regardless of whether "a display, keyboard and mouse can be supported" or not.)

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
I would expect the documentation to contain some version of the text that appears in the technical article:

"Note: The isHeadless() method checks the specific system property, java.awt.headless, instead of the system's hardware configuration."

together with a mention of the check on the X11 DISPLAY variable.
ACTUAL -
"Tests whether or not a display, keyboard, and mouse can be supported in this environment."

which is not the same as what it actually does, namely:

"Tests whether the java.awt.headless property is set to true"

URL OF FAULTY DOCUMENTATION :
http://java.sun.com/javase/6/docs/api/java/awt/GraphicsEnvironment.html#isHeadless()