Typical Java interpreter default configurations use native graphic libraries to carry out actual graphic rendering. This is an efficient and good general solution in most cases, but if a native graphics environment is not conveniently present, some alternate graphic rendering toolkit is needed. The problem arises in particular in many dedicated Unix server installations that do not need or provide any graphical user console interface.
This document describes three alternative methods that can be used to solve most cases where a native graphics environment is not available by default. The methods in question are:
Sun JDK 1.4 implementation provides a new Headless graphics operation mode. The headless feature is activated by setting the Sun JDK 1.4 -spesific "java.awt.headless" system property to "true", for example with an appropriate Java virtual machine command line option:
java -Djava.awt.headless=true
This should be all that is needed, but unfortunately Sun JDK 1.4 versions up to at least 1.4.1.1 have certain problems the limit the usefullness of this feature. In particular, based on our own expierences, the precense of X11 runtime libraries is still needed. This means that a X11 environment must be installed into the system, but the X11 server itself need not to be started.
For RedHat Linux distribution for example, the minimum set of X11 packages needed is:
For more information, please see the following Sun documentation:
If full X11 server is too heavy, a good alternative may be to set up a lightweight but fast virtual framebuffer X11 server that provides all the necessary graphical resources that a Java-interpreter needs, but without the complexities full interactive desktop system would have. This works at least with Linux systems, and it could work with other Unix platforms, too.
Off-screen graphics rendering is useful in server environments where the host itself does not need to offer graphical user interface services, but it runs software that needs X. The most typical case would be a Web server running graphical Java software, since typical Java interpreters rely on native graphics toolkits to carry out graphics primitives.
To make use of a virtual framebuffer device in Linux environment, install the latest XFree86-Xvfb package from your favourite Linux distribution (www.redhat.com, www.rpmfind.net), or from the original source (www.xfree86.org). While searching the software, please note that the virtual framebuffer device (Xvfb) is completely different compared to normal framebuffer (FBDev) devices.
Besides the actual virtual framebuffer device, you need also some fonts and a font server, and basic X11 runtime libraries. With RedHat installation packages, this means that at least the following packages need to be installed:
The asterisk (*) represents here some spesific XFree86 version. The actual package names may also vary, and other than RedHat systems may use completely different packaging. Please refer to XFree86 and your local system documentation for more information.
Once everything has been installed, you may test the virtual framebuffer offscreen X server with an appropriate command, for example:
Xvfb :0 -screen 0 1024x768x16 &
':0' sets the server number to 0, while the '-screen 0 1024x768x16' option defines a screen 0 with size 1024x768 and depth 16. The server now becomes available under the DISPLAY=":0.0" address, and works in every aspect like any X server, it just does not support any input devices, and it's current screen content may not be viewed directly.
The current Xvfb screen content can be accessed with the appropriate tools, but for that and other Xvfb option details, please consult the Xvfb manual page. Please note, that unlike many other X servers, Xvfb is started most conveniently without any wrapper commands like 'xinit' or 'startx'.
In the actual production environment, the X server startup command should be automatized, preferably by placing the appropriate command into the system '/etc/inittab' configuration file. In RedHat systems, for example, the runlevels 5 and 3 are reserved for systems configurations that run and do not run X, respectively, but 4 is unused by default. One viable strategy would therefore be to use runlevel 4 for running virtual X servers. This would imply, for example, the following '/etc/inittab' entries:
id:4:initdefault: xvbf:4:wait:/usr/X11R6/bin/Xvfb :0 -screen 0 1024x768x16
The first line sets the runlevel 4 as the default runlevel the
server assumes at startup, while the second line commands the system
to start the virtual framebuffer upon entering that runlevel. For more
information about runlevels and corresponding service initialization
mechanisms, please see your system local inittab
documentation.
Pure Java AWT (PJA) provides a pure Java graphics toolkit that will run wherever there is Java. In particular, it does not require any external graphics support like from X -windows or Microsoft Windows
To deploy PJA, first download the latest version from:
Then extract 'pja.jar', and place it conveniently. Define the following system runtime properties (JDK environments earlier than 1.2 only require the 'awt.tookit' property).
The method of how exactly to define the properties in the given runtime environment depends on the Java interpreter at hand. The definitions can be made, for example, at runtime with the appropriate custom Java code, or without any extra coding at the Java interpreter launch. For Sun JDK 1.2.2, for example, use the following command (written on one line):
java -Xbootclasspath:JDK/jre/lib/rt.jar:LIB/pja.jar -Dawt.toolkit=com.eteks.awt.PJAToolkit -Djava.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment -Djava.awt.fonts=JDK/jre/lib/fonts mainclassname args
'JDK' here represents the absolute directory path to the JDK 1.2.2 install directory, while 'LIB' names the 'pja.jar' install directory. Please note, that in this example the 'pja.jar' does not necessarily need to be placed along the normal class path.
For more detailed PJA deployment instructions, please consult PJA's own documentation, in particular the API documentation for the 'com.eteks.awt.PJAToolkit' class.
To use PJA with Apache/JServ, Tomcat and other servlet and JSP containers, simply add the appropriate command line options to their default Java interpreter launching commands. For Apache/JServ, for example, the Java launching command is defined in the servlet zone property file with the 'wrapper.bin' directive. The Tomcat java launching command is defined in the 'tomcat' startup script.