changeset 221:5a9dcfdf856d

Merge
author volk
date Sun, 13 Apr 2008 23:56:20 +0400
parents 61ea2d05afba ddfd2acb2347
children 863b81ff642c
files
diffstat 28 files changed, 1200 insertions(+), 493 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/awt/Component.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/Component.java	Sun Apr 13 23:56:20 2008 +0400
@@ -1327,12 +1327,15 @@
             KeyboardFocusManager.clearMostRecentFocusOwner(this);
             synchronized (getTreeLock()) {
                 enabled = false;
-                if (isFocusOwner()) {
+                // A disabled lw container is allowed to contain a focus owner.
+                if ((isFocusOwner() || (containsFocus() && !isLightweight())) &&
+                    KeyboardFocusManager.isAutoFocusTransferEnabled())
+                {
                     // Don't clear the global focus owner. If transferFocus
                     // fails, we want the focus to stay on the disabled
                     // Component so that keyboard traversal, et. al. still
                     // makes sense to the user.
-                    autoTransferFocus(false);
+                    transferFocus(false);
                 }
                 ComponentPeer peer = this.peer;
                 if (peer != null) {
@@ -1493,8 +1496,8 @@
             synchronized (getTreeLock()) {
                 visible = false;
                 mixOnHiding(isLightweight());
-                if (containsFocus()) {
-                    autoTransferFocus(true);
+                if (containsFocus() && KeyboardFocusManager.isAutoFocusTransferEnabled()) {
+                    transferFocus(true);
                 }
                 ComponentPeer peer = this.peer;
                 if (peer != null) {
@@ -6578,12 +6581,8 @@
         }
 
         synchronized (getTreeLock()) {
-            if (isFocusOwner()
-                && KeyboardFocusManager.isAutoFocusTransferEnabled()
-                && !nextFocusHelper())
-            {
-                KeyboardFocusManager.getCurrentKeyboardFocusManager().
-                    clearGlobalFocusOwner();
+            if (isFocusOwner() && KeyboardFocusManager.isAutoFocusTransferEnabledFor(this)) {
+                transferFocus(true);
             }
 
             if (getContainer() != null && isAddNotifyComplete) {
@@ -6718,8 +6717,8 @@
 
         firePropertyChange("focusable", oldFocusable, focusable);
         if (oldFocusable && !focusable) {
-            if (isFocusOwner()) {
-                autoTransferFocus(true);
+            if (isFocusOwner() && KeyboardFocusManager.isAutoFocusTransferEnabled()) {
+                transferFocus(true);
             }
             KeyboardFocusManager.clearMostRecentFocusOwner(this);
         }
@@ -7373,69 +7372,6 @@
         }
     }
 
-    private void autoTransferFocus(boolean clearOnFailure) {
-        Component toTest = KeyboardFocusManager.
-            getCurrentKeyboardFocusManager().getFocusOwner();
-        if (toTest != this) {
-            if (toTest != null) {
-                toTest.autoTransferFocus(clearOnFailure);
-            }
-            return;
-        }
-
-        // Check if there are pending focus requests.  We shouldn't do
-        // auto-transfer if user has already took care of this
-        // component becoming ineligible to hold focus.
-        if (!KeyboardFocusManager.isAutoFocusTransferEnabled()) {
-            return;
-        }
-
-        // the following code will execute only if this Component is the focus
-        // owner
-
-        if (!(isDisplayable() && isVisible() && isEnabled() && isFocusable())) {
-            doAutoTransfer(clearOnFailure);
-            return;
-        }
-
-        toTest = getParent();
-
-        while (toTest != null && !(toTest instanceof Window)) {
-            if (!(toTest.isDisplayable() && toTest.isVisible() &&
-                  (toTest.isEnabled() || toTest.isLightweight()))) {
-                doAutoTransfer(clearOnFailure);
-                return;
-            }
-            toTest = toTest.getParent();
-        }
-    }
-    private void doAutoTransfer(boolean clearOnFailure) {
-        if (focusLog.isLoggable(Level.FINER)) {
-            focusLog.log(Level.FINER, "this = " + this + ", clearOnFailure = " + clearOnFailure);
-        }
-        if (clearOnFailure) {
-            if (!nextFocusHelper()) {
-                if (focusLog.isLoggable(Level.FINER)) {
-                    focusLog.log(Level.FINER, "clear global focus owner");
-                }
-                KeyboardFocusManager.getCurrentKeyboardFocusManager().
-                    clearGlobalFocusOwner();
-            }
-        } else {
-            transferFocus();
-        }
-    }
-
-    /**
-     * Transfers the focus to the next component, as though this Component were
-     * the focus owner.
-     * @see       #requestFocus()
-     * @since     JDK1.1
-     */
-    public void transferFocus() {
-        nextFocus();
-    }
-
     /**
      * Returns the Container which is the focus cycle root of this Component's
      * focus traversal cycle. Each focus traversal cycle has only a single
@@ -7475,31 +7411,51 @@
         return (rootAncestor == container);
     }
 
+    Container getTraversalRoot() {
+        return getFocusCycleRootAncestor();
+    }
+
+    /**
+     * Transfers the focus to the next component, as though this Component were
+     * the focus owner.
+     * @see       #requestFocus()
+     * @since     JDK1.1
+     */
+    public void transferFocus() {
+        nextFocus();
+    }
+
     /**
      * @deprecated As of JDK version 1.1,
      * replaced by transferFocus().
      */
     @Deprecated
     public void nextFocus() {
-        nextFocusHelper();
-    }
-
-    private boolean nextFocusHelper() {
-        Component toFocus = preNextFocusHelper();
+        transferFocus(false);
+    }
+
+    boolean transferFocus(boolean clearOnFailure) {
         if (focusLog.isLoggable(Level.FINER)) {
-            focusLog.log(Level.FINER, "toFocus = " + toFocus);
-        }
-        if (isFocusOwner() && toFocus == this) {
-            return false;
-        }
-        return postNextFocusHelper(toFocus, CausedFocusEvent.Cause.TRAVERSAL_FORWARD);
-    }
-
-    Container getTraversalRoot() {
-        return getFocusCycleRootAncestor();
-    }
-
-    final Component preNextFocusHelper() {
+            focusLog.finer("clearOnFailure = " + clearOnFailure);
+        }
+        Component toFocus = getNextFocusCandidate();
+        boolean res = false;
+        if (toFocus != null && !toFocus.isFocusOwner() && toFocus != this) {
+            res = toFocus.requestFocusInWindow(CausedFocusEvent.Cause.TRAVERSAL_FORWARD);
+        }
+        if (clearOnFailure && !res) {
+            if (focusLog.isLoggable(Level.FINER)) {
+                focusLog.finer("clear global focus owner");
+            }
+            KeyboardFocusManager.getCurrentKeyboardFocusManager().clearGlobalFocusOwner();
+        }
+        if (focusLog.isLoggable(Level.FINER)) {
+            focusLog.finer("returning result: " + res);
+        }
+        return res;
+    }
+
+    final Component getNextFocusCandidate() {
         Container rootAncestor = getTraversalRoot();
         Component comp = this;
         while (rootAncestor != null &&
@@ -7511,18 +7467,19 @@
             rootAncestor = comp.getFocusCycleRootAncestor();
         }
         if (focusLog.isLoggable(Level.FINER)) {
-            focusLog.log(Level.FINER, "comp = " + comp + ", root = " + rootAncestor);
-        }
+            focusLog.finer("comp = " + comp + ", root = " + rootAncestor);
+        }
+        Component candidate = null;
         if (rootAncestor != null) {
             FocusTraversalPolicy policy = rootAncestor.getFocusTraversalPolicy();
             Component toFocus = policy.getComponentAfter(rootAncestor, comp);
             if (focusLog.isLoggable(Level.FINER)) {
-                focusLog.log(Level.FINER, "component after is " + toFocus);
+                focusLog.finer("component after is " + toFocus);
             }
             if (toFocus == null) {
                 toFocus = policy.getDefaultComponent(rootAncestor);
                 if (focusLog.isLoggable(Level.FINER)) {
-                    focusLog.log(Level.FINER, "default component is " + toFocus);
+                    focusLog.finer("default component is " + toFocus);
                 }
             }
             if (toFocus == null) {
@@ -7531,23 +7488,12 @@
                     toFocus = applet;
                 }
             }
-            return toFocus;
-        }
-        return null;
-    }
-
-    static boolean postNextFocusHelper(Component toFocus, CausedFocusEvent.Cause cause) {
-        if (toFocus != null) {
-            if (focusLog.isLoggable(Level.FINER)) {
-                focusLog.log(Level.FINER, "Next component " + toFocus);
-            }
-            boolean res = toFocus.requestFocusInWindow(cause);
-            if (focusLog.isLoggable(Level.FINER)) {
-                focusLog.log(Level.FINER, "Request focus returned " + res);
-            }
-            return res;
-        }
-        return false;
+            candidate = toFocus;
+        }
+        if (focusLog.isLoggable(Level.FINER)) {
+            focusLog.finer("Focus transfer candidate: " + candidate);
+        }
+        return candidate;
     }
 
     /**
@@ -7557,6 +7503,10 @@
      * @since     1.4
      */
     public void transferFocusBackward() {
+        transferFocusBackward(false);
+    }
+
+    boolean transferFocusBackward(boolean clearOnFailure) {
         Container rootAncestor = getTraversalRoot();
         Component comp = this;
         while (rootAncestor != null &&
@@ -7567,6 +7517,7 @@
             comp = rootAncestor;
             rootAncestor = comp.getFocusCycleRootAncestor();
         }
+        boolean res = false;
         if (rootAncestor != null) {
             FocusTraversalPolicy policy = rootAncestor.getFocusTraversalPolicy();
             Component toFocus = policy.getComponentBefore(rootAncestor, comp);
@@ -7574,9 +7525,19 @@
                 toFocus = policy.getDefaultComponent(rootAncestor);
             }
             if (toFocus != null) {
-                toFocus.requestFocusInWindow(CausedFocusEvent.Cause.TRAVERSAL_BACKWARD);
-            }
-        }
+                res = toFocus.requestFocusInWindow(CausedFocusEvent.Cause.TRAVERSAL_BACKWARD);
+            }
+        }
+        if (!res) {
+            if (focusLog.isLoggable(Level.FINER)) {
+                focusLog.finer("clear global focus owner");
+            }
+            KeyboardFocusManager.getCurrentKeyboardFocusManager().clearGlobalFocusOwner();
+        }
+        if (focusLog.isLoggable(Level.FINER)) {
+            focusLog.finer("returning result: " + res);
+        }
+        return res;
     }
 
     /**
@@ -7651,6 +7612,20 @@
         return hasFocus();
     }
 
+    /*
+     * Used to disallow auto-focus-transfer on disposal of the focus owner
+     * in the process of disposing its parent container.
+     */
+    private boolean autoFocusTransferOnDisposal = true;
+
+    void setAutoFocusTransferOnDisposal(boolean value) {
+        autoFocusTransferOnDisposal = value;
+    }
+
+    boolean isAutoFocusTransferOnDisposal() {
+        return autoFocusTransferOnDisposal;
+    }
+
     /**
      * Adds the specified popup menu to the component.
      * @param     popup the popup menu to be added to the component.
--- a/src/share/classes/java/awt/Container.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/Container.java	Sun Apr 13 23:56:20 2008 +0400
@@ -2660,9 +2660,26 @@
         synchronized (getTreeLock()) {
             int ncomponents = this.ncomponents;
             Component component[] = this.component;
-            for (int i = ncomponents-1 ; i >= 0 ; i--) {
-                if( component[i] != null )
-                component[i].removeNotify();
+            for (int i = ncomponents - 1; i >= 0; i--) {
+                if( component[i] != null ) {
+                    // Fix for 6607170.
+                    // We want to suppress focus change on disposal
+                    // of the focused component. But because of focus
+                    // is asynchronous, we should suppress focus change
+                    // on every component in case it receives native focus
+                    // in the process of disposal.
+                    component[i].setAutoFocusTransferOnDisposal(false);
+                    component[i].removeNotify();
+                    component[i].setAutoFocusTransferOnDisposal(true);
+                }
+            }
+            // If some of the children had focus before disposal then it still has.
+            // Auto-transfer focus to the next (or previous) component if auto-transfer
+            // is enabled.
+            if (containsFocus() && KeyboardFocusManager.isAutoFocusTransferEnabledFor(this)) {
+                if (!transferFocus(false)) {
+                    transferFocusBackward(true);
+                }
             }
             if ( dispatcher != null ) {
                 dispatcher.dispose();
--- a/src/share/classes/java/awt/DefaultKeyboardFocusManager.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/DefaultKeyboardFocusManager.java	Sun Apr 13 23:56:20 2008 +0400
@@ -155,12 +155,13 @@
                                    boolean clearOnFailure)
     {
         if (toFocus != vetoedComponent && toFocus.isShowing() && toFocus.isFocusable() &&
-            toFocus.requestFocus(false, CausedFocusEvent.Cause.ROLLBACK)) {
+            toFocus.requestFocus(false, CausedFocusEvent.Cause.ROLLBACK))
+        {
             return true;
         } else {
-            Component nextFocus = toFocus.preNextFocusHelper();
-            if (nextFocus != vetoedComponent
-                && Component.postNextFocusHelper(nextFocus, CausedFocusEvent.Cause.ROLLBACK))
+            Component nextFocus = toFocus.getNextFocusCandidate();
+            if (nextFocus != null && nextFocus != vetoedComponent &&
+                nextFocus.requestFocusInWindow(CausedFocusEvent.Cause.ROLLBACK))
             {
                 return true;
             } else if (clearOnFailure) {
@@ -504,9 +505,16 @@
                 {
                     // we should not accept focus on such component, so reject it.
                     dequeueKeyEvents(-1, newFocusOwner);
-                    if (KeyboardFocusManager.isAutoFocusTransferEnabled())
-                    {
-                        restoreFocus(fe, newFocusedWindow);
+                    if (KeyboardFocusManager.isAutoFocusTransferEnabled()) {
+                        // If FOCUS_GAINED is for a disposed component (however
+                        // it shouldn't happen) its toplevel parent is null. In this
+                        // case we have to try to restore focus in the current focused
+                        // window (for the details: 6607170).
+                        if (newFocusedWindow == null) {
+                            restoreFocus(fe, currentFocusedWindow);
+                        } else {
+                            restoreFocus(fe, newFocusedWindow);
+                        }
                     }
                     break;
                 }
--- a/src/share/classes/java/awt/KeyboardFocusManager.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/KeyboardFocusManager.java	Sun Apr 13 23:56:20 2008 +0400
@@ -2578,6 +2578,10 @@
         }
     }
 
+    static boolean isAutoFocusTransferEnabledFor(Component comp) {
+        return isAutoFocusTransferEnabled() && comp.isAutoFocusTransferOnDisposal();
+    }
+
     /*
      * Used to process exceptions in dispatching focus event (in focusLost/focusGained callbacks).
      * @param ex previously caught exception that may be processed right here, or null
--- a/src/share/classes/java/awt/dnd/DragGestureEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/dnd/DragGestureEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright 1998-2006 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 1998-2008 Sun Microsystems, Inc.  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
@@ -55,9 +55,19 @@
  * platform dependent drag initiating gesture has occurred
  * on the <code>Component</code> that it is tracking.
  *
+ * The {@code action} field of any {@code DragGestureEvent} instance should take one of the following
+ * values:
+ * <ul>
+ * <li> {@code DnDConstants.ACTION_COPY}
+ * <li> {@code DnDConstants.ACTION_MOVE}
+ * <li> {@code DnDConstants.ACTION_LINK}
+ * </ul>
+ * Assigning the value different from listed above will cause an unspecified behavior.
+ *
  * @see java.awt.dnd.DragGestureRecognizer
  * @see java.awt.dnd.DragGestureListener
  * @see java.awt.dnd.DragSource
+ * @see java.awt.dnd.DnDConstants
  */
 
 public class DragGestureEvent extends EventObject {
@@ -65,19 +75,25 @@
     private static final long serialVersionUID = 9080172649166731306L;
 
     /**
-     * Constructs a <code>DragGestureEvent</code> given the
-     * <code>DragGestureRecognizer</code> firing this event,
-     * an <code>int</code> representing
-     * the user's preferred action, a <code>Point</code>
-     * indicating the origin of the drag, and a <code>List</code>
-     * of events that comprise the gesture.
+     * Constructs a <code>DragGestureEvent</code> object given by the
+     * <code>DragGestureRecognizer</code> instance firing this event,
+     * an {@code act} parameter representing
+     * the user's preferred action, an {@code ori} parameter
+     * indicating the origin of the drag, and a {@code List} of
+     * events that comprise the gesture({@code evs} parameter).
      * <P>
      * @param dgr The <code>DragGestureRecognizer</code> firing this event
-     * @param act The the user's preferred action
+     * @param act The user's preferred action.
+     *            For information on allowable values, see
+     *            the class description for {@link DragGestureEvent}
      * @param ori The origin of the drag
      * @param evs The <code>List</code> of events that comprise the gesture
      * <P>
-     * @throws IllegalArgumentException if input parameters are {@code null}
+     * @throws IllegalArgumentException if any parameter equals {@code null}
+     * @throws IllegalArgumentException if the act parameter does not comply with
+     *                                  the values given in the class
+     *                                  description for {@link DragGestureEvent}
+     * @see java.awt.dnd.DnDConstants
      */
 
     public DragGestureEvent(DragGestureRecognizer dgr, int act, Point ori,
--- a/src/share/classes/java/awt/dnd/DropTargetEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/dnd/DropTargetEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -45,10 +45,13 @@
     private static final long serialVersionUID = 2821229066521922993L;
 
     /**
-     * Construct a <code>DropTargetEvent</code> with
-     * a specified <code>DropTargetContext</code>.
+     * Construct a <code>DropTargetEvent</code> object with
+     * the specified <code>DropTargetContext</code>.
      * <P>
-     * @param dtc the <code>DropTargetContext</code>
+     * @param dtc The <code>DropTargetContext</code>
+     * @throws NullPointerException if {@code dtc} equals {@code null}.
+     * @see #getSource()
+     * @see #getDropTargetContext()
      */
 
     public DropTargetEvent(DropTargetContext dtc) {
--- a/src/share/classes/java/awt/event/ActionEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/ActionEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright 1996-2006 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 1996-2008 Sun Microsystems, Inc.  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
@@ -45,6 +45,10 @@
  * is therefore spared the details of processing individual mouse movements
  * and mouse clicks, and can instead process a "meaningful" (semantic)
  * event like "button pressed".
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ActionEvent} instance is not
+ * in the range from {@code ACTION_FIRST} to {@code ACTION_LAST}.
  *
  * @see ActionListener
  * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/eventmodel.html">Tutorial: Java 1.1 Event Model</a>
@@ -134,18 +138,22 @@
     /**
      * Constructs an <code>ActionEvent</code> object.
      * <p>
-     * Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      * A <code>null</code> <code>command</code> string is legal,
      * but not recommended.
      *
-     * @param source  the object that originated the event
-     * @param id      an integer that identifies the event
-     * @param command a string that may specify a command (possibly one
+     * @param source  The object that originated the event
+     * @param id      An integer that identifies the event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ActionEvent}
+     * @param command A string that may specify a command (possibly one
      *                of several) associated with the event
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getActionCommand()
      */
     public ActionEvent(Object source, int id, String command) {
         this(source, id, command, 0);
@@ -154,19 +162,27 @@
     /**
      * Constructs an <code>ActionEvent</code> object with modifier keys.
      * <p>
-     * Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      * A <code>null</code> <code>command</code> string is legal,
      * but not recommended.
      *
-     * @param source    the object that originated the event
-     * @param id        an integer that identifies the event
-     * @param command   a string that may specify a command (possibly one
-     *                  of several) associated with the event
-     * @param modifiers the modifier keys held down during this action
+     * @param source  The object that originated the event
+     * @param id      An integer that identifies the event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ActionEvent}
+     * @param command A string that may specify a command (possibly one
+     *                of several) associated with the event
+     * @param modifiers The modifier keys down during event
+     *                  (shift, ctrl, alt, meta).
+     *                  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()
+     * @see #getActionCommand()
+     * @see #getModifiers()
      */
     public ActionEvent(Object source, int id, String command, int modifiers) {
         this(source, id, command, 0, modifiers);
@@ -176,20 +192,31 @@
      * Constructs an <code>ActionEvent</code> object with the specified
      * modifier keys and timestamp.
      * <p>
-     * Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      * A <code>null</code> <code>command</code> string is legal,
      * but not recommended.
      *
-     * @param source    the object that originated the event
-     * @param id        an integer that identifies the event
-     * @param command   a string that may specify a command (possibly one
-     *                  of several) associated with the event
-     * @param when      the time the event occurred
-     * @param modifiers the modifier keys held down during this action
+     * @param source    The object that originated the event
+     * @param id      An integer that identifies the event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ActionEvent}
+     * @param command A string that may specify a command (possibly one
+     *                of several) associated with the event
+     * @param modifiers The modifier keys down during event
+     *                  (shift, ctrl, alt, meta).
+     *                  Passing negative parameter is not recommended.
+     *                  Zero value means that no modifiers were passed
+     * @param when   A long that gives the time the event occurred.
+     *               Passing negative or zero value
+     *               is not recommended
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getActionCommand()
+     * @see #getModifiers()
+     * @see #getWhen()
      *
      * @since 1.4
      */
--- a/src/share/classes/java/awt/event/AdjustmentEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/AdjustmentEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -29,7 +29,25 @@
 import java.awt.AWTEvent;
 
 /**
- * The adjustment event emitted by Adjustable objects.
+ * The adjustment event emitted by Adjustable objects like
+ * {@link java.awt.Scrollbar} and {@link java.awt.ScrollPane}.
+ * When the user changes the value of the scrolling component,
+ * it receives an instance of {@code AdjustmentEvent}.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code AdjustmentEvent} instance is not
+ * in the range from {@code ADJUSTMENT_FIRST} to {@code ADJUSTMENT_LAST}.
+ * <p>
+ * The {@code type} of any {@code AdjustmentEvent} instance takes one of the following
+ * values:
+ *                     <ul>
+ *                     <li> {@code UNIT_INCREMENT}
+ *                     <li> {@code UNIT_DECREMENT}
+ *                     <li> {@code BLOCK_INCREMENT}
+ *                     <li> {@code BLOCK_DECREMENT}
+ *                     <li> {@code TRACK}
+ *                     </ul>
+ * Assigning the value different from listed above will cause an unspecified behavior.
  * @see java.awt.Adjustable
  * @see AdjustmentListener
  *
@@ -130,17 +148,24 @@
      * Constructs an <code>AdjustmentEvent</code> object with the
      * specified <code>Adjustable</code> source, event type,
      * adjustment type, and value.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior.  This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the <code>Adjustable</code> object where the
+     * @param source The <code>Adjustable</code> object where the
      *               event originated
-     * @param id     the event type
-     * @param type   the adjustment type
-     * @param value  the current value of the adjustment
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link AdjustmentEvent}
+     * @param type   An integer indicating the adjustment type.
+     *                     For information on allowable values, see
+     *                     the class description for {@link AdjustmentEvent}
+     * @param value  The current value of the adjustment
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getAdjustmentType()
+     * @see #getValue()
      */
     public AdjustmentEvent(Adjustable source, int id, int type, int value) {
         this(source, id, type, value, false);
@@ -149,22 +174,29 @@
     /**
      * Constructs an <code>AdjustmentEvent</code> object with the
      * specified Adjustable source, event type, adjustment type, and value.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior.  This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
-
      *
-     * @param source the <code>Adjustable</code> object where the
+     * @param source The <code>Adjustable</code> object where the
      *               event originated
-     * @param id     the event type
-     * @param type   the adjustment type
-     * @param value  the current value of the adjustment
-     * @param isAdjusting <code>true</code> if the event is one
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link AdjustmentEvent}
+     * @param type   An integer indicating the adjustment type.
+     *                     For information on allowable values, see
+     *                     the class description for {@link AdjustmentEvent}
+     * @param value  The current value of the adjustment
+     * @param isAdjusting A boolean that equals <code>true</code> if the event is one
      *               of a series of multiple adjusting events,
      *               otherwise <code>false</code>
      * @throws IllegalArgumentException if <code>source</code> is null
      * @since 1.4
+     * @see #getSource()
+     * @see #getID()
+     * @see #getAdjustmentType()
+     * @see #getValue()
+     * @see #getValueIsAdjusting()
      */
     public AdjustmentEvent(Adjustable source, int id, int type, int value, boolean isAdjusting) {
         super(source, id);
--- a/src/share/classes/java/awt/event/ComponentEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/ComponentEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -52,6 +52,10 @@
  * (<code>ComponentAdapter</code> objects implement the
  * <code>ComponentListener</code> interface.) Each such listener object
  * gets this <code>ComponentEvent</code> when the event occurs.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ComponentEvent} instance is not
+ * in the range from {@code COMPONENT_FIRST} to {@code COMPONENT_LAST}.
  *
  * @see ComponentAdapter
  * @see ComponentListener
@@ -99,14 +103,17 @@
 
     /**
      * Constructs a <code>ComponentEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the <code>Component</code> that originated the event
-     * @param id     an integer indicating the type of event
+     * @param source The <code>Component</code> that originated the event
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ComponentEvent}
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getComponent()
+     * @see #getID()
      */
     public ComponentEvent(Component source, int id) {
         super(source, id);
--- a/src/share/classes/java/awt/event/ContainerEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/ContainerEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -45,6 +45,10 @@
  * (<code>ContainerAdapter</code> objects implement the
  * <code>ContainerListener</code> interface.) Each such listener object
  * gets this <code>ContainerEvent</code> when the event occurs.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ContainerEvent} instance is not
+ * in the range from {@code CONTAINER_FIRST} to {@code CONTAINER_LAST}.
  *
  * @see ContainerAdapter
  * @see ContainerListener
@@ -92,16 +96,20 @@
 
     /**
      * Constructs a <code>ContainerEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the <code>Component</code> object (container)
+     * @param source The <code>Component</code> object (container)
      *               that originated the event
-     * @param id     an integer indicating the type of event
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ContainerEvent}
      * @param child  the component that was added or removed
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getContainer()
+     * @see #getID()
+     * @see #getChild()
      */
     public ContainerEvent(Component source, int id, Component child) {
         super(source, id);
--- a/src/share/classes/java/awt/event/FocusEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/FocusEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -50,6 +50,10 @@
  * reactivated. Both permanent and temporary focus events are delivered using
  * the FOCUS_GAINED and FOCUS_LOST event ids; the level may be distinguished in
  * the event using the isTemporary() method.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code FocusEvent} instance is not
+ * in the range from {@code FOCUS_FIRST} to {@code FOCUS_LAST}.
  *
  * @see FocusAdapter
  * @see FocusListener
@@ -121,18 +125,23 @@
      * application, with a Java application in a different VM,
      * or with no other <code>Component</code>, then the opposite
      * <code>Component</code> is <code>null</code>.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source     the <code>Component</code> that originated the event
-     * @param id         <code>FOCUS_GAINED</code> or <code>FOCUS_LOST</code>
-     * @param temporary  <code>true</code> if the focus change is temporary;
+     * @param source     The <code>Component</code> that originated the event
+     * @param id         An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link FocusEvent}
+     * @param temporary  Equals <code>true</code> if the focus change is temporary;
      *                   <code>false</code> otherwise
-     * @param opposite   the other Component involved in the focus change,
+     * @param opposite   The other Component involved in the focus change,
      *                   or <code>null</code>
-     * @throws IllegalArgumentException if <code>source</code> is null
+     * @throws IllegalArgumentException if <code>source</code> equals {@code null}
+     * @see #getSource()
+     * @see #getID()
+     * @see #isTemporary()
+     * @see #getOppositeComponent()
      * @since 1.4
      */
     public FocusEvent(Component source, int id, boolean temporary,
@@ -145,16 +154,20 @@
     /**
      * Constructs a <code>FocusEvent</code> object and identifies
      * whether or not the change is temporary.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Component</code> that originated the event
-     * @param id        an integer indicating the type of event
-     * @param temporary <code>true</code> if the focus change is temporary;
+     * @param source    The <code>Component</code> that originated the event
+     * @param id        An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link FocusEvent}
+     * @param temporary Equals <code>true</code> if the focus change is temporary;
      *                  <code>false</code> otherwise
-     * @throws IllegalArgumentException if <code>source</code> is null
+     * @throws IllegalArgumentException if <code>source</code> equals {@code null}
+     * @see #getSource()
+     * @see #getID()
+     * @see #isTemporary()
      */
     public FocusEvent(Component source, int id, boolean temporary) {
         this(source, id, temporary, null);
@@ -163,14 +176,17 @@
     /**
      * Constructs a <code>FocusEvent</code> object and identifies it
      * as a permanent change in focus.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Component</code> that originated the event
-     * @param id        an integer indicating the type of event
-     * @throws IllegalArgumentException if <code>source</code> is null
+     * @param source    The <code>Component</code> that originated the event
+     * @param id        An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link FocusEvent}
+     * @throws IllegalArgumentException if <code>source</code> equals {@code null}
+     * @see #getSource()
+     * @see #getID()
      */
     public FocusEvent(Component source, int id) {
         this(source, id, false);
--- a/src/share/classes/java/awt/event/HierarchyEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/HierarchyEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 1999-2008 Sun Microsystems, Inc.  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
@@ -31,7 +31,7 @@
 
 /**
  * An event which indicates a change to the <code>Component</code>
- * hierarchy to which a <code>Component</code> belongs.
+ * hierarchy to which <code>Component</code> belongs.
  * <ul>
  * <li>Hierarchy Change Events (HierarchyListener)
  *     <ul>
@@ -58,16 +58,30 @@
  * Container is added, removed, moved, or resized, and passed down the
  * hierarchy. It is also generated by a Component object when that object's
  * <code>addNotify</code>, <code>removeNotify</code>, <code>show</code>, or
- * <code>hide</code> method is called. ANCESTOR_MOVED and ANCESTOR_RESIZED
+ * <code>hide</code> method is called. The {@code ANCESTOR_MOVED} and
+ * {@code ANCESTOR_RESIZED}
  * events are dispatched to every <code>HierarchyBoundsListener</code> or
  * <code>HierarchyBoundsAdapter</code> object which registered to receive
  * such events using the Component's <code>addHierarchyBoundsListener</code>
  * method. (<code>HierarchyBoundsAdapter</code> objects implement the <code>
- * HierarchyBoundsListener</code> interface.) HIERARCHY_CHANGED events are
+ * HierarchyBoundsListener</code> interface.) The {@code HIERARCHY_CHANGED} events are
  * dispatched to every <code>HierarchyListener</code> object which registered
  * to receive such events using the Component's <code>addHierarchyListener
  * </code> method. Each such listener object gets this <code>HierarchyEvent
  * </code> when the event occurs.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code HierarchyEvent} instance is not
+ * in the range from {@code HIERARCHY_FIRST} to {@code HIERARCHY_LAST}.
+ * <br>
+ * The {@code changeFlags} parameter of any {@code HierarchyEvent} instance takes one of the following
+ * values:
+ * <ul>
+ * <li> {@code HierarchyEvent.PARENT_CHANGED}
+ * <li> {@code HierarchyEvent.DISPLAYABILITY_CHANGED}
+ * <li> {@code HierarchyEvent.SHOWING_CHANGED}
+ * </ul>
+ * Assigning the value different from listed above will cause unspecified behavior.
  *
  * @author      David Mendenhall
  * @see         HierarchyListener
@@ -108,20 +122,20 @@
     public static final int HIERARCHY_LAST = ANCESTOR_RESIZED;
 
     /**
-     * Indicates that the <code>HIERARCHY_CHANGED</code> event
+     * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
      * was generated by a reparenting operation.
      */
     public static final int PARENT_CHANGED = 0x1;
 
     /**
-     * Indicates that the <code>HIERARCHY_CHANGED</code> event
-     * was generated due to a change in the displayability
-     * of the hierarchy.  To discern the
-     * current displayability of the hierarchy, call
-     * <code>Component.isDisplayable</code>. Displayability changes occur
-     * in response to explicit or implicit calls to
+     * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
+     * was generated due to the changing of the hierarchy displayability.
+     * To discern the
+     * current displayability of the hierarchy, call the
+     * <code>Component.isDisplayable</code> method. Displayability changes occur
+     * in response to explicit or implicit calls of the
      * <code>Component.addNotify</code> and
-     * <code>Component.removeNotify</code>.
+     * <code>Component.removeNotify</code> methods.
      *
      * @see java.awt.Component#isDisplayable()
      * @see java.awt.Component#addNotify()
@@ -130,15 +144,15 @@
     public static final int DISPLAYABILITY_CHANGED = 0x2;
 
     /**
-     * Indicates that the <code>HIERARCHY_CHANGED</code> event
-     * was generated due to a change in the showing state
-     * of the hierarchy. To discern the
-     * current showing state of the hierarchy, call
-     * <code>Component.isShowing</code>. Showing state changes occur
+     * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
+     * was generated due to the changing of the hierarchy showing state.
+     * To discern the
+     * current showing state of the hierarchy, call the
+     * <code>Component.isShowing</code> method. Showing state changes occur
      * when either the displayability or visibility of the
      * hierarchy occurs. Visibility changes occur in response to explicit
-     * or implicit calls to <code>Component.show</code> and
-     * <code>Component.hide</code>.
+     * or implicit calls of the <code>Component.show</code> and
+     * <code>Component.hide</code> methods.
      *
      * @see java.awt.Component#isShowing()
      * @see java.awt.Component#addNotify()
@@ -155,20 +169,26 @@
     /**
      * Constructs an <code>HierarchyEvent</code> object to identify a
      * change in the <code>Component</code> hierarchy.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source          the <code>Component</code> object that
+     * @param source          The <code>Component</code> object that
      *                        originated the event
-     * @param id              an integer indicating the type of event
-     * @param changed         the <code>Component</code> at the top of
+     * @param id              An integer indicating the type of event.
+     *                        For information on allowable values, see
+     *                        the class description for {@link HierarchyEvent}
+     * @param changed         The <code>Component</code> at the top of
      *                        the hierarchy which was changed
-     * @param changedParent   the parent of <code>changed</code>; this
+     * @param changedParent   The parent of the <code>changed</code> component.
+     *                        This
      *                        may be the parent before or after the
      *                        change, depending on the type of change
-     * @throws IllegalArgumentException if <code>source</code> is null
+     * @throws IllegalArgumentException if <code>source</code> is {@code null}
+     * @see #getSource()
+     * @see #getID()
+     * @see #getChanged()
+     * @see #getChangedParent()
      */
     public HierarchyEvent(Component source, int id, Component changed,
                           Container changedParent) {
@@ -180,23 +200,32 @@
     /**
      * Constructs an <code>HierarchyEvent</code> object to identify
      * a change in the <code>Component</code> hierarchy.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source          the <code>Component</code> object that
+     * @param source          The <code>Component</code> object that
      *                        originated the event
-     * @param id              an integer indicating the type of event
-     * @param changed         the <code>Component</code> at the top
+     * @param id              An integer indicating the type of event.
+     *                        For information on allowable values, see
+     *                        the class description for {@link HierarchyEvent}
+     * @param changed         The <code>Component</code> at the top
      *                        of the hierarchy which was changed
-     * @param changedParent   the parent of <code>changed</code>; this
+     * @param changedParent   The parent of the <code>changed</code> component.
+     *                        This
      *                        may be the parent before or after the
      *                        change, depending on the type of change
-     * @param changeFlags     a bitmask which indicates the type(s) of
-     *                        <code>HIERARCHY_CHANGED</code> events
-     *                        represented in this event object
+     * @param changeFlags     A bitmask which indicates the type(s) of
+     *                        the <code>HIERARCHY_CHANGED</code> events
+     *                        represented in this event object.
+     *                        For information on allowable values, see
+     *                        the class description for {@link HierarchyEvent}
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getChanged()
+     * @see #getChangedParent()
+     * @see #getChangeFlags()
      */
     public HierarchyEvent(Component source, int id, Component changed,
                           Container changedParent, long changeFlags) {
--- a/src/share/classes/java/awt/event/InputEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/InputEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -208,17 +208,32 @@
     /**
      * Constructs an InputEvent object with the specified source component,
      * modifiers, and type.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
      * @param source the object where the event originated
-     * @param id the event type
-     * @param when the time the event occurred
-     * @param modifiers represents the modifier keys and mouse buttons down
-     *                  while the event occurred
+     * @param id           the integer that identifies the event type.
+     *                     It is allowed to pass as parameter any value that
+     *                     allowed for some subclass of {@code InputEvent} class.
+     *                     Passing in the value different from those values result
+     *                     in unspecified behavior
+     * @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
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
      */
     InputEvent(Component source, int id, long when, int modifiers) {
         super(source, id);
@@ -285,7 +300,8 @@
     }
 
     /**
-     * Returns the timestamp of when this event occurred.
+     * Returns the difference in milliseconds between the timestamp of when this event occurred and
+     * midnight, January 1, 1970 UTC.
      */
     public long getWhen() {
         return when;
@@ -358,7 +374,12 @@
      * Returns a String describing the extended modifier keys and
      * mouse buttons, such as "Shift", "Button1", or "Ctrl+Shift".
      * These strings can be localized by changing the
-     * awt.properties file.
+     * <code>awt.properties</code> file.
+     * <p>
+     * Note that passing negative parameter is incorrect,
+     * and will cause the returning an unspecified string.
+     * Zero parameter means that no modifiers were passed and will
+     * cause the returning an empty string.
      *
      * @param modifiers a modifier mask describing the extended
        *                modifier keys and mouse buttons for the event
--- a/src/share/classes/java/awt/event/InvocationEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/InvocationEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright 1998-2006 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 1998-2008 Sun Microsystems, Inc.  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
@@ -39,6 +39,10 @@
  * can use this fact to write replacement functions for <code>invokeLater
  * </code> and <code>invokeAndWait</code> without writing special-case code
  * in any <code>AWTEventListener</code> objects.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code InvocationEvent} instance is not
+ * in the range from {@code INVOCATION_FIRST} to {@code INVOCATION_LAST}.
  *
  * @author      Fred Ecks
  * @author      David Mendenhall
@@ -123,12 +127,13 @@
      * <p> This method throws an <code>IllegalArgumentException</code>
      * if <code>source</code> is <code>null</code>.
      *
-     * @param source    the <code>Object</code> that originated the event
-     * @param runnable  the <code>Runnable</code> whose <code>run</code>
+     * @param source    The <code>Object</code> that originated the event
+     * @param runnable  The <code>Runnable</code> whose <code>run</code>
      *                  method will be executed
      * @throws IllegalArgumentException if <code>source</code> is null
      *
-     * @see     #InvocationEvent(Object, Runnable, Object, boolean)
+     * @see #getSource()
+     * @see #InvocationEvent(Object, Runnable, Object, boolean)
      */
     public InvocationEvent(Object source, Runnable runnable) {
         this(source, runnable, null, false);
@@ -147,15 +152,15 @@
      * <p>This method throws an <code>IllegalArgumentException</code>
      * if <code>source</code> is <code>null</code>.
      *
-     * @param source            the <code>Object</code> that originated
+     * @param source            The <code>Object</code> that originated
      *                          the event
-     * @param runnable          the <code>Runnable</code> whose
+     * @param runnable          The <code>Runnable</code> whose
      *                          <code>run</code> method will be
      *                          executed
-     * @param notifier          the Object whose <code>notifyAll</code>
+     * @param notifier          The {@code Object} whose <code>notifyAll</code>
      *                          method will be called after
      *                          <code>Runnable.run</code> has returned
-     * @param catchThrowables   specifies whether <code>dispatch</code>
+     * @param catchThrowables   Specifies whether <code>dispatch</code>
      *                          should catch Throwable when executing
      *                          the <code>Runnable</code>'s <code>run</code>
      *                          method, or should instead propagate those
@@ -163,6 +168,7 @@
      *                          dispatch loop
      * @throws IllegalArgumentException if <code>source</code> is null
      *
+     * @see #getSource()
      * @see     #InvocationEvent(Object, int, Runnable, Object, boolean)
      */
     public InvocationEvent(Object source, Runnable runnable, Object notifier,
@@ -176,26 +182,29 @@
      * method when dispatched.  If notifier is non-<code>null</code>,
      * <code>notifyAll</code> will be called on it
      * immediately after <code>run</code> returns.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source            the <code>Object</code> that originated
+     * @param source            The <code>Object</code> that originated
      *                          the event
-     * @param id                the ID for the event
-     * @param runnable          the <code>Runnable</code> whose
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link InvocationEvent}
+     * @param runnable          The <code>Runnable</code> whose
      *                          <code>run</code> method will be executed
-     * @param notifier          the <code>Object</code> whose <code>notifyAll</code>
+     * @param notifier          The <code>Object</code> whose <code>notifyAll</code>
      *                          method will be called after
      *                          <code>Runnable.run</code> has returned
-     * @param catchThrowables   specifies whether <code>dispatch</code>
+     * @param catchThrowables   Specifies whether <code>dispatch</code>
      *                          should catch Throwable when executing the
      *                          <code>Runnable</code>'s <code>run</code>
      *                          method, or should instead propagate those
      *                          Throwables to the EventDispatchThread's
      *                          dispatch loop
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
      */
     protected InvocationEvent(Object source, int id, Runnable runnable,
                               Object notifier, boolean catchThrowables) {
--- a/src/share/classes/java/awt/event/ItemEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/ItemEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -41,6 +41,18 @@
  * spared the details of processing individual mouse movements and mouse
  * clicks, and can instead process a "meaningful" (semantic) event like
  * "item selected" or "item deselected".
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ItemEvent} instance is not
+ * in the range from {@code ITEM_FIRST} to {@code ITEM_LAST}.
+ * <p>
+ * The {@code stateChange} of any {@code ItemEvent} instance takes one of the following
+ * values:
+ *                     <ul>
+ *                     <li> {@code ItemEvent.SELECTED}
+ *                     <li> {@code ItemEvent.DESELECTED}
+ *                     </ul>
+ * Assigning the value different from listed above will cause an unspecified behavior.
  *
  * @author Carl Quinn
  *
@@ -101,19 +113,24 @@
 
     /**
      * Constructs an <code>ItemEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the <code>ItemSelectable</code> object
+     * @param source The <code>ItemSelectable</code> object
      *               that originated the event
-     * @param id     an integer that identifies the event type
-     * @param item   an object -- the item affected by the event
-     * @param stateChange
-     *               an integer that indicates whether the item was
-     *               selected or deselected
+     * @param id           The integer that identifies the event type.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ItemEvent}
+     * @param item   An object -- the item affected by the event
+     * @param stateChange  An integer that indicates whether the item was
+     *               selected or deselected.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ItemEvent}
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getItemSelectable()
+     * @see #getID()
+     * @see #getStateChange()
      */
     public ItemEvent(ItemSelectable source, int id, Object item, int stateChange) {
         super(source, id);
--- a/src/share/classes/java/awt/event/KeyEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/KeyEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright 1996-2007 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 1996-2008 Sun Microsystems, Inc.  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
@@ -128,6 +128,10 @@
  * (VK_ENTER, VK_BACK_SPACE, and VK_TAB), do not rely on the values of the VK_
  * constants.  Sun reserves the right to change these values as needed
  * to accomodate a wider range of keyboards in the future.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code KeyEvent} instance is not
+ * in the range from {@code KEY_FIRST} to {@code KEY_LAST}.
  *
  * @author Carl Quinn
  * @author Amy Fowler
@@ -914,27 +918,32 @@
 
     /**
      * Constructs a <code>KeyEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Component</code> that originated the event
-     * @param id        an integer identifying the type of event
-     * @param when      a long integer that specifies the time the event
-     *                  occurred
-     * @param modifiers the modifier keys down during event (shift, ctrl,
-     *                  alt, meta)
-     *                  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 keyCode   the integer code for an actual key, or VK_UNDEFINED
+     * @param source    The <code>Component</code> that originated the event
+     * @param id              An integer indicating the type of event.
+     *                  For information on allowable values, see
+     *                  the class description for {@link KeyEvent}
+     * @param when      A long integer that specifies the time the event
+     *                  occurred.
+     *                     Passing negative or zero value
+     *                     is not recommended
+     * @param modifiers The modifier keys down during event (shift, ctrl,
+     *                  alt, meta).
+     *                     Passing negative value
+     *                     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
+     * @param keyCode   The integer code for an actual key, or VK_UNDEFINED
      *                  (for a key-typed event)
-     * @param keyChar   the Unicode character generated by this event, or
+     * @param keyChar   The Unicode character generated by this event, or
      *                  CHAR_UNDEFINED (for key-pressed and key-released
      *                  events which do not map to a valid Unicode character)
-     * @param keyLocation  identifies the key location.  The only legal
+     * @param keyLocation  Identifies the key location.  The only legal
      *        values are <code>KEY_LOCATION_UNKNOWN</code>,
      *        <code>KEY_LOCATION_STANDARD</code>, <code>KEY_LOCATION_LEFT</code>,
      *        <code>KEY_LOCATION_RIGHT</code>, and <code>KEY_LOCATION_NUMPAD</code>.
@@ -948,6 +957,13 @@
      *     or if <code>keyLocation</code> is not one of the legal
      *       values enumerated above.
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
+     * @see #getKeyCode()
+     * @see #getKeyChar()
+     * @see #getKeyLocation()
      * @since 1.4
      */
     public KeyEvent(Component source, int id, long when, int modifiers,
@@ -982,24 +998,29 @@
 
     /**
      * Constructs a <code>KeyEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Component</code> that originated the event
-     * @param id        an integer identifying the type of event
-     * @param when      a long integer that specifies the time the event
-     *                  occurred
-     * @param modifiers the modifier keys down during event (shift, ctrl,
-     *                  alt, meta)
-     *                  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 keyCode   the integer code for an actual key, or VK_UNDEFINED
+     * @param source    The <code>Component</code> that originated the event
+     * @param id              An integer indicating the type of event.
+     *                  For information on allowable values, see
+     *                  the class description for {@link KeyEvent}
+     * @param when      A long integer that specifies the time the event
+     *                  occurred.
+     *                     Passing negative or zero value
+     *                     is not recommended
+     * @param modifiers The modifier keys down during event (shift, ctrl,
+     *                  alt, meta).
+     *                     Passing negative value
+     *                     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
+     * @param keyCode   The integer code for an actual key, or VK_UNDEFINED
      *                  (for a key-typed event)
-     * @param keyChar   the Unicode character generated by this event, or
+     * @param keyChar   The Unicode character generated by this event, or
      *                  CHAR_UNDEFINED (for key-pressed and key-released
      *                  events which do not map to a valid Unicode character)
      * @throws IllegalArgumentException  if <code>id</code> is
@@ -1008,6 +1029,12 @@
      *     <code>KEY_TYPED</code> and <code>keyCode</code> is not
      *     <code>VK_UNDEFINED</code>
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
+     * @see #getKeyCode()
+     * @see #getKeyChar()
      */
     public KeyEvent(Component source, int id, long when, int modifiers,
                     int keyCode, char keyChar) {
--- a/src/share/classes/java/awt/event/MouseEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/MouseEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -159,6 +159,11 @@
  * The reported coordinates for mouse drag events are clipped to fit within the
  * bounds of the virtual device associated with the <code>Component</code>.
  * </ul>
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code MouseEvent} instance is not
+ * in the range from {@code MOUSE_FIRST} to {@code MOUSE_LAST}-1
+ * ({@code MOUSE_WHEEL} is not acceptable).
  *
  * @author Carl Quinn
  *
@@ -418,8 +423,7 @@
      * specified source component,
      * type, modifiers, coordinates, and click count.
      * <p>
-     * Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior.  Creating an invalid event (such
+     * Creating an invalid event (such
      * as by using more than one of the old _MASKs, or modifier/button
      * values which don't match) results in unspecified behavior.
      * An invocation of the form
@@ -435,28 +439,44 @@
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source       the <code>Component</code> that originated the event
-     * @param id           the integer that identifies the event
-     * @param when         a long int that gives the time the event occurred
-     * @param modifiers    the modifier keys down during event (e.g. shift, ctrl,
+     * @param source       The <code>Component</code> that originated the event
+     * @param id              An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link MouseEvent}
+     * @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)
-     *                     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 x            the horizontal x coordinate for the mouse location
-     * @param y            the vertical y coordinate for the mouse location
-     * @param clickCount   the number of mouse clicks associated with event
-     * @param popupTrigger a boolean, true if this event is a trigger for a
-     *                     popup menu
-     * @param button       which of the mouse buttons has changed state.
-     *                      <code>NOBUTTON</code>,
-     *                      <code>BUTTON1</code>,
-     *                      <code>BUTTON2</code> or
-     *                      <code>BUTTON3</code>.
+     *                     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
+     * @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.
+     *                       It is allowed to pass negative values
+     * @param clickCount   The number of mouse clicks associated with event.
+     *                       Passing negative value
+     *                       is not recommended
+     * @param popupTrigger A boolean that equals {@code true} if this event
+     *                     is a trigger for a popup menu
+     * @param button       An integer that indicates, which of the mouse buttons has
+     *                     changed its state
      * @throws IllegalArgumentException if an invalid <code>button</code>
      *            value is passed in
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
+     * @see #getX()
+     * @see #getY()
+     * @see #getClickCount()
+     * @see #isPopupTrigger()
+     * @see #getButton()
      * @since 1.4
      */
     public MouseEvent(Component source, int id, long when, int modifiers,
@@ -479,8 +499,6 @@
      * Constructs a <code>MouseEvent</code> object with the
      * specified source component,
      * type, modifiers, coordinates, and click count.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior.
      * An invocation of the form
      * <tt>MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger)</tt>
      * behaves in exactly the same way as the invocation
@@ -493,21 +511,39 @@
      * This method throws an <code>IllegalArgumentException</code>
      * if <code>source</code> is <code>null</code>.
      *
-     * @param source       the <code>Component</code> that originated the event
-     * @param id           the integer that identifies the event
-     * @param when         a long int that gives the time the event occurred
-     * @param modifiers    the modifier keys down during event (e.g. shift, ctrl,
+     * @param source       The <code>Component</code> that originated the event
+     * @param id              An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link MouseEvent}
+     * @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)
-     *                     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 x            the horizontal x coordinate for the mouse location
-     * @param y            the vertical y coordinate for the mouse location
-     * @param clickCount   the number of mouse clicks associated with event
-     * @param popupTrigger a boolean, true if this event is a trigger for a
-     *                     popup menu
+     *                     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
+     * @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.
+     *                       It is allowed to pass negative values
+     * @param clickCount   The number of mouse clicks associated with event.
+     *                       Passing negative value
+     *                       is not recommended
+     * @param popupTrigger A boolean that equals {@code true} if this event
+     *                     is a trigger for a popup menu
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
+     * @see #getX()
+     * @see #getY()
+     * @see #getClickCount()
+     * @see #isPopupTrigger()
      */
      public MouseEvent(Component source, int id, long when, int modifiers,
                       int x, int y, int clickCount, boolean popupTrigger) {
@@ -520,8 +556,7 @@
      * specified source component,
      * type, modifiers, coordinates, absolute coordinates, and click count.
      * <p>
-     * Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior.  Creating an invalid event (such
+     * Creating an invalid event (such
      * as by using more than one of the old _MASKs, or modifier/button
      * values which don't match) results in unspecified behavior.
      * Even if inconsistent values for relative and absolute coordinates are
@@ -531,30 +566,50 @@
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source       the <code>Component</code> that originated the event
-     * @param id           the integer that identifies the event
-     * @param when         a long int that gives the time the event occurred
-     * @param modifiers    the modifier keys down during event (e.g. shift, ctrl,
+     * @param source       The <code>Component</code> that originated the event
+     * @param id              An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link MouseEvent}
+     * @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)
-     *                     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 x            the horizontal x coordinate for the mouse location
-     * @param y            the vertical y coordinate for the mouse location
-     * @param xAbs         the absolute horizontal x coordinate for the mouse location
-     * @param yAbs         the absolute vertical y coordinate for the mouse location
-     * @param clickCount   the number of mouse clicks associated with event
-     * @param popupTrigger a boolean, true if this event is a trigger for a
-     *                     popup menu
-     * @param button       which of the mouse buttons has changed state.
-     *                      <code>NOBUTTON</code>,
-     *                      <code>BUTTON1</code>,
-     *                      <code>BUTTON2</code> or
-     *                      <code>BUTTON3</code>.
+     *                     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
+     * @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.
+     *                       It is allowed to pass negative values
+     * @param xAbs           The absolute horizontal x coordinate for the mouse location
+     *                       It is allowed to pass negative values
+     * @param yAbs           The absolute vertical y coordinate for the mouse location
+     *                       It is allowed to pass negative values
+     * @param clickCount   The number of mouse clicks associated with event.
+     *                       Passing negative value
+     *                       is not recommended
+     * @param popupTrigger A boolean that equals {@code true} if this event
+     *                     is a trigger for a popup menu
+     * @param button       An integer that indicates, which of the mouse buttons has
+     *                     changed its state
      * @throws IllegalArgumentException if an invalid <code>button</code>
      *            value is passed in
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
+     * @see #getX()
+     * @see #getY()
+     * @see #getXOnScreen()
+     * @see #getYOnScreen()
+     * @see #getClickCount()
+     * @see #isPopupTrigger()
+     * @see #getButton()
      * @since 1.6
      */
     public MouseEvent(Component source, int id, long when, int modifiers,
@@ -675,21 +730,26 @@
     }
 
     /**
-     * Returns a <code>String</code> describing the modifier keys and
+     * Returns a <code>String</code> instance describing the modifier keys and
      * mouse buttons that were down during the event, such as "Shift",
      * or "Ctrl+Shift". These strings can be localized by changing
      * the <code>awt.properties</code> file.
      * <p>
-     * Note that <code>InputEvent.ALT_MASK</code> and
-     * <code>InputEvent.BUTTON2_MASK</code> have the same value,
-     * so the string "Alt" is returned for both modifiers.  Likewise,
-     * <code>InputEvent.META_MASK</code> and
-     * <code>InputEvent.BUTTON3_MASK</code> have the same value,
-     * so the string "Meta" is returned for both modifiers.
+     * Note that the <code>InputEvent.ALT_MASK</code> and
+     * <code>InputEvent.BUTTON2_MASK</code> have equal values,
+     * so the "Alt" string is returned for both modifiers.  Likewise,
+     * the <code>InputEvent.META_MASK</code> and
+     * <code>InputEvent.BUTTON3_MASK</code> have equal values,
+     * so the "Meta" string is returned for both modifiers.
+     * <p>
+     * Note that passing negative parameter is incorrect,
+     * and will cause the returning an unspecified string.
+     * Zero parameter means that no modifiers were passed and will
+     * cause the returning an empty string.
      *
-     * @param modifiers a modifier mask describing the modifier keys and
+     * @param modifiers A modifier mask describing the modifier keys and
      *                  mouse buttons that were down during the event
-     * @return string   a text description of the combination of modifier
+     * @return string   string text description of the combination of modifier
      *                  keys and mouse buttons that were down during the event
      * @see InputEvent#getModifiersExText(int)
      * @since 1.4
--- a/src/share/classes/java/awt/event/MouseWheelEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/MouseWheelEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2007 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 2000-2008 Sun Microsystems, Inc.  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
--- a/src/share/classes/java/awt/event/PaintEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/PaintEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -36,6 +36,10 @@
  * designed to be used with the Event Listener model; programs
  * should continue to override paint/update methods in order
  * render themselves properly.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code PaintEvent} instance is not
+ * in the range from {@code PAINT_FIRST} to {@code PAINT_LAST}.
  *
  * @author Amy Fowler
  * @since 1.1
@@ -82,15 +86,19 @@
     /**
      * Constructs a <code>PaintEvent</code> object with the specified
      * source component and type.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source     the object where the event originated
-     * @param id         the event type
-     * @param updateRect the rectangle area which needs to be repainted
+     * @param source     The object where the event originated
+     * @param id           The integer that identifies the event type.
+     *                     For information on allowable values, see
+     *                     the class description for {@link PaintEvent}
+     * @param updateRect The rectangle area which needs to be repainted
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getUpdateRect()
      */
     public PaintEvent(Component source, int id, Rectangle updateRect) {
         super(source, id);
--- a/src/share/classes/java/awt/event/TextEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/TextEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -38,6 +38,10 @@
  * this <code>TextEvent</code> when the event occurs. The listener is
  * spared the details of processing individual mouse movements and key strokes
  * Instead, it can process a "meaningful" (semantic) event like "text changed".
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code TextEvent} instance is not
+ * in the range from {@code TEXT_FIRST} to {@code TEXT_LAST}.
  *
  * @author Georges Saab
  *
@@ -71,15 +75,18 @@
 
     /**
      * Constructs a <code>TextEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the (<code>TextComponent</code>) object that
+     * @param source The (<code>TextComponent</code>) object that
      *               originated the event
-     * @param id     an integer that identifies the event type
+     * @param id     An integer that identifies the event type.
+     *                     For information on allowable values, see
+     *                     the class description for {@link TextEvent}
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
      */
     public TextEvent(Object source, int id) {
         super(source, id);
--- a/src/share/classes/java/awt/event/WindowEvent.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/share/classes/java/awt/event/WindowEvent.java	Sun Apr 13 23:56:20 2008 +0400
@@ -41,6 +41,10 @@
  * (<code>WindowAdapter</code> objects implement the
  * <code>WindowListener</code> interface.) Each such listener object
  * gets this <code>WindowEvent</code> when the event occurs.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code WindowEvent} instance is not
+ * in the range from {@code WINDOW_FIRST} to {@code WINDOW_LAST}.
  *
  * @author Carl Quinn
  * @author Amy Fowler
@@ -170,20 +174,27 @@
 
     /**
      * Constructs a <code>WindowEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Window</code> object
+     * @param source    The <code>Window</code> object
      *                    that originated the event
-     * @param id        an integer indicating the type of event.
-     * @param opposite  the other window involved in the focus or activation
+     * @param id        An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link WindowEvent}
+     * @param opposite  The other window involved in the focus or activation
      *                      change, or <code>null</code>
-     * @param oldState  previous state of the window for window state
-     *                      change event
-     * @param newState  new state of the window for window state change event
+     * @param oldState  Previous state of the window for window state change event.
+     *                  See {@code #getOldState()} for allowable values
+     * @param newState  New state of the window for window state change event.
+     *                  See {@code #getNewState()} for allowable values
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getWindow()
+     * @see #getID()
+     * @see #getOppositeWindow()
+     * @see #getOldState()
+     * @see #getNewState()
      * @since 1.4
      */
     public WindowEvent(Window source, int id, Window opposite,
@@ -209,24 +220,28 @@
      * If this focus change occurs with a native application, with a
      * Java application in a different VM, or with no other
      * <code>Window</code>, then the opposite Window is <code>null</code>.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source     the <code>Window</code> object that
+     * @param source     The <code>Window</code> object that
      *                   originated the event
-     * @param id         <code>WINDOW_ACTIVATED</code>,
-     *                   <code>WINDOW_DEACTIVATED</code>,
-     *                   <code>WINDOW_GAINED_FOCUS</code>,
-     *                   or <code>WINDOW_LOST_FOCUS</code>. It is
-     *                   expected that this constructor will not be used for
-     *                   other <code>WindowEvent</code> types because the
-     *                   opposite <code>Window</code> of such events
-     *                   will always be <code>null</code>
-     * @param opposite   the other <code>Window</code> involved in the
+     * @param id        An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link WindowEvent}.
+     *                  It is expected that this constructor will not
+     *                  be used for other then
+     *                  {@code WINDOW_ACTIVATED},{@code WINDOW_DEACTIVATED},
+     *                  {@code WINDOW_GAINED_FOCUS}, or {@code WINDOW_LOST_FOCUS}.
+     *                  {@code WindowEvent} types,
+     *                  because the opposite <code>Window</code> of other event types
+     *                  will always be {@code null}.
+     * @param opposite   The other <code>Window</code> involved in the
      *                   focus or activation change, or <code>null</code>
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getWindow()
+     * @see #getID()
+     * @see #getOppositeWindow()
      * @since 1.4
      */
     public WindowEvent(Window source, int id, Window opposite) {
@@ -236,21 +251,30 @@
     /**
      * Constructs a <code>WindowEvent</code> object with the specified
      * previous and new window states.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Window</code> object
+     * @param source    The <code>Window</code> object
      *                  that originated the event
-     * @param id        <code>WINDOW_STATE_CHANGED</code> event type.
+     * @param id        An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link WindowEvent}.
      *                  It is expected that this constructor will not
-     *                  be used for other <code>WindowEvent</code>
+     *                  be used for other then
+     *                  {@code WINDOW_STATE_CHANGED}
+     *                  {@code WindowEvent}
      *                  types, because the previous and new window
      *                  states are meaningless for other event types.
-     * @param oldState  an integer representing the previous window state
-     * @param newState  an integer representing the new window state
+     * @param oldState  An integer representing the previous window state.
+     *                  See {@code #getOldState()} for allowable values
+     * @param newState  An integer representing the new window state.
+     *                  See {@code #getNewState()} for allowable values
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getWindow()
+     * @see #getID()
+     * @see #getOldState()
+     * @see #getNewState()
      * @since 1.4
      */
     public WindowEvent(Window source, int id, int oldState, int newState) {
@@ -259,14 +283,17 @@
 
     /**
      * Constructs a <code>WindowEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the <code>Window</code> object that originated the event
-     * @param id     an integer indicating the type of event
+     * @param source The <code>Window</code> object that originated the event
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link WindowEvent}.
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getWindow()
+     * @see #getID()
      */
     public WindowEvent(Window source, int id) {
         this(source, id, null, 0, 0);
--- a/src/solaris/classes/sun/awt/X11/XComponentPeer.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/solaris/classes/sun/awt/X11/XComponentPeer.java	Sun Apr 13 23:56:20 2008 +0400
@@ -420,40 +420,36 @@
           case SNFH_SUCCESS_PROCEED:
               // Currently we just generate focus events like we deal with lightweight instead of calling
               // XSetInputFocus on native window
-              if (focusLog.isLoggable(Level.FINER)) focusLog.finer("Proceeding with request to " + lightweightChild + " in " + target);
+              if (focusLog.isLoggable(Level.FINER)) focusLog.finer("Proceeding with request to " +
+                  lightweightChild + " in " + target);
               /**
                * The problems with requests in non-focused window arise because shouldNativelyFocusHeavyweight
                * checks that native window is focused while appropriate WINDOW_GAINED_FOCUS has not yet
                * been processed - it is in EventQueue. Thus, SNFH allows native request and stores request record
-               * in requests list - and it breaks our requests sequence as first record on WGF should be the last focus
-               * owner which had focus before WLF. So, we should not add request record for such requests
+               * in requests list - and it breaks our requests sequence as first record on WGF should be the last
+               * focus owner which had focus before WLF. So, we should not add request record for such requests
                * but store this component in mostRecent - and return true as before for compatibility.
                */
               Window parentWindow = getContainingWindow(target);
-              if (parentWindow != null) {
-                  // and check that it is focused
-                  if (!parentWindow.isFocused()) {
-                      XWindowPeer wpeer = (XWindowPeer)parentWindow.getPeer();
-                      /*
-                       * Fix for 6314575.
-                       * Shouldn't restore focus on 'actualFocusedWindow'
-                       * when a component inside a Frame is requesting it.
-                       */
-                      wpeer.setActualFocusedWindow(null);
+              if (parentWindow == null) {
+                  return rejectFocusRequestHelper("WARNING: Parent window is null");
+              }
+              XWindowPeer wpeer = (XWindowPeer)parentWindow.getPeer();
+              if (wpeer == null) {
+                  return rejectFocusRequestHelper("WARNING: Parent window's peer is null");
+              }
+              /*
+               * Passing null 'actualFocusedWindow' as we don't want to restore focus on it
+               * when a component inside a Frame is requesting focus.
+               * See 6314575 for details.
+               */
+              boolean res = wpeer.requestWindowFocus(null);
 
-                      boolean res = wpeer.requestWindowFocus();
-                      if (focusLog.isLoggable(Level.FINER)) focusLog.finer("Requested window focus: " + res);
-                      // If parent window can be made focused and has been made focused(synchronously)
-                      // then we can proceed with children, otherwise we retreat.
-                      if (!(res && parentWindow.isFocused())) {
-                          focusLog.finer("Waiting for asynchronous processing of window focus request");
-                          KeyboardFocusManagerPeerImpl.removeLastFocusRequest(target);
-                          return false;
-                      }
-                  }
-              } else {
-                  if (focusLog.isLoggable(Level.FINER)) focusLog.finer("WARNING: Parent window is null");
-                  return false;
+              if (focusLog.isLoggable(Level.FINER)) focusLog.finer("Requested window focus: " + res);
+              // If parent window can be made focused and has been made focused(synchronously)
+              // then we can proceed with children, otherwise we retreat.
+              if (!(res && parentWindow.isFocused())) {
+                  return rejectFocusRequestHelper("Waiting for asynchronous processing of the request");
               }
 
               // NOTE: We simulate heavyweight behavior of Motif - component receives focus right
@@ -469,6 +465,12 @@
         return false;
     }
 
+    private boolean rejectFocusRequestHelper(String logMsg) {
+        if (focusLog.isLoggable(Level.FINER)) focusLog.finer(logMsg);
+        KeyboardFocusManagerPeerImpl.removeLastFocusRequest(target);
+        return false;
+    }
+
     void handleJavaFocusEvent(AWTEvent e) {
         if (focusLog.isLoggable(Level.FINER)) focusLog.finer(e.toString());
         if (e.getID() == FocusEvent.FOCUS_GAINED) {
--- a/src/solaris/classes/sun/awt/X11/XDecoratedPeer.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/solaris/classes/sun/awt/X11/XDecoratedPeer.java	Sun Apr 13 23:56:20 2008 +0400
@@ -1013,16 +1013,6 @@
 
     private void handleWmTakeFocus(XClientMessageEvent cl) {
         focusLog.log(Level.FINE, "WM_TAKE_FOCUS on {0}", new Object[]{this});
-        // A workaround to Metacity issue (see 6613426).
-        // The first check is to skip redundant WM_TAKE_FOCUS on click
-        // in a focused frame. The second check is to allow requesting focus
-        // on click in a frame when its owned window is currently focused.
-        if (this == getNativeFocusedWindowPeer() &&
-            target == XKeyboardFocusManagerPeer.getCurrentNativeFocusedWindow())
-        {
-            focusLog.fine("The window is already focused, skipping.");
-            return;
-        }
         requestWindowFocus(cl.get_data(1), true);
     }
 
@@ -1124,53 +1114,51 @@
         focusLog.fine("Request for decorated window focus");
         // If this is Frame or Dialog we can't assure focus request success - but we still can try
         // If this is Window and its owner Frame is active we can be sure request succedded.
-        Window win = (Window)target;
         Window focusedWindow = XKeyboardFocusManagerPeer.getCurrentNativeFocusedWindow();
         Window activeWindow = XWindowPeer.getDecoratedOwner(focusedWindow);
 
         focusLog.log(Level.FINER, "Current window is: active={0}, focused={1}",
-                     new Object[]{ Boolean.valueOf(win == activeWindow),
-                                   Boolean.valueOf(win == focusedWindow)});
+                     new Object[]{ Boolean.valueOf(target == activeWindow),
+                                   Boolean.valueOf(target == focusedWindow)});
 
         XWindowPeer toFocus = this;
         while (toFocus.nextTransientFor != null) {
             toFocus = toFocus.nextTransientFor;
         }
-
-        if (this == toFocus) {
-            if (focusAllowedFor()) {
-                if (win == activeWindow && win != focusedWindow) {
-                    // Happens when focus is on window child
-                    focusLog.fine("Focus is on child window - transfering it back");
-                    handleWindowFocusInSync(-1);
-                } else {
-                    focusLog.fine("Requesting focus to this window");
-                    if (timeProvided) {
-                        requestXFocus(time);
-                    } else {
-                        requestXFocus();
-                    }
-                }
-                return true;
-            } else {
-                return false;
-            }
-        }
-        else if (toFocus.focusAllowedFor()) {
-            focusLog.fine("Requesting focus to " + toFocus);
-            if (timeProvided) {
-                toFocus.requestXFocus(time);
-            } else {
-                toFocus.requestXFocus();
-            }
-            return false;
-        }
-        else
-        {
+        if (toFocus == null || !toFocus.focusAllowedFor()) {
             // This might change when WM will have property to determine focus policy.
             // Right now, because policy is unknown we can't be sure we succedded
             return false;
         }
+        if (this == toFocus) {
+            if (isWMStateNetHidden()) {
+                focusLog.fine("The window is unmapped, so rejecting the request");
+                return false;
+            }
+            if (target == activeWindow && target != focusedWindow) {
+                // Happens when an owned window is currently focused
+                focusLog.fine("Focus is on child window - transfering it back to the owner");
+                handleWindowFocusInSync(-1);
+                return true;
+            }
+            Window realNativeFocusedWindow = XWindowPeer.getNativeFocusedWindow();
+            focusLog.finest("Real native focused window: " + realNativeFocusedWindow +
+                            "\nKFM's focused window: " + focusedWindow);
+
+            // See 6522725, 6613426.
+            if (target == realNativeFocusedWindow) {
+                focusLog.fine("The window is already natively focused.");
+                return true;
+            }
+        }
+        focusLog.fine("Requesting focus to " + (this == toFocus ? "this window" : toFocus));
+
+        if (timeProvided) {
+            toFocus.requestXFocus(time);
+        } else {
+            toFocus.requestXFocus();
+        }
+        return (this == toFocus);
     }
 
     XWindowPeer actualFocusedWindow = null;
--- a/src/solaris/classes/sun/awt/X11/XKeyboardFocusManagerPeer.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/solaris/classes/sun/awt/X11/XKeyboardFocusManagerPeer.java	Sun Apr 13 23:56:20 2008 +0400
@@ -96,12 +96,12 @@
             Component focusOwner = activeWindow.getFocusOwner();
             if (focusLog.isLoggable(Level.FINE)) focusLog.fine("Clearing global focus owner " + focusOwner);
             if (focusOwner != null) {
-                XComponentPeer nativePeer = XComponentPeer.getNativeContainer(focusOwner);
-                if (nativePeer != null) {
+//                XComponentPeer nativePeer = XComponentPeer.getNativeContainer(focusOwner);
+//                if (nativePeer != null) {
                     FocusEvent fl = new CausedFocusEvent(focusOwner, FocusEvent.FOCUS_LOST, false, null,
                                                          CausedFocusEvent.Cause.CLEAR_GLOBAL_FOCUS_OWNER);
                     XWindow.sendEvent(fl);
-                }
+//                }
             }
         }
    }
--- a/src/solaris/classes/sun/awt/X11/XWindowPeer.java	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/solaris/classes/sun/awt/X11/XWindowPeer.java	Sun Apr 13 23:56:20 2008 +0400
@@ -582,7 +582,7 @@
     }
 
     /*
-     * Converts native focused X window id into Java peer.
+     * Retrives real native focused window and converts it into Java peer.
      */
     static XWindowPeer getNativeFocusedWindowPeer() {
         XBaseWindow baseWindow = XToolkit.windowToXWindow(xGetInputFocus());
@@ -591,6 +591,14 @@
                ((XFocusProxyWindow)baseWindow).getOwner() : null;
     }
 
+    /*
+     * Retrives real native focused window and converts it into Java window.
+     */
+    static Window getNativeFocusedWindow() {
+        XWindowPeer peer = getNativeFocusedWindowPeer();
+        return peer != null ? (Window)peer.target : null;
+    }
+
     boolean isFocusableWindow() {
         if (XToolkit.isToolkitThread() || SunToolkit.isAWTLockHeldByCurrentThread())
         {
@@ -1252,7 +1260,7 @@
         return res;
     }
 
-    private boolean isWMStateNetHidden() {
+    protected boolean isWMStateNetHidden() {
         XNETProtocol protocol = XWM.getWM().getNETProtocol();
         return (protocol != null && protocol.isWMStateNetHidden(this));
     }
@@ -1740,6 +1748,11 @@
         return window;
     }
 
+    public boolean requestWindowFocus(XWindowPeer actualFocusedWindow) {
+        setActualFocusedWindow(actualFocusedWindow);
+        return requestWindowFocus();
+    }
+
     public boolean requestWindowFocus() {
         return requestWindowFocus(0, false);
     }
@@ -1748,25 +1761,25 @@
         focusLog.fine("Request for window focus");
         // If this is Frame or Dialog we can't assure focus request success - but we still can try
         // If this is Window and its owner Frame is active we can be sure request succedded.
-        Window win = (Window) target;
-        Window owner = XWindowPeer.getDecoratedOwner(win);
+        Window ownerWindow  = XWindowPeer.getDecoratedOwner((Window)target);
+        Window focusedWindow = XKeyboardFocusManagerPeer.getCurrentNativeFocusedWindow();
+        Window activeWindow = XWindowPeer.getDecoratedOwner(focusedWindow);
 
-        final Window activeWindow =
-                XWindowPeer.getDecoratedOwner(XKeyboardFocusManagerPeer.getCurrentNativeFocusedWindow());
-        if (activeWindow == owner) {
+        if (isWMStateNetHidden()) {
+            focusLog.fine("The window is unmapped, so rejecting the request");
+            return false;
+        }
+        if (activeWindow == ownerWindow) {
             focusLog.fine("Parent window is active - generating focus for this window");
             handleWindowFocusInSync(-1);
             return true;
-        } else {
-            focusLog.fine("Parent window is not active");
         }
-        ComponentPeer peer = ComponentAccessor.getPeer(owner);
-        if (peer instanceof XDecoratedPeer) {
-            XDecoratedPeer wpeer = (XDecoratedPeer) peer;
-            if (wpeer.requestWindowFocus(this, time, timeProvided)) {
-                focusLog.fine("Parent window accepted focus request - generating focus for this window");
-                return true;
-            }
+        focusLog.fine("Parent window is not active");
+
+        XDecoratedPeer wpeer = (XDecoratedPeer)ComponentAccessor.getPeer(ownerWindow);
+        if (wpeer != null && wpeer.requestWindowFocus(this, time, timeProvided)) {
+            focusLog.fine("Parent window accepted focus request - generating focus for this window");
+            return true;
         }
         focusLog.fine("Denied - parent window is not active and didn't accept focus request");
         return false;
--- a/src/windows/native/sun/windows/awt_Component.cpp	Sun Apr 13 23:41:40 2008 +0400
+++ b/src/windows/native/sun/windows/awt_Component.cpp	Sun Apr 13 23:56:20 2008 +0400
@@ -903,8 +903,27 @@
 
 void AwtComponent::Hide()
 {
+    JNIEnv *env = (JNIEnv *)JNU_GetEnv(jvm, JNI_VERSION_1_2);
+    jobject peer = GetPeer(env);
+    BOOL oldValue = sm_suppressFocusAndActivation;
     m_visible = false;
+
+    // On disposal the focus owner actually loses focus at the moment of hiding.
+    // So, focus change suppression (if requested) should be made here.
+    if (GetHWnd() == sm_focusOwner &&
+        !JNU_CallMethodByName(env, NULL, peer, "isAutoFocusTransferOnDisposal", "()Z").z)
+   {
+        sm_suppressFocusAndActivation = TRUE;
+        // The native system may autotransfer focus on hiding to the parent
+        // of the component. Nevertheless this focus change won't be posted
+        // to the Java level, we're better to avoid this. Anyway, after
+        // the disposal focus should be requested to the right component.
+        ::SetFocus(NULL);
+        sm_focusOwner = NULL;
+    }
     ::ShowWindow(GetHWnd(), SW_HIDE);
+
+    sm_suppressFocusAndActivation = oldValue;
 }
 
 BOOL
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/java/awt/Focus/ContainerFocusAutoTransferTest/ContainerFocusAutoTransferTest.java	Sun Apr 13 23:56:20 2008 +0400
@@ -0,0 +1,243 @@
+/*
+ * Copyright 2008 Sun Microsystems, Inc.  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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ */
+
+/*
+  @test
+  @bug       6607170
+  @summary   Tests for focus-auto-transfer.
+  @author    Anton Tarasov: area=awt-focus
+  @library   ../../regtesthelpers
+  @build     Util
+  @run       main ContainerFocusAutoTransferTest
+*/
+
+import java.applet.Applet;
+import java.awt.AWTEvent;
+import java.awt.Component;
+import java.awt.ComponentOrientation;
+import java.awt.DefaultKeyboardFocusManager;
+import java.awt.KeyboardFocusManager;
+import java.awt.Robot;
+import java.awt.Color;
+import java.awt.FlowLayout;
+import java.awt.Toolkit;
+import java.awt.event.AWTEventListener;
+import java.awt.event.FocusEvent;
+import java.awt.event.WindowEvent;
+import javax.swing.JButton;
+import javax.swing.JFrame;
+import javax.swing.JPanel;
+import test.java.awt.regtesthelpers.Util;
+
+public class ContainerFocusAutoTransferTest extends Applet {
+    Robot robot;
+    TestFrame frame;
+    KeyboardFocusManager kfm;
+    enum TestCase {
+        REMOVAL { public String toString() { return "removal"; } },
+        HIDING { public String toString() { return "hiding"; } },
+        DISABLING { public String toString() { return "disabling"; } },
+        DEFOCUSING { public String toString() { return "defocusing"; } };
+        public abstract String toString();
+    };
+
+    public static void main(String[] args) {
+        ContainerFocusAutoTransferTest app = new ContainerFocusAutoTransferTest();
+        app.init();
+        app.start();
+    }
+
+    public void init() {
+        robot = Util.createRobot();
+        kfm = KeyboardFocusManager.getCurrentKeyboardFocusManager();
+        Toolkit.getDefaultToolkit().addAWTEventListener(new AWTEventListener() {
+            public void eventDispatched(AWTEvent event) {
+                System.out.println("--> " + event);
+            }
+        }, FocusEvent.FOCUS_EVENT_MASK | WindowEvent.WINDOW_FOCUS_EVENT_MASK);
+    }
+
+    public void start() {
+        System.out.println("*** TEST #1 ***");
+        test(TestCase.HIDING);
+
+        System.out.println("*** TEST #2 ***");
+        test(TestCase.REMOVAL);
+
+        System.out.println("*** TEST #3 ***");
+        test3(TestCase.DISABLING);
+
+        System.out.println("*** TEST #4 ***");
+        test3(TestCase.DEFOCUSING);
+
+        System.out.println("*** TEST #5 ***");
+        test4();
+
+        System.out.println("Test passed.");
+    }
+
+    void test(final TestCase t) {
+        showFrame();
+        test1(t); // Test for correct auto-transfer
+        test2(t); // Test for clearing focus
+    }
+
+    void test1(final TestCase t) {
+        Runnable action = new Runnable() {
+            public void run() {
+                KeyboardFocusManager.setCurrentKeyboardFocusManager(new TestKFM());
+                if (t == TestCase.REMOVAL) {
+                    frame.remove(frame.panel0);
+
+                } else if (t == TestCase.HIDING) {
+                    frame.panel0.setVisible(false);
+                }
+                frame.repaint();
+            }
+        };
+        if (!Util.trackFocusGained(frame.b3, action, 2000, false)) {
+            throw new TestFailedException(t + ": focus wasn't transfered as expected!");
+        }
+        KeyboardFocusManager.setCurrentKeyboardFocusManager(kfm);
+    }
+
+    void test2(TestCase t) {
+        frame.setFocusable(false); // exclude it from the focus cycle
+        if (t == TestCase.REMOVAL) {
+            frame.remove(frame.panel1);
+
+        } else if (t == TestCase.HIDING) {
+            frame.panel1.setVisible(false);
+        }
+        frame.repaint();
+        Util.waitForIdle(robot);
+        if (kfm.getFocusOwner() != null) {
+            throw new TestFailedException(t + ": focus wasn't cleared!");
+        }
+    }
+
+    void test3(final TestCase t) {
+        showFrame();
+        Runnable action = new Runnable() {
+            public void run() {
+                if (t == TestCase.DISABLING) {
+                    frame.b0.setEnabled(false);
+
+                } else if (t == TestCase.DEFOCUSING) {
+                    frame.b0.setFocusable(false);
+                }
+            }};
+        if (!Util.trackFocusGained(frame.b1, action, 2000, false)) {
+            throw new TestFailedException(t + ": focus wasn't transfered as expected!");
+        }
+    }
+
+    void test4() {
+        showFrame();
+        frame.setFocusableWindowState(false);
+        Util.waitForIdle(robot);
+        if (kfm.getFocusOwner() != null) {
+            throw new TestFailedException("defocusing the frame: focus wasn't cleared!");
+        }
+    }
+
+    void showFrame() {
+        if (frame != null) {
+            frame.dispose();
+            Util.waitForIdle(robot);
+        }
+        frame = new TestFrame();
+        frame.setVisible(true);
+        Util.waitTillShown(frame);
+
+        if (!frame.b0.hasFocus()) {
+            Util.clickOnComp(frame.b0, robot);
+            Util.waitForIdle(robot);
+            if (!frame.b0.hasFocus()) {
+                throw new TestErrorException("couldn't set focus on " + frame.b2);
+            }
+        }
+    }
+
+    class TestKFM extends DefaultKeyboardFocusManager {
+        public boolean dispatchEvent(AWTEvent e) {
+            if (e.getID() == FocusEvent.FOCUS_GAINED) {
+                System.out.println(e);
+                Component src = (Component)e.getSource();
+                if (src == frame.b1 || src == frame.b2) {
+                    throw new TestFailedException("wrong focus transfer on removal!");
+                }
+            }
+            return super.dispatchEvent(e);
+        }
+    }
+}
+
+class TestFrame extends JFrame {
+    public JPanel panel0 = new JPanel();
+    public JPanel panel1 = new JPanel();
+    public JButton b0 = new JButton("b0");
+    public JButton b1 = new JButton("b1");
+    public JButton b2 = new JButton("b2");
+    public JButton b3 = new JButton("b3");
+    public JButton b4 = new JButton("b4");
+
+    public TestFrame() {
+        super("TestFrame");
+
+        // The change of the orientation and the reverse order of
+        // adding the buttons to the panel is because in Container.removeNotify()
+        // the child components are removed in the reverse order.
+        // We want that the focus owner (b0) would be removed first and
+        // that the next traversable component would be b1.
+        panel0.setComponentOrientation(ComponentOrientation.RIGHT_TO_LEFT);
+        panel0.add(b2);
+        panel0.add(b1);
+        panel0.add(b0);
+
+        panel1.add(b3);
+        panel1.add(b4);
+
+        setLayout(new FlowLayout());
+        add(panel0);
+        add(panel1);
+        pack();
+
+        panel0.setBackground(Color.red);
+        panel1.setBackground(Color.blue);
+    }
+}
+
+// Thrown when the behavior being verified is found wrong.
+class TestFailedException extends RuntimeException {
+    TestFailedException(String msg) {
+        super("Test failed: " + msg);
+    }
+}
+
+// Thrown when an error not related to the behavior being verified is encountered.
+class TestErrorException extends RuntimeException {
+    TestErrorException(String msg) {
+        super("Unexpected error: " + msg);
+    }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/java/awt/Focus/IconifiedFrameFocusChangeTest/IconifiedFrameFocusChangeTest.java	Sun Apr 13 23:56:20 2008 +0400
@@ -0,0 +1,124 @@
+/*
+ * Copyright 2008 Sun Microsystems, Inc.  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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ */
+
+/*
+  @test
+  @bug       6522725
+  @summary   Tests for proper request-focus-back on FOCUS_LOST.
+  @author    Anton Tarasov: area=awt-focus
+  @library   ../../regtesthelpers
+  @build     Util
+  @run       main IconifiedFrameFocusChangeTest
+*/
+
+import java.awt.*;
+import java.applet.Applet;
+import java.awt.event.*;
+import test.java.awt.regtesthelpers.Util;
+
+public class IconifiedFrameFocusChangeTest extends Applet {
+    Frame testFrame = new Frame("Test Frame");
+    Frame otherFrame = new Frame("Other Frame");
+    Button testButton = new Button("test button");
+    Button otherButton = new Button("other button");
+    Robot robot;
+
+    public static void main(String[] args) {
+        IconifiedFrameFocusChangeTest app = new IconifiedFrameFocusChangeTest();
+        app.init();
+        app.start();
+    }
+
+    public void init() {
+        robot = Util.createRobot();
+
+        testFrame.add(testButton);
+        testFrame.pack();
+        otherFrame.add(otherButton);
+        otherFrame.pack();
+        otherFrame.setLocation(200, 0);
+
+        testButton.addFocusListener(new FocusAdapter() {
+            public void focusLost(FocusEvent e) {
+                testButton.requestFocus();
+            }
+        });
+    }
+
+    public void start() {
+        otherFrame.setVisible(true);
+        Util.waitForIdle(robot);
+        testFrame.setVisible(true);
+        Util.waitForIdle(robot);
+
+        if (!testButton.hasFocus()) {
+            throw new TestErrorException("wrong initial focus");
+        }
+
+        /*
+         * Iconify the Frame. Test that focus switches properly.
+         */
+        Runnable action = new Runnable() {
+            public void run() {
+                testFrame.setExtendedState(Frame.ICONIFIED);
+            }
+        };
+        if (!Util.trackFocusGained(otherButton, action, 2000, true)) {
+            throw new TestFailedException("iconifying focused window didn't trigger focus change");
+        }
+
+        /*
+         * Test that key events go into the focus owner.
+         */
+        action = new Runnable() {
+            public void run() {
+                robot.keyPress(KeyEvent.VK_SPACE);
+                robot.delay(50);
+                robot.keyRelease(KeyEvent.VK_SPACE);
+            }
+        };
+        if (!Util.trackActionPerformed(otherButton, action, 2000, true)) {
+            throw new TestFailedException("Java focus owner doesn't match to the native one");
+        }
+
+        System.out.println("Test passed.");
+    }
+}
+
+/**
+ * Thrown when the behavior being verified is found wrong.
+ */
+class TestFailedException extends RuntimeException {
+    TestFailedException(String msg) {
+        super("Test failed: " + msg);
+    }
+}
+
+/**
+ * Thrown when an error not related to the behavior being verified is encountered.
+ */
+class TestErrorException extends RuntimeException {
+    TestErrorException(String msg) {
+        super("Unexpected error: " + msg);
+    }
+}