7109991: SwingUtilities.isXMouseButton behaves unexpectedly starting from JDK8 b08

Reviewed-by: rupashka

src/share/classes/java/awt/event/InputEvent.java

@@ -321,14 +321,15 @@ public abstract class InputEvent extends ComponentEvent {
      * @param when         a long int that gives the time the event occurred.
      *                     Passing negative or zero value
      *                     is not recommended
-     * @param modifiers    the modifier keys down during event (e.g. shift, ctrl,
-     *                     alt, meta)
-     *                     Passing negative parameter is not recommended.
-     *                     Zero value means no modifiers.
-     *                     Either extended _DOWN_MASK or old _MASK modifiers
-     *                     should be used, but both models should not be mixed
-     *                     in one event. Use of the extended modifiers is
-     *                     preferred
+     * @param modifiers    a modifier mask describing the modifier keys and mouse
+     *                     buttons (for example, shift, ctrl, alt, and meta) that
+     *                     are down during the event.
+     *                     Only extended modifiers are allowed to be used as a
+     *                     value for this parameter (see the {@link InputEvent#getModifiersEx}
+     *                     class for the description of extended modifiers).
+     *                     Passing negative parameter
+     *                     is not recommended.
+     *                     Zero value means that no modifiers were passed
      * @throws IllegalArgumentException if <code>source</code> is null
      * @see #getSource()
      * @see #getID()
@@ -416,9 +417,13 @@ public abstract class InputEvent extends ComponentEvent {
 
     /**
      * Returns the extended modifier mask for this event.
+     * <P>
+     * Extended modifiers are the modifiers that ends with the _DOWN_MASK suffix,
+     * such as ALT_DOWN_MASK, BUTTON1_DOWN_MASK, and others.
+     * <P>
      * Extended modifiers represent the state of all modal keys,
      * such as ALT, CTRL, META, and the mouse buttons just after
-     * the event occurred
+     * the event occurred.
      * <P>
      * For example, if the user presses <b>button 1</b> followed by
      * <b>button 2</b>, and then releases them in the same order,

src/share/classes/java/awt/event/MouseEvent.java

@@ -488,14 +488,15 @@ public class MouseEvent extends InputEvent {
      * @param when         A long integer that gives the time the event occurred.
      *                     Passing negative or zero value
      *                     is not recommended
-     * @param modifiers    The modifier keys down during event (e.g. shift, ctrl,
-     *                     alt, meta)
+     * @param modifiers    a modifier mask describing the modifier keys and mouse
+     *                     buttons (for example, shift, ctrl, alt, and meta) that
+     *                     are down during the event.
+     *                     Only extended modifiers are allowed to be used as a
+     *                     value for this parameter (see the {@link InputEvent#getModifiersEx}
+     *                     class for the description of extended modifiers).
      *                     Passing negative parameter
      *                     is not recommended.
-     *                     Zero value means that no modifiers were passed.
-     *                     Use either an extended _DOWN_MASK or old _MASK modifiers,
-     *                     however do not mix models in the one event.
-     *                     The extended modifiers are preferred for using
+     *                     Zero value means that no modifiers were passed
      * @param x            The horizontal x coordinate for the mouse location.
      *                       It is allowed to pass negative values
      * @param y            The vertical y coordinate for the mouse location.
@@ -586,14 +587,15 @@ public class MouseEvent extends InputEvent {
      * @param when         A long integer that gives the time the event occurred.
      *                     Passing negative or zero value
      *                     is not recommended
-     * @param modifiers    The modifier keys down during event (e.g. shift, ctrl,
-     *                     alt, meta)
+     * @param modifiers    a modifier mask describing the modifier keys and mouse
+     *                     buttons (for example, shift, ctrl, alt, and meta) that
+     *                     are down during the event.
+     *                     Only extended modifiers are allowed to be used as a
+     *                     value for this parameter (see the {@link InputEvent#getModifiersEx}
+     *                     class for the description of extended modifiers).
      *                     Passing negative parameter
      *                     is not recommended.
-     *                     Zero value means that no modifiers were passed.
-     *                     Use either an extended _DOWN_MASK or old _MASK modifiers,
-     *                     however do not mix models in the one event.
-     *                     The extended modifiers are preferred for using
+     *                     Zero value means that no modifiers were passed
      * @param x            The horizontal x coordinate for the mouse location.
      *                       It is allowed to pass negative values
      * @param y            The vertical y coordinate for the mouse location.
@@ -657,14 +659,15 @@ public class MouseEvent extends InputEvent {
      * @param when         A long integer that gives the time the event occurred.
      *                     Passing negative or zero value
      *                     is not recommended
-     * @param modifiers    The modifier keys down during event (e.g. shift, ctrl,
-     *                     alt, meta)
+     * @param modifiers    a modifier mask describing the modifier keys and mouse
+     *                     buttons (for example, shift, ctrl, alt, and meta) that
+     *                     are down during the event.
+     *                     Only extended modifiers are allowed to be used as a
+     *                     value for this parameter (see the {@link InputEvent#getModifiersEx}
+     *                     class for the description of extended modifiers).
      *                     Passing negative parameter
      *                     is not recommended.
-     *                     Zero value means that no modifiers were passed.
-     *                     Use either an extended _DOWN_MASK or old _MASK modifiers,
-     *                     however do not mix models in the one event.
-     *                     The extended modifiers are preferred for using
+     *                     Zero value means that no modifiers were passed
      * @param x            The horizontal x coordinate for the mouse location.
      *                       It is allowed to pass negative values
      * @param y            The vertical y coordinate for the mouse location.