'Headless' operation refers to the ability to run a Java program without a 
monitor, mouse or keyboard.  In unix environments, it usually means that X
or an equivalent windowing system does not have to be present. 

Headless Java operation would mean that a server side Java program should be 
able to use the full J2SE or J2EE API without a GUI environment being present.
This means that all AWT calls to manipulate components, graphics, fonts,
printing etc. should be functional. 

Run an X server just to satisfy getGraphics()

======================================================================

You can also get Xvfb (a virtual frame buffer Xserver) from x.org's X11R6
distribution.

This is tied to work on headless AWT.
 xxxxx@xxxxx  1999-10-14

This is the RFE number I will use to track headless, and close out all others as duplicates.
 xxxxx@xxxxx  1999-12-20

I am correcting spelling and grammar.
 xxxxx@xxxxx  2000-03-10

This feature is complete.  No further updates should be made to this evaluation. 
If additional functionality is requested, or if bugs are encountered, a new 
bug report should be filed.  

A brief description of this feature may be found at: 
http://java.sun.com/j2se/1.4/docs/guide/awt/AWTChanges.html#headless 

Please note that headless specifies that all heavyweight components throw
HeadlessException in headless mode.  That includes JWindow, JFrame, and
JDialog, since these are heavyweight components.  The javadoc specifies
this, as well as any other methods or constructors that may throw
HeadlessException in headless mode.

 xxxxx@xxxxx  2002-04-02

Note that this was not filed against the current beta, but against several JDK
1.2.x implementations. 

Geting xvfb compiled and installed from scratch is'nt straight forward
under IRIX but yes it can be done.

Xvfb works but doesn't provide a quality font server so if you are generating
gifs and jpegs for a web server the font porportions become skewed and jaggad
in some cases.  A sun X server is rock solid and render every thing right.
We gave up and just through in a frame buffer with our software and run a micro
X server to let the server do background rendering.

Only NT for JAVA ... I back to C++!!!  :(

I do distributed processing on a Unix network (client-server model,
NOT RMI-based).  With earlier java releases, I had great success
warning people I was using their machines.  Now with this bug, I
can't succeed in popping up the warning dialog on the remote box!

The function getDefaultToolkit() is failing in a manner very similar to
that in this bug report.

Got ideas?  How do I pop up a dialog on someone else's workstation?
Security is not an issue, or at least we should be able to control it
on our own network.

Thanks!!!

I came across this problem back in August 1999.  I was writing a servlet to
draw a bar chart based on parameters in the URL query string.  It worked on the
development and test box, but on the production box it threw the Exception
mentioned above.  Since I was only trying to output a GIF image, I shouldn't
have to care about the (undocumented) dependency on having an X display
working.  This occurred using Sun's own JVM on Sun OS.  I rewrote the servlet
as a Perl CGI in a hurry, but the Java 2D library I was using should absolutely
not assume that the image will go to the display, it could also go to a GIF or
JPEG file that then gets output to the browser.

It is possible to generate a GIF on the fly using acme GIFEncoder without
X Server if you use a BufferedImage. The problems comes when you want
to use a Graphics objet with BufferImage.getGraphics().
I'm trying to work arround this problem by drawing directly in a pixels array
a not use any Graphics object.

I currently develop the PJA (Pure Java AWT) library : it is 
an AWT Toolkit library with 100% pure Java graphics, 
compatible with Java 1.1.
By 100% pure Java, I mean it doesn't need any X11 Display or 
Windows GDI : 
all java.awt.Graphics drawing methods are written in Java in 
an off-screen image managed with a buffer (no Java2D yet). 
What is it for ?
Some people using servlets like me don't have access on their 
Unix web server to a X11 Display. Thanks to this library they 
will be able to generate image results with their servlets 
(charts,...) using Java Graphics methods.
They have to make one operation to switch Toolkit from X11 or 
Windows default Toolkit to the Toolkit I developed :
Change the "awt.toolkit" System property to 
"com.eteks.awt.PJAToolkit" :
thus getDefaultToolkit () static method of java.awt.Toolkit 
will use this class as Toolkit.

I want to distribute freely PJA library to enable people to 
optimize the Graphics methods and use it on their server.

If you're interested by PJA please write me...

We actually performed brain surgery on the Java 2 AWT in order to get server-side AWT
functionality.  Very tough to get fonts working because ... guess what! java.awt.Font has
a cast to SunGraphicsEnvironment buried in its initialization code, which kind of destroys
the point of being able to switch graphics environments.  The AWT initialization code is 
very, very scary. (managed to get everything working, though ... we can render
JPEGs using full Java2D without a display! Woohoo!)

PJA is now available at http://www.eteks.com/pja/en

If there is anyone listening at Sun.  It would be nice if:
1) Xvfb came with Solaris.
2) This dependency was explicitally mentioned somewhere. 
Esp. in the Java books published by Sun.

