8345144: Robot does not specify all causes of IllegalThreadStateException

Reviewed-by: prr

Author: Alisen Chung

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

@@ -58,6 +58,15 @@
  * queue. For example, {@code Robot.mouseMove} will actually move
  * the mouse cursor instead of just generating mouse move events.
  * <p>
+ * @apiNote When {@code autoWaitForIdle()} is enabled, mouse and key related methods
+ * cannot be called on the AWT EDT. This is because when {@code autoWaitForIdle()}
+ * is enabled, the mouse and key methods implicitly call {@code waitForIdle()}
+ * which will throw {@code IllegalThreadStateException} when called on the AWT EDT.
+ * In addition, screen capture operations can be lengthy
+ * and {@code delay(long ms)} clearly inserts a delay, so these also
+ * should not be called on the EDT. Taken together, this means that as much as possible,
+ * methods on this class should not be called on the EDT.
+ * <p>
  * Note that some platforms require special privileges or extensions
  * to access low-level input control. If the current platform configuration
  * does not allow input control, an {@code AWTException} will be thrown
@@ -216,6 +225,8 @@ private static void checkIsScreenDevice(GraphicsDevice device) {
      *
      * @param x         X position
      * @param y         Y position
+     * @throws  IllegalThreadStateException if called on the AWT event dispatching
+     *          thread and {@code isAutoWaitForIdle} would return true
      */
     public synchronized void mouseMove(int x, int y) {
         peer.mouseMove(x, y);
@@ -268,6 +279,7 @@ public synchronized void mouseMove(int x, int y) {
      *         and support for extended mouse buttons is {@link Toolkit#areExtraMouseButtonsEnabled() disabled} by Java
      * @throws IllegalArgumentException if the {@code buttons} mask contains the mask for extra mouse button
      *         that does not exist on the mouse and support for extended mouse buttons is {@link Toolkit#areExtraMouseButtonsEnabled() enabled} by Java
+     * @throws  IllegalThreadStateException if called on the AWT event dispatching thread and {@code isAutoWaitForIdle} would return true
      * @see #mouseRelease(int)
      * @see InputEvent#getMaskForButton(int)
      * @see Toolkit#areExtraMouseButtonsEnabled()
@@ -325,6 +337,7 @@ public synchronized void mousePress(int buttons) {
      *         and support for extended mouse buttons is {@link Toolkit#areExtraMouseButtonsEnabled() disabled} by Java
      * @throws IllegalArgumentException if the {@code buttons} mask contains the mask for extra mouse button
      *         that does not exist on the mouse and support for extended mouse buttons is {@link Toolkit#areExtraMouseButtonsEnabled() enabled} by Java
+     * @throws  IllegalThreadStateException if called on the AWT event dispatching thread and {@code isAutoWaitForIdle} would return true
      * @see #mousePress(int)
      * @see InputEvent#getMaskForButton(int)
      * @see Toolkit#areExtraMouseButtonsEnabled()
@@ -349,6 +362,8 @@ private static void checkButtonsArgument(int buttons) {
      * @param wheelAmt  number of "notches" to move the mouse wheel
      *                  Negative values indicate movement up/away from the user,
      *                  positive values indicate movement down/towards the user.
+     * @throws  IllegalThreadStateException if called on the AWT event dispatching
+     *          thread and {@code isAutoWaitForIdle} would return true
      *
      * @since 1.4
      */
@@ -368,6 +383,8 @@ public synchronized void mouseWheel(int wheelAmt) {
      * @param   keycode Key to press (e.g. {@code KeyEvent.VK_A})
      * @throws  IllegalArgumentException if {@code keycode} is not
      *          a valid key
+     * @throws  IllegalThreadStateException if called on the AWT event
+     *          dispatching thread and {@code isAutoWaitForIdle} would return true
      * @see     #keyRelease(int)
      * @see     java.awt.event.KeyEvent
      */
@@ -387,7 +404,9 @@ public synchronized void keyPress(int keycode) {
      * @param   keycode Key to release (e.g. {@code KeyEvent.VK_A})
      * @throws  IllegalArgumentException if {@code keycode} is not a
      *          valid key
-     * @see  #keyPress(int)
+     * @throws  IllegalThreadStateException if called on the AWT event
+     *          dispatching thread and {@code isAutoWaitForIdle} would return true
+     * @see     #keyPress(int)
      * @see     java.awt.event.KeyEvent
      */
     public synchronized void keyRelease(int keycode) {
@@ -487,6 +506,12 @@ public synchronized BufferedImage createScreenCapture(Rectangle screenRect) {
      *          nativeResImage = resolutionVariants.get(0);
      *      }
      * }</pre>
+     *
+     * @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
@@ -641,6 +666,10 @@ public synchronized boolean isAutoWaitForIdle() {
     /**
      * Sets whether this Robot automatically invokes {@code waitForIdle}
      * after generating an event.
+     * <p>
+     * @apiNote Setting this to true means you cannot call mouse and key-controlling events
+     * on the AWT Event Dispatching Thread
+     *
      * @param   isOn    Whether {@code waitForIdle} is automatically invoked
      */
     public synchronized void setAutoWaitForIdle(boolean isOn) {
@@ -692,6 +721,10 @@ private void autoDelay() {
      * already set, this method returns immediately with the interrupt status
      * set.
      *
+     * @apiNote It is recommended to avoid calling this method on
+     * the AWT Event Dispatch Thread since delay may be a lengthy
+     * operation.
+     *
      * @param  ms time to sleep in milliseconds
      * @throws IllegalArgumentException if {@code ms} is not between {@code 0}
      *         and {@code 60,000} milliseconds inclusive