Headless Systems

In most cases, the FNZ Studio Platform is installed on a so-called "headless system". A headless system is a server that has been configured to operate without a monitor, keyboard, or mouse. A headless system is typically controlled via a network connection. The opposite is a system with a graphical user interface like a desktop on a workstation.

If a Java program runs on a headless system, certain UI-related operations like opening a window cannot be executed. Trying to do so usually results in an exception being thrown by the JVM code:

java.awt.HeadlessException
        at java.awt.GraphicsEnvironment.checkHeadless(GraphicsEnvironment.java:159)
        at java.awt.Window.(Window.java:432)
        at java.awt.Frame.(Frame.java:403)
        [...]

java.lang.NoClassDefFoundError: Could not initialize class sun.awt.X11GraphicsEnvironment
        at java.lang.Class.forName0(Native Method)
        at java.lang.Class.forName(Class.java:171)
        at java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(GraphicsEnvironment.java:68)
        ...

Some other operations, like creating images in memory and rendering fonts when generating PDF files may use the native graphical subsystem of the operating system as well. The native graphical subsystem can execute such operations in a highly performant manner. If it is not or only partially available, the JVM may have to use an alternative approach for certain operations.

Usually, the JVM automatically detects whether it is running on a headless system or not. If it is, it enables a special headless mode. In this headless mode, it can perform most graphical background operations, even on systems without support for a graphical output. If this detection fails and the headless mode is not enabled on a headless system, or if the UI system is not properly configured, the JVM could fail to operate in headless mode and experience issues when trying to perform such operations.

The Platform does not require a heavy graphical subsystem like an X server or Windows desktop; it can run perfectly well in headless mode. In order to avoid the problems mentioned above, I suggest to run the Platform on a JVM with headless mode enabled.

To do so:

• Set the system property java.awt.headless on the command line when starting a Java program (including a Java application server):

  Copy

  java -Djava.awt.headless=true ... [other options] ...
  

  If you set this property to true, the JVM runs in headless mode, regardless of if a UI system is available or not.

To check if headless mode is enabled, use one of the following alternatives:

• If you have access to FNZ Studio Composition, open the Interactive Script Editor and execute the following line of code:

  Copy

      CONF('java.awt.headless')
  

  This function can return true, false or null: If it returns false or null, the headless mode has not been enabled explicitly.

• Check the "inside" view of the JVM on this flag by executing the following line of code:

  Copy

  java.awt.GraphicsEnvironment.isHeadless()
  

  If this returns true, headless mode has been enabled, either explicitly or automatically.