I came accross the problem when trying to print an awt 
graphics object to the printer. Although the opreation does 
not require a terminal to display the graphics onto the 
screen, the awt.print package still requires you to set the 
DISPLAY variable on the terminal from which you run the 
code. Related to the requirement for headless JAVA.

We've worked around this in the past using the approach 
described at the bottom of this URL:

http://www.sunworld.com/sunworldonline/swol-03-2000/f_swol-
03-xvfb.html

This bug is critical when running servlets on a Unix web 
server. There is usually no X server on a Web server. 

This is also important on the AS/400 where no graphics 
subsystem is available, and perhaps I might like to serve 
graphics I create locally up to clients that connect to me 
(such as creating diagrams, charts and graphs).

Are you doing anything to this bug? It is stupid that
one has to create cummy X server. Bug has been open for 
almost a year now. When are you going to fix this one?

I'm voting for this one.  I mainly need it for doing
createGraphics() on a BufferedImage, so I can use those
amazing Java2D antialased drawing operations on the server
side.

Tried PJA (mentioned here earlier). 
Unfortunately, JVM 1.2.1 running on SunOS 5.7 dies 
immediately with a segmentation fault whenever I try to 
access the servlet that uses PJA...

headless AWT means "remote AWT" ?

You cant even use the javax.swing.Timer class as it uses 
the java.awt.ActionListener  wich causes the same problem.  
Eventhough no graphics are invloved it still fails in the 
same manner.

This is pathetic? THIS is a workaround??? Run an X server or a possibly not fully-functional virtual frame buffer? I mean
Come ON.... in attempts simply to resize gifs (you know... batch processing... that stuff that ALL servers are supposed
to do...) it fails because there's no Xdisplay on the headless unix box. WHY does it need one? What possible purpose
could it serve? Whose ego is stroked here by requiring one? Who's poor coding skill is masked by leaving this bug in
as a 'feature' ?

"bug fixed in a non-public release, case closed" is not
a very satisfying answer.

I tried to run non-graphics Java applications (like web-
server) on an intentionally configured Linux without any 
X11 library installed. It worked with JDK 1.2.2, but 
downloaded yesterday JDK 1.3 even didn't run "java" until I 
copied libX11.so to the libraries directory and reran 
ldconfig. Running ldd on the actual "java" executable shows 
that it requires libX11.so just by itself. (this is not a 
reverse engineering, is it?)

The goal of my experiments is to determine the minimal 
Linux configuration a non-graphic (headless) Java 
application will run on. The most possible minimal 
configuration would consist only of Linux kernel, shell, 
and some shell script acting as init program (specified at 
LILO command line), actually invoking a Java application. 
However .java_wrapper itself requires some shell utilities 
(like dirname, expr, uname, etc.) Well, this can be worked 
around by writing a custom shell script which does the same 
but without calling those utilities...

BTW, JDK1.3 self-extractor requires glibc2 to run (why not 
make it statically compiled?)

I'm getting this problem when using the AWT classes to draw 
an image which I then encode using the Acme GifEncoder 
(www.acme.com).  Any idea where we can get the fix from (is 
it in JDK1.3 or can we get the classes that are part of 
this "non-public release")?

Sorry sun, this is NOT "closed, fixed" - it's a BUG. IT DOES NOT WORK.
All of us drawing handy dandy little gif maps and graphs and things on servers are NOT HAPPY.
My workarounds have been REALLY ugly - output the graphics as "pic" commands, feed the results
to ghostwriter, then grab the resulting gif.  Yes, that was in production. 8cP

Is Sun considering doing something with this or are we 
stuck with Xvfb, which occasionally takes of sucks the CPU 
dry, or is there a new work around?

Randy Cross

Closed, fixed?????
These guys must be kidding!!
How could anyone call running an X server a fix???

i just want to run the java virtual machine without X
installed. period.
please dont tell me the workaround is to "run an X server". 
any suggestions?

JDK 1.4 claims to fix the problem by adding support for 
headless operation. I downloaded the JDK 1.4 beta but it 
still tries to connect to an X server. Has anyone been able 
to run it in headless mode? Does it require some special 
configuration (environment variables, java system 
properties, etc.)?

JDK 1.4 beta indeed supports headless operation but you 
need to set the "java.awt.headless" system property to 
value "true" to enable it. This can be done by adding "-
Djava.awt.headless=true" to the command line when launching 
the JRE. Thanks to Sun's AWT engineering team for promptly 
resolving the configuration issue!

Will the fix on JDK1.4 beta be reported to previous version
?

