Summary

Provide an implementation system property which controls the platform API used by java.awt.Robot on Linux to capture screen pixels.

Problem

Modern Linux desktops now enable the Wayland display server by default. X11 applications like JDK then run on the compatibility layer, XWayland.

This has some limitations, one of which is that you cannot take a screenshot with the currently used X11 API, and this is one of the reasons JDK is not supported at all running on the Wayland server, since the Robot API functionality is severely degraded and even though this is now allowed by specification [see the CSR JDK-8308012: Relax the java.awt.Robot specification], it is a practical limitation for some applications and is a blocker for automated testing.

Solution

Use newer platform API for taking screenshots on Linux desktops which works both on Wayland and X11. This will be enabled by default if Wayland is detected (but note this mode is still unsupported) and can be explicitly enabled on X.org/X11 servers via setting a system property.

The platform API to be used is the org.freedesktop.portal.ScreenCast DBUS API. This will be an important step to later supporting JDK on Wayland in X11 compatibility mode.

Specification

New system properties for Linux only

awt.robot.screenshotMethod - dbusScreencast by default for Wayland session, x11 by default for X11 session, and for all other values except dbusScreencast.

Note

1. setting this to x11 in a Wayland session means screen capture will always fail, as it does in earlier JDKs
2. setting this to dbusScreencast in an X.org session should work but is only recommended for JDK debugging purposes
3. (Applies to 17u, 11u only, 8u does not have the awt.robot.gtk property)
   The usage and meaning of the already existing awt.robot.gtk System property is unchanged and is only valid for x11 and has no effect for dbusScreencast.

awt.robot.screenshotDebug - false by default, if true prints debug information related if any is available.