Headless environment

Under a Unix operating system, like Linux, Sun Solaris and others, the AWT toolkit relies on the X server to run. For this reason, chart applications do not run in a headless environment, like a dedicated server without an X server installed.

This problem can be addressed using two different approaches. The first requires Xvfb, a virtual frame buffer that replaces an X server, providing the native graphic libraries the AWT toolkit relies on. Xvfb must be used with all JVMs prior to version 1.4. The second approach is much simpler, but can only be used with JVM 1.4 and newer versions. Both options are detailed below.


Using Xvfb

The following lines show how to start Xvfb running as display 1. The screen size is set to 800x600 and depth to 8. The first thing to be done is to create the DISPLAY environment variable.

# DISPLAY=localhost:1.0
# export DISPLAY
# Xvfb :1 -screen 0 800x600x8 &

Please refer to the Xvfb documentation for detailed instructions. There are versions of Xvfb available for different Unix operating systems. Some Linux distributions usually install Xvfb as default.
Xvfb is available for download at http://www.x.org.


Running offscreen applications using JVM 1.4 or newer versions

Java version 1.4 comes with support for headless environment. The only configuration needed is to set the system property java.awt.headless to true, specified at the command line or using the method System.setProperty(String key,String value), as below:

java -Djava.awt.headless=true or
System.setProperty("java.awt.headless","true");

Note: the ChartEncoder class, used to generate GIF,JPEG, PNG and SVG images, internally creates an invisible Frame object. The constructor of heavyweight components implemented by JDK 1.4, like the Frame class, throws a java.awt.HeadlessException. This exception is thrown when code dependent on a valid display is called in an environment that does not support a display, and this is the case of the ChartEncoder invisible Frame object.
Therefore, do not use the ChartEncoder class if you decide to generate encoded images setting the system property java.awt.headless as described above. Instead, use the BufferedImage class in conjunction with an explicit call to one of the image encoders available, as described here.