Overview

Sun introduced a new feature with Java 1.4 which allows server applications to access core graphics objects, such as fonts, colors and images. When used inside a 1.4+ JVM, ReportMill activates this feature (to take advantage of Java's font and image libraries) from a static initializer in the RMDocument class. It gets activated with this line of code the first time you create or load a template:

        System.setProperty("java.awt.headless", "true");

This setting is generally transparent to most developers and should just work on most platforms without intervention. Occasionally, however, some additional steps have to be taken.

Symptoms of "headless" failure

There are occasionally conditions that can interfere with activating Java AWT's Headless mode. It seems this can happen if ReportMill's activation happens too late in the execution of your application or on some linux platforms, this can happen if the X11 graphics environment hasn't been installed on the machine.

The most common indication of a failure to activate the headless mode is that your application will throw a Java.awt.HeadlessException. Alternatively, you may see a complaint mentioning the GraphicsEnvironment class or failure to find an X11 server (unix only). Another possibility is that you will see an error in initializing the RMFont class or a failure when loading an image.

You can positively diagnose headless mode activation failure by calling the following line of code after setting the headless property (or initializing a ReportMill template):

        java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment().getAllFonts();

If this line of code throws an exception, then your application isn't running in headless mode.

Fixing headless activation failure

The most common solution to fixing ReportMill's headless activation failure is to activate headless mode earlier in your application. You can try executing the line referenced above at the earliest possible moment in the initialization of your application. Another option is to execute your application with the following Java command line arg:

        prompt> java -Djava.awt.headless=true <your_normal_args>

References

    Google: Search google for "Java" + "Headless" + "<your_platform>".

    ColdFusion: http://www.macromedia.com/support/flex/ts/documents/java_awt_headless.htm