8307779: Relax the java.awt.Robot specification

Reviewed-by: phh, prr
Backport-of: 42eb684707287a41a9922519de6b08aff1d83eae

Author: Alexander Zvegintsev

src/java.desktop/share/classes/java/awt/Robot.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -68,6 +68,43 @@
  * <p>
  * Applications that use Robot for purposes other than self-testing should
  * handle these error conditions gracefully.
+ * <p>
+ * Platforms and desktop environments may impose restrictions or limitations
+ * on the access required to implement all functionality in the Robot class.
+ * For example:
+ * <ul>
+ * <li> preventing access to the contents of any part of a desktop
+ * or Window on the desktop that is not owned by the running application.</li>
+ * <li> treating window decorations as non-owned content.</li>
+ * <li> ignoring or limiting specific requests to manipulate windows.</li>
+ * <li> ignoring or limiting specific requests for Robot generated (synthesized)
+ * events related to keyboard and mouse etc.</li>
+ * <li> requiring specific or global permissions to any access to window
+ * contents, even application owned content,or to perform even limited
+ * synthesizing of events.</li>
+ * </ul>
+ *
+ * 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:
+ * <ul>
+ * <li>be required every time</li>
+ * <li>or persistent for the lifetime of an application,</li>
+ * <li>or persistent across multiple user desktop sessions</li>
+ * <li>be fine-grained permissions</li>
+ * <li>be associated with a specific binary application,
+ * or a class of binary applications.</li>
+ * </ul>
+ *
+ * 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.
  *
  * @author      Robi Khan
  * @since       1.3
@@ -180,6 +217,11 @@ private void checkIsScreenDevice(GraphicsDevice device) {
 
     /**
      * Moves mouse pointer to given screen coordinates.
+     * <p>
+     * The mouse pointer may not visually move on some platforms,
+     * while the subsequent mousePress and mouseRelease can be
+     * delivered to the correct location
+     *
      * @param x         X position
      * @param y         Y position
      */
@@ -374,8 +416,22 @@ private void checkKeycodeArgument(int keycode) {
 
     /**
      * Returns the color of a pixel at the given screen coordinates.
+     * <p>
+     * If the desktop environment requires that permissions be granted
+     * to capture screen content, and the required permissions are not granted,
+     * then a {@code SecurityException} may be thrown,
+     * or the content of the returned {@code Color} is undefined.
+     * </p>
+     * @apiNote 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.
+     *
      * @param   x       X position of pixel
      * @param   y       Y position of pixel
+     * @throws  SecurityException if {@code readDisplayPixels} permission
+     *          is not granted, or access to the screen is denied
+     *          by the desktop environment
      * @return  Color of the pixel
      */
     public synchronized Color getPixelColor(int x, int y) {
@@ -386,12 +442,25 @@ public synchronized Color getPixelColor(int x, int y) {
     }
 
     /**
-     * Creates an image containing pixels read from the screen.  This image does
-     * not include the mouse cursor.
+     * Creates an image containing pixels read from the screen.
+     * <p>
+     * If the desktop environment requires that permissions be granted
+     * to capture screen content, and the required permissions are not granted,
+     * then a {@code SecurityException} may be thrown,
+     * or the contents of the returned {@code BufferedImage} are undefined.
+     * </p>
+     * @apiNote 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.
+     *
      * @param   screenRect      Rect to capture in screen coordinates
      * @return  The captured image
-     * @throws  IllegalArgumentException if {@code screenRect} width and height are not greater than zero
-     * @throws  SecurityException if {@code readDisplayPixels} permission is not granted
+     * @throws  IllegalArgumentException if {@code screenRect} width and height
+     *          are not greater than zero
+     * @throws  SecurityException if {@code readDisplayPixels} permission
+     *          is not granted, or access to the screen is denied
+     *          by the desktop environment
      * @see     SecurityManager#checkPermission
      * @see     AWTPermission
      */
@@ -401,7 +470,6 @@ public synchronized BufferedImage createScreenCapture(Rectangle screenRect) {
 
     /**
      * Creates an image containing pixels read from the screen.
-     * This image does not include the mouse cursor.
      * This method can be used in case there is a scaling transform
      * from user space to screen (device) space.
      * Typically this means that the display is a high resolution screen,
@@ -434,8 +502,11 @@ public synchronized BufferedImage createScreenCapture(Rectangle screenRect) {
      * }</pre>
      * @param   screenRect     Rect to capture in screen coordinates
      * @return  The captured image
-     * @throws  IllegalArgumentException if {@code screenRect} width and height are not greater than zero
-     * @throws  SecurityException if {@code readDisplayPixels} permission is not granted
+     * @throws  IllegalArgumentException if {@code screenRect} width and height
+     *          are not greater than zero
+     * @throws  SecurityException if {@code readDisplayPixels} permission
+     *          is not granted, or access to the screen is denied
+     *          by the desktop environment
      * @see     SecurityManager#checkPermission
      * @see     AWTPermission
      *