Skip to main content

Headless toolkit basics

Posted by ixmal on April 4, 2006 at 10:15 AM PDT


java.awt.Toolkit is an abstract superclass of all actual implementations of the Abstract Window Toolkit (AWT). Subclasses of java.awt.Toolkit are used to bind various components to particular native resources.

You may have noticed that many of the methods in java.awt.Toolkit, java.awt.GraphicsEnvironment and other classes require the availability of display, keyboard and mouse. You may easily find such methods as they throw java.awt.HeadlessException in headless mode.

What is that headless mode?

Headless mode

Headless mode is a system configuration in which graphic adapter, keyboard or mouse are lacking. For example, mainframes or dedicated servers do not support a display, keyboard or mouse. On the other hand, such environments possess a substantial computing power, which can be used for the non-visual features realization.

All the AWT components with the exception of Canvas and Panel can not be operated in Headless mode. These include: applets, buttons, checkboxes, choices, dialogs, file dialogs, frames, labels, lists, menus, menubars, popup menus, page and print dialogs, scrollbars, scrollpanes, text components, windows, and their descendants. Such heavyweight components require a native "peer" at the operating system level, which cannot be guaranteed on "headless" machines.

Here is a brief list of what is available in Headless mode:

    * lightweight components: canvas, panels, Swing components (with the exception of JApplet, JDialog, JFrame and JWindow)

    * fonts and font metrics

    * colors

    * images

    * printing using java.awt.PrintJob, java.awt.print.* and javax.print.*

    * audio beep

Headless mode setup

To set up the Headless mode you should set the appropriate system property using System.setProperty() method. Property name is "java.awt.headless" and possible values are "true" or "false". Note, that this property shoult be set before the toolkit is initialized with Toolkit.getDefaultToolkit() method.

To check up the availability of the Headless mode you should use GraphicsEnvironment.isHeadless() method. This method checks the "java.awt.headless" property: if it equals to "true", it is assumed that java.awt.HeadlessException will be thrown from all the methods that are dependent on a display, keyboard, or mouse. This method *does not check* hardware configuration of the system, so it is possible to run the application in the Headless mode on a usual desktop.

Operating in the Headless mode


Following code represents a blank rectangular area onto which we can paint. To create a new canvas component use java.awt.Canvas class:

    Canvas c = new Canvas()
        public void paint(Graphics g)
            Rectangle r = getBounds();
            g.drawLine(0, 0, r.width - 1, r.height - 1);
            g.drawLine(0, r.height - 1, r.width - 1, 0);


This code illustrates how to set font using Font class for drawing a text string. The Graphics object is used to render this string:

    public void paint(Graphics g)
        g.setFont(new Font("Arial", Font.ITALIC, 12));
        g.drawString("Test", 32, 8);


This code shows how to set color with the specified red, green, and blue values for drawing a filled rectangle. The Graphics object is used to render this line:

    public void paint(Graphics g)
        g.setColor(new Color(255, 127, 0));
        g.fillRect(0, 0, 32, 24);


In following example the read method of the javax.imageio.ImageIO class decodes the grapefruit.jpg file and returns a result as a Buffered Image:

    Image i = null;
        File f = new File("grapefruit.jpg");
        i =;
    catch (Exception z)


This code illustrates how print a prepared canvas enabling to define the printer as a default surface for the paint method:

    PrinterJob pj = PrinterJob.getPrinterJob();
    pj.setPrintable(new Printable()
        public int print(Graphics g, PageFormat pf, int pageIndex)
            if (pageIndex > 0)
                return Printable.NO_SUCH_PAGE;
            ((Graphics2D)g).translate(pf.getImageableX(), pf.getImageableY());
            // paint canvas
            return Printable.PAGE_EXISTS;



All the capabilities described above are represented in the integrated HeadlessBasics example. There are some comments in the source code to better understang Headless mode basics.

Compile the source code using javac compiler. Download grapefruit.jpg image and put it to the directory where the HeadlessBasics class is located and then run the example with `java HeadlessBasics`. You can run it without any display, keyboard or mouse in the system, for example, using a remote console.

Related Topics >>