JSR 337 Maintenance Release 6: Java SE 8

This document describes additional changes to the specification of JSR 337 which is defined by the Final Release in March 2014 and amended by the following Maintenance Releases:

When specification text is provided, insertions are shown on a light green background and deletions are shown struck through on a light red background. Links to pages outside of those explicitly changed by this specification may not be functional.

Contents
1	Version Identification
2	Modern Desktop Support

Version Identification

There is no change to the values returned by the system properties java.specification.version and java.vm.specification.version. They continue to report "1.8". The value returned by the system property java.specification.maintenance.version is "6".

Modern Desktop Support

Update the java.awt.Robot specification to describe how it may operate in modern desktop environments which do not automatically give applications full access to the screen.

Append the following text to the class specification:

Platforms and desktop environments may impose restrictions or limitations on the access required to implement all functionality in the Robot class. For example:

preventing access to the contents of any part of a desktop or Window on the desktop that is not owned by the running application.
treating window decorations as non-owned content.
ignoring or limiting specific requests to manipulate windows.
ignoring or limiting specific requests for Robot generated (synthesized) events related to keyboard and mouse etc.
requiring specific or global permissions to any access to window contents, even application owned content,or to perform even limited synthesizing of events.

The Robot API specification requires that approvals for these be granted for full operation. If they are not granted, the API will be degraded as discussed here. Relevant specific API methods may document more specific limitations and requirements. Depending on the policies of the desktop environment, the approvals mentioned above may:

be required every time
or persistent for the lifetime of an application,
or persistent across multiple user desktop sessions
be fine-grained permissions
be associated with a specific binary application, or a class of binary applications.

When such approvals need to given interactively, it may impede the normal operation of the application until approved, and if approval is denied or not possible, or cannot be made persistent then it will degrade the functionality of this class and in turn any part of the operation of the application which is dependent on it.

Augment the specification of mouseMove(int, int) to describe acceptable behaviour:

The mouse pointer may not visually move on some platforms, while the subsequent mousePress and mouseRelease can be delivered to the correct location

Update the specification of getPixelColor(int, int) to allow for degraded behaviour if the required permissions are missing:

Extend the method specification to discuss permissions:
Returns the color of a pixel at the given screen coordinates.

If the desktop environment requires that permissions be granted to capture screen content, and the required permissions are not granted, then a SecurityException may be thrown, or the content of the returned Color is undefined.
Add an "API Note":
It is recommended to avoid calling this method on the AWT Event Dispatch Thread since screen capture may be a lengthy operation, particularly if acquiring permissions is needed and involves user interaction.
Define conditions when a SecurityException may be thrown:
SecurityException - if readDisplayPixels permission is not granted, or access to the screen is denied by the desktop environment

Similarly, update the specification of createScreenCapture(Rectangle) to allow for degraded behaviour if the required permissions are missing:

Remove the mouse cursor exclusion and discuss permissions in the method description:
Creates an image containing pixels read from the screen. This image does not include the mouse cursor.

If the desktop environment requires that permissions be granted to capture screen content, and the required permissions are not granted, then a SecurityException may be thrown, or the content of the returned BufferedImage is undefined.
Add an "API Note":
It is recommended to avoid calling this method on the AWT Event Dispatch Thread since screen capture may be a lengthy operation, particularly if acquiring permissions is needed and involves user interaction.
Provide additional conditions for throwing a SecurityException:
SecurityException - if readDisplayPixels permission is not granted, or access to the screen is denied by the desktop environment

The Change Specification Request (CSR) associated with these changes is 8331038. This specification aligns with the corresponding specification in the Final Release of Java SE 21 with the exception of changes to createMultiResolutionScreenCapture(Rectangle) which does not exist in Java SE 8.