How To: Deploy a MapObjects Java or ArcIMS Java component on a UNIX machine without a graphics environment (headless)


Some MapObjects Java and ArcIMS Java libraries require the availability of the java.awt package. Most versions of the java.awt library on UNIX require a graphics environment supported by a functioning X server. The X server and the DISPLAY environment variable need to be set correctly. However sometimes Java applications and libraries dependent on the java.awt package must be deployed on a machine without a local graphics environment.
A common error when a valid graphics environment cannot be found is:

"Can't connect to x11 window server using ':0.0'"

Below is a list of possible solutions:


  • The best solution is to create a MapObjects Java application that is capable of running in headless mode. MapObjects Java 2.x includes server components that do not require a display environment to function. For example, the com.esri.mo2.ui.bean.Map AWT based component requires a display environment. Either replace instances of this object with a server-based Map component (com.esri.mo2.svr.map.Map) or integrate code within your application to accomodate a headless environment. Any component that requires a display environment will throw a HeadlessException when the current display environment is not supported (for example, one is not available). Use try/catch blocks to trap for this exception and use server-based components instead of visual, AWT based components. The following Java Virtual Machine command line parameter can be used to specify that no display environment is available for a Java application:


    This parameter can be used for testing and execution. This topic is discussed in greater detail at the following url:
    Headless Capabilities

    MOJava 1.x (included with ArcIMS 4.x and 9.x) does not have this capability - see other options listed below.

  • Use Xvfb (or X Virtual Frame Buffer).

    Xvfb is an X server emulator that can run on machines with no display hardware and no physical input devices. It can be found as part of x11 Release 6.4, a version of which is available from XFree86 at http://www.xfree86.org/.
    Another website that may provide useful information on this option is located at: http://www.javasource.org/GifServlet/linux.html.
    When this process is running, the DISPLAY variable must be set to route back to local machine.

  • Use a remote X server.

    The java.awt package requires that your DISPLAY variable be set to a functioning X server.
    For example:

    setenv DISPLAY=remotehost:0.0
    export DISPLAY

    The ability of remote clients to connect to an X server by typing "xhost +" on the remote X server may need to be enabled.