Problem with the Xvfb is that it does not support TrueType 
fonts.  Further there are other workarounds on Graphics2d 
that involve using TrueType scalable fonts.  Any help on 
this one?

After adding -Djava.awt.headless=true, I still got 
following message when excuting JFrame frame = new JFrame
();:
java.awt.HeadlessException
        at java.awt.GraphicsEnvironment.checkHeadless
(GraphicsEnvironment.java:1
23)
        at java.awt.Window.<init>(Window.java:252)
        at java.awt.Frame.<init>(Frame.java:390)
        at java.awt.Frame.<init>(Frame.java:355)    

In previous messages the following was determined to be the 
procedure to get headless AWT applications to run:
JDK 1.4 beta supports headless operation by setting 
the "java.awt.headless" system property to value "true". 
This can be done by adding "-Djava.awt.headless=true" to 
the command line when launching the JRE. 
Has anyone actually got this to work?  Is there a way to 
set this system property in a JServ servlet environment 
where the JRE is lauched by Apache JServ?  The goal here is 
to draw graphics off-screen, convert to an image, and 
display on an http client browser.
Thanks.

JDK 1.4 beta supports headless operation by setting the "java.awt.headless" system property to value 
"true". This can be done by adding "-Djava.awt.headless=true" to the command line when launching the JRE. 
 Is there a way to set this system property so it is always set without having to set it the command line?  
That is -- is there a property file I can edit to add Djava.awt.headless=true.
Thanks,
Gerry Lavender
Media Recovery

The following code works in a servlet I wrote for uploading
photos.  I use java.awt.Image to determine the dimensions. 
This code works on Tomcat 3.2.2, JDK1.4 beta, and RH Linux
7.1.  This is identical to setting the property on the
command line, but I think it's simpler than messing with the
servlet engines startup scripts.

   try {
      System.setProperty("java.awt.headless", "true");
   } catch (Exception e) {
      e.printStackTrace();
   }

Using this code, the "Cannot connect to X display" error has
disappeared.  Note, my Linux server doesn't run X and is
only accessed via SSH.  FYI:

[davis@enigma davis]$ java -version
java version "1.4.0-beta"
Java(TM) 2 Runtime Environment, Standard Edition (build
1.4.0-beta-b65)
Java HotSpot(TM) Client VM (build 1.4.0-beta-b65, mixed mode)

Let me know if anyone has problems with this fix.
Guy Davis  guy-davis@home.com   http://davis.dnsalias.com

Still can't get it to work. I have tried both adding the 
property "java.awt.headless=true" to my code, as well as to 
the command line, but it still gives me the 
java.awt.HeadlessException. I am running a cobalt raq4i on 
JDK 1.4beta. Any suggestions?

wait, there must be something wrong here:
Reported Against  ... merlin-beta 
Release Fixed  merlin-beta 

BTW I'd prefer "speaking" JDK names rather than codenames.

tchia - HeadlessException means you *are* headless, and you're trying
to do something that you *can't do* on a headless system.  The most
likely case is that you're creating a Frame.  Regardless, the line of code
that is generating the exception is the problem; you can't do whatever
it is without a display.

Headless mode is meant to allow use of 'the full J2SE or 
J2EE API without a GUI environment', then goes on to say 
that headlessException will bve thrown when using 
heavyweight awt components. Which is going to be true going 
forwards? It's causing me a huge headache at the moment!

Why should I be forced to use BETA software in my 
production system because Sun won't provide a 'real' fix to 
this problem?  I'm using JDK 1.3.1 and have no intention of 
going to JDK 1.4+ for at least two releases.  Does anyone 
know a real solution that is applicable to JDK 1.3.1?

Please fix this issue. Those of us wishing to use Tomcat on
headless Linux servers would appreciate it.
Until then, I guess it's back to using PHP or the Perl::GD
module for dynamic graphics.

I am using iPlanet Web Server 4.1 SP2 on Sun Solaris 2.7 to 
create Server Side images.I am getting the error " Can't 
connect to X11 window server using ':0.0' as the value of 
the DISPLAY variable."
Please let me know a workaround so that I am able to draw 
charts.

You have to set your display in the iPlanet 'start' file. 
Edit ../server4/https-servername/start and put in:

# DISPLAY setting to fix bug in AWT java package
DISPLAY=:1.0; export DISPLAY

Then stop and start your webserver. This works for me on 
SUN running Xvfb

It works!
Do not use Frame and others heavyweight components, I done 
it like this:

import java.awt.*;
import java.awt.image.*;
import java.io.*;

public class Graph {

   public static void main(String args[]) throws Exception {
		  	   
      BufferedImage bi = new BufferedImage
(100,100,BufferedImage.TYPE_BYTE_INDEXED);
      Graphics g = bi.createGraphics();
      g.setColor(new Color(0xF5F5F5));
      g.setColor(new Color(0x8888AC));
      g.fillRect(0,0,100,100);		
      FileOutputStream out = new FileOutputStream
("test.gif");
      Acme.JPM.Encoders.GifEncoder gif = new 
Acme.JPM.Encoders.GifEncoder(bi, out);
      gif.encode();
      out.close();
      System.exit(0);
   }
   
}

compile it:
javac Graph.java
run it:
java -Djava.awt.headless=true Graph

Thats all!

The problem is that I MUST use heavy-weight components - I am trying to set up a Cruise Control automated testing environment for my unit and acceptance tests that include tests that bring up the GUI and use java.awt.Robot to change things and verify that things changed properly.
I want this to run on a headless NT machine that will do nothing but run these tests.  When I read the problem description and then the fix, I was happy.  However, reading further, and reading about it in the docs, I see that Sun has implemented something less than what they said.  It seems just plain stupid that I should have to lock a machine in a closet just so that I can leave a userid logged on with a tube to run automated tests.  It turns out that PJA does nothing for me because it can't handle the heavy-weight components either.  Does anybody know of a solution for this?

Headlessenvironment works but it still requires X11 to be
installed. On my Linux box, java command produces 
java.lang.UnsatisfiedLinkError when I am tring to get
BufferedImage or GraphicalEnvironment. It needs X11
libraries to work (libXp.so, for example). So, we still have
no complete headless environment - we still need 
X11 libraries. But there is no point to install whole X11
system on a web server or on a dedicated device.

FWIW, javax.imageio is faster than Acme.
E.g.
--
import java.awt.*;
import java.awt.image.*;
import java.io.*;
import javax.imageio.ImageIO;

public class Graph {

   public static void main(String args[]) throws Exception {
		  	   
      BufferedImage bi = new BufferedImage
(100,100,BufferedImage.TYPE_BYTE_INDEXED);
      Graphics g = bi.createGraphics();
      g.setColor(new Color(0xF5F5F5));
      g.setColor(new Color(0x8888AC));
      g.fillRect(0,0,100,100);		
      FileOutputStream out = new FileOutputStream
("test.png");
      ImageIO.write(bi, "PNG", out);
      out.close();
      System.exit(0);
   }
   
}
--

For the web, you'll want to write into a
ByteArrayOutputStream, set the content length, and write
the bytes to the response output stream.

Am I wrong in thinking that headless AWT means that AWT now
works in a headless environment? But the supposed fix is to
simply throw an exception? 

If PJA can do it, why can't Sun? Maybe PJA could be released
under an Apache style license so it could be incorporated
into the JRE? PJA does work great, but is slightly
complicated to set up (bootclasspath param and awt command
line switches).

Even though headless is supposed to be fixed I'm having a bit 
of a problem with it. I'm developing under Linux Debian.
I've set headless to true and some of my code works just 
fine.. But.. this little function doesn't

private int getTextWidth(String text, Font font) {
	FontMetrics fm = (new Applet()).getFontMetrics
(font);
	return fm.stringWidth(text);
}

I'm not sure that it's 100% correct, but it works fine under 
windows so I suppose it is..

If anyone can help I'd be grateful..

Thanks.

Hello,

I have a Linux server with a Java application hosted on it 
where the Java application produces a dynamic GIF. The 
hosting company informed me the server is NOT headless and 
they managed to turn X11 windows on. But still the Java 
application would not create the GIF images. I have been 
reading about setting the $DISPLAY env variable. Any idea 
how to set the $DISPLAY variable. The server has Linux, 
Orion applications server and JDK 1.3.0. Thank you

The headless supports solves my problem.  However I 
when i execute the java.awt.headless the command 
hangs.  Any solution for that?  the process is still 
running.
using JVM 1.4.0

How to deal with HeadlessException?

How to deal with HeadlessException?

Mac OS X Server/FOP note:  this problem is still being encountered by some folks using FOP.  In case you are in that category and have been lead here then this is for you:  1) this new headless option should work for you.  Really.  2) If for some reason you can't run the newer JDK or for some other reason the option fails, then get Apple's X11 package, make your app's UID a valid login, log in, start your calling app from the X terminal (making sure that the env var DISPLAY is set and exported), and then when FOP is called your app should pop up a little java window to the logged in user's aqua X11 session - leave that open, you may then close the xterm but leave X11 running and the user session open and uninterrupted (no fast user switching).  FOP should run Ok, but obviously the headless switch is a much better solution - so upgrade!

The real problem here is people are trying to do gui operations without a properly configured os (at least as far as the gui is concerned) and oddly enough it does not work.
As for the solaris packages, they are not a part of the windows binary, just the referance impl (if you wish to complain about source make sure you are talking about the correct implementation!)
todd_musheno@yahoo.com