Summary

Specify all cases where java.awt.Robot may throw IllegalThreadStateException.

Problem

When robot.autoWaitForIdle is set to true, all mouse and key-related methods of AWT Robot will throw java.lang.IllegalThreadStateException when invoked on the EDT. However, this is not mentioned in the Robot specification.

Additionally, even methods that may be called on the EDT are not necessarily appropriate to be called on the EDT, specifically if they may invoke lengthy operations. This is also not described in the specification.

Solution

Update the specification of AWT Robot to describe all cases where IllegalThreadStateException may be thrown.

Additionally, update the specification of methods which may not be appropriate to be called on the EDT with advice on this topic.

Specification

class java.awt.Robot

+ * @apiNote When {@code waitForIdle()} must not be called on the AWT EDT, since
+ * when {@code autoWaitForIdle()} is enabled, mouse and key related methods
+ * will implicitly call {@code waitForIdle()} and therefore {@code 
IllegalThreadStateException}
+ * will be thrown. 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.

+     * @apiNote Setting this to true means you cannot call mouse and 
key-controlling events
+     * on the AWT Event Dispatching Thread
public synchronized void setAutoWaitForIdle(boolean isOn);

+     * @throws  IllegalThreadStateException if called on the AWT event 
dispatching
+     *          thread and {@code isAutoWaitForIdle} would return true
public synchronized void mouseMove(int x, int y);

+     * @throws  IllegalThreadStateException if called on the AWT event 
dispatching
+     *          thread and {@code isAutoWaitForIdle} would return true
public synchronized void mousePress(int buttons) ;

+     * @throws  IllegalThreadStateException if called on the AWT event 
dispatching
+     *          thread and {@code isAutoWaitForIdle} would return true
public synchronized void mouseRelease(int buttons);

+     * @throws  IllegalThreadStateException if called on the AWT event 
dispatching
+     *          thread and {@code isAutoWaitForIdle} would return true
public synchronized void mouseWheel(int wheelAmt);

+     * @throws  IllegalThreadStateException if called on the AWT event 
dispatching
+     *          thread and {@code isAutoWaitForIdle} would return true
public synchronized void keyPress(int keycode);

+     * @throws  IllegalThreadStateException if called on the AWT event
+     *          dispatching thread and {@code isAutoWaitForIdle} would 
return true
public synchronized void keyRelease(int keycode);

+     * @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.
public synchronized MultiResolutionImage 
createMultiResolutionScreenCapture(Rectangle screenRect);

+     * @apiNote It is recommended to avoid calling this method on
+     * the AWT Event Dispatch Thread since delay may be a lengthy
+     * operation.
public void delay(int ms);