--- a/jdk/src/share/classes/java/awt/Component.java	Fri Sep 04 14:50:58 2009 +0400
+++ b/jdk/src/share/classes/java/awt/Component.java	Tue Sep 15 16:15:36 2009 +0400
@@ -91,7 +91,17 @@
  * the nonmenu-related Abstract Window Toolkit components. Class
  * <code>Component</code> can also be extended directly to create a
  * lightweight component. A lightweight component is a component that is
- * not associated with a native opaque window.
+ * not associated with a native window. On the contrary, a heavyweight
+ * component is associated with a native window. The {@link #isLightweight()}
+ * method may be used to distinguish between the two kinds of the components.
+ * <p>
+ * Lightweight and heavyweight components may be mixed in a single component
+ * hierarchy. However, for correct operating of such a mixed hierarchy of
+ * components, the whole hierarchy must be valid. When the hierarchy gets
+ * invalidated, like after changing the bounds of components, or
+ * adding/removing components to/from containers, the whole hierarchy must be
+ * validated afterwards by means of the {@link Container#validate()} method
+ * invoked on the top-most invalid container of the hierarchy.
  * <p>
  * <h3>Serialization</h3>
  * It is important to note that only AWT listeners which conform
@@ -1489,9 +1499,14 @@
     /**
      * Shows or hides this component depending on the value of parameter
      * <code>b</code>.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param b  if <code>true</code>, shows this component;
      * otherwise, hides this component
      * @see #isVisible
+     * @see #invalidate
      * @since JDK1.1
      */
     public void setVisible(boolean b) {
@@ -1750,10 +1765,15 @@
 
     /**
      * Sets the font of this component.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param f the font to become this component's font;
      *          if this parameter is <code>null</code> then this
      *          component will inherit the font of its parent
      * @see #getFont
+     * @see #invalidate
      * @since JDK1.0
      * @beaninfo
      *       bound: true
@@ -1827,8 +1847,13 @@
 
     /**
      * Sets the locale of this component.  This is a bound property.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param l the locale to become this component's locale
      * @see #getLocale
+     * @see #invalidate
      * @since JDK1.1
      */
     public void setLocale(Locale l) {
@@ -1948,12 +1973,17 @@
      * Moves this component to a new location. The top-left corner of
      * the new location is specified by the <code>x</code> and <code>y</code>
      * parameters in the coordinate space of this component's parent.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param x the <i>x</i>-coordinate of the new location's
      *          top-left corner in the parent's coordinate space
      * @param y the <i>y</i>-coordinate of the new location's
      *          top-left corner in the parent's coordinate space
      * @see #getLocation
      * @see #setBounds
+     * @see #invalidate
      * @since JDK1.1
      */
     public void setLocation(int x, int y) {
@@ -1976,11 +2006,16 @@
      * Moves this component to a new location. The top-left corner of
      * the new location is specified by point <code>p</code>. Point
      * <code>p</code> is given in the parent's coordinate space.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param p the point defining the top-left corner
      *          of the new location, given in the coordinate space of this
      *          component's parent
      * @see #getLocation
      * @see #setBounds
+     * @see #invalidate
      * @since JDK1.1
      */
     public void setLocation(Point p) {
@@ -2015,10 +2050,15 @@
     /**
      * Resizes this component so that it has width <code>width</code>
      * and height <code>height</code>.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param width the new width of this component in pixels
      * @param height the new height of this component in pixels
      * @see #getSize
      * @see #setBounds
+     * @see #invalidate
      * @since JDK1.1
      */
     public void setSize(int width, int height) {
@@ -2040,10 +2080,15 @@
     /**
      * Resizes this component so that it has width <code>d.width</code>
      * and height <code>d.height</code>.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param d the dimension specifying the new size
      *          of this component
      * @see #setSize
      * @see #setBounds
+     * @see #invalidate
      * @since JDK1.1
      */
     public void setSize(Dimension d) {
@@ -2086,6 +2131,10 @@
      * Moves and resizes this component. The new location of the top-left
      * corner is specified by <code>x</code> and <code>y</code>, and the
      * new size is specified by <code>width</code> and <code>height</code>.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param x the new <i>x</i>-coordinate of this component
      * @param y the new <i>y</i>-coordinate of this component
      * @param width the new <code>width</code> of this component
@@ -2096,6 +2145,7 @@
      * @see #setLocation(Point)
      * @see #setSize(int, int)
      * @see #setSize(Dimension)
+     * @see #invalidate
      * @since JDK1.1
      */
     public void setBounds(int x, int y, int width, int height) {
@@ -2228,12 +2278,17 @@
      * position is specified by <code>r.x</code> and <code>r.y</code>,
      * and its new size is specified by <code>r.width</code> and
      * <code>r.height</code>
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param r the new bounding rectangle for this component
      * @see       #getBounds
      * @see       #setLocation(int, int)
      * @see       #setLocation(Point)
      * @see       #setSize(int, int)
      * @see       #setSize(Dimension)
+     * @see #invalidate
      * @since     JDK1.1
      */
     public void setBounds(Rectangle r) {
@@ -6618,8 +6673,13 @@
      * native screen resource.
      * This method is called internally by the toolkit and should
      * not be called directly by programs.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @see       #isDisplayable
      * @see       #removeNotify
+     * @see #invalidate
      * @since JDK1.0
      */
     public void addNotify() {
@@ -8586,8 +8646,13 @@
      * To set the orientation of an entire component
      * hierarchy, use
      * {@link #applyComponentOrientation applyComponentOrientation}.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      *
      * @see ComponentOrientation
+     * @see #invalidate
      *
      * @author Laura Werner, IBM
      * @beaninfo
@@ -8623,12 +8688,17 @@
     /**
      * Sets the <code>ComponentOrientation</code> property of this component
      * and all components contained within it.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      *
      * @param orientation the new component orientation of this component and
      *        the components contained within it.
      * @exception NullPointerException if <code>orientation</code> is null.
      * @see #setComponentOrientation
      * @see #getComponentOrientation
+     * @see #invalidate
      * @since 1.4
      */
     public void applyComponentOrientation(ComponentOrientation orientation) {

--- a/jdk/src/share/classes/java/awt/Container.java	Fri Sep 04 14:50:58 2009 +0400
+++ b/jdk/src/share/classes/java/awt/Container.java	Tue Sep 15 16:15:36 2009 +0400
@@ -381,16 +381,15 @@
      * Appends the specified component to the end of this container.
      * This is a convenience method for {@link #addImpl}.
      * <p>
-     * Note: If a component has been added to a container that
-     * has been displayed, <code>validate</code> must be
-     * called on that container to display the new component.
-     * If multiple components are being added, you can improve
-     * efficiency by calling <code>validate</code> only once,
-     * after all the components have been added.
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy. If the container has already been
+     * displayed, the hierarchy must be validated thereafter in order to
+     * display the added component.
      *
      * @param     comp   the component to be added
      * @exception NullPointerException if {@code comp} is {@code null}
      * @see #addImpl
+     * @see #invalidate
      * @see #validate
      * @see javax.swing.JComponent#revalidate()
      * @return    the component argument
@@ -406,8 +405,15 @@
      * <p>
      * This method is obsolete as of 1.1.  Please use the
      * method <code>add(Component, Object)</code> instead.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy. If the container has already been
+     * displayed, the hierarchy must be validated thereafter in order to
+     * display the added component.
+     *
      * @exception NullPointerException if {@code comp} is {@code null}
      * @see #add(Component, Object)
+     * @see #invalidate
      */
     public Component add(String name, Component comp) {
         addImpl(comp, name, -1);
@@ -419,12 +425,11 @@
      * position.
      * This is a convenience method for {@link #addImpl}.
      * <p>
-     * Note: If a component has been added to a container that
-     * has been displayed, <code>validate</code> must be
-     * called on that container to display the new component.
-     * If multiple components are being added, you can improve
-     * efficiency by calling <code>validate</code> only once,
-     * after all the components have been added.
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy. If the container has already been
+     * displayed, the hierarchy must be validated thereafter in order to
+     * display the added component.
+     *
      *
      * @param     comp   the component to be added
      * @param     index    the position at which to insert the component,
@@ -435,6 +440,7 @@
      * @return    the component <code>comp</code>
      * @see #addImpl
      * @see #remove
+     * @see #invalidate
      * @see #validate
      * @see javax.swing.JComponent#revalidate()
      */
@@ -700,6 +706,9 @@
      * This property is guaranteed to apply only to lightweight
      * non-<code>Container</code> components.
      * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     * <p>
      * <b>Note</b>: Not all platforms support changing the z-order of
      * heavyweight components from one container into another without
      * the call to <code>removeNotify</code>. There is no way to detect
@@ -723,6 +732,7 @@
      * @exception IllegalArgumentException if adding a <code>Window</code>
      *            to a container
      * @see #getComponentZOrder(java.awt.Component)
+     * @see #invalidate
      * @since 1.5
      */
     public void setComponentZOrder(Component comp, int index) {
@@ -923,18 +933,18 @@
      * this container's layout using the specified constraints object.
      * This is a convenience method for {@link #addImpl}.
      * <p>
-     * Note: If a component has been added to a container that
-     * has been displayed, <code>validate</code> must be
-     * called on that container to display the new component.
-     * If multiple components are being added, you can improve
-     * efficiency by calling <code>validate</code> only once,
-     * after all the components have been added.
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy. If the container has already been
+     * displayed, the hierarchy must be validated thereafter in order to
+     * display the added component.
+     *
      *
      * @param     comp the component to be added
      * @param     constraints an object expressing
      *                  layout contraints for this component
      * @exception NullPointerException if {@code comp} is {@code null}
      * @see #addImpl
+     * @see #invalidate
      * @see #validate
      * @see javax.swing.JComponent#revalidate()
      * @see       LayoutManager
@@ -951,12 +961,11 @@
      * the specified constraints object.
      * This is a convenience method for {@link #addImpl}.
      * <p>
-     * Note: If a component has been added to a container that
-     * has been displayed, <code>validate</code> must be
-     * called on that container to display the new component.
-     * If multiple components are being added, you can improve
-     * efficiency by calling <code>validate</code> only once,
-     * after all the components have been added.
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy. If the container has already been
+     * displayed, the hierarchy must be validated thereafter in order to
+     * display the added component.
+     *
      *
      * @param comp the component to be added
      * @param constraints an object expressing layout contraints for this
@@ -967,6 +976,7 @@
      * @exception IllegalArgumentException if {@code index} is invalid (see
      *            {@link #addImpl} for details)
      * @see #addImpl
+     * @see #invalidate
      * @see #validate
      * @see javax.swing.JComponent#revalidate()
      * @see #remove
@@ -1014,6 +1024,11 @@
      * <code>super.addImpl(comp, constraints, index)</code>
      * </blockquote>
      * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy. If the container has already been
+     * displayed, the hierarchy must be validated thereafter in order to
+     * display the added component.
+     *
      * @param     comp       the component to be added
      * @param     constraints an object expressing layout constraints
      *                 for this component
@@ -1033,6 +1048,7 @@
      * @see       #add(Component)
      * @see       #add(Component, int)
      * @see       #add(Component, java.lang.Object)
+     * @see #invalidate
      * @see       LayoutManager
      * @see       LayoutManager2
      * @since     JDK1.1
@@ -1145,19 +1161,18 @@
      * This method also notifies the layout manager to remove the
      * component from this container's layout via the
      * <code>removeLayoutComponent</code> method.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy. If the container has already been
+     * displayed, the hierarchy must be validated thereafter in order to
+     * reflect the changes.
      *
-     * <p>
-     * Note: If a component has been removed from a container that
-     * had been displayed, {@link #validate} must be
-     * called on that container to reflect changes.
-     * If multiple components are being removed, you can improve
-     * efficiency by calling {@link #validate} only once,
-     * after all the components have been removed.
      *
      * @param     index   the index of the component to be removed
      * @throws ArrayIndexOutOfBoundsException if {@code index} is not in
      *         range {@code [0, getComponentCount()-1]}
      * @see #add
+     * @see #invalidate
      * @see #validate
      * @see #getComponentCount
      * @since JDK1.1
@@ -1209,17 +1224,15 @@
      * This method also notifies the layout manager to remove the
      * component from this container's layout via the
      * <code>removeLayoutComponent</code> method.
-     *
      * <p>
-     * Note: If a component has been removed from a container that
-     * had been displayed, {@link #validate} must be
-     * called on that container to reflect changes.
-     * If multiple components are being removed, you can improve
-     * efficiency by calling {@link #validate} only once,
-     * after all the components have been removed.
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy. If the container has already been
+     * displayed, the hierarchy must be validated thereafter in order to
+     * reflect the changes.
      *
      * @param comp the component to be removed
      * @see #add
+     * @see #invalidate
      * @see #validate
      * @see #remove(int)
      */
@@ -1239,8 +1252,15 @@
      * This method also notifies the layout manager to remove the
      * components from this container's layout via the
      * <code>removeLayoutComponent</code> method.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy. If the container has already been
+     * displayed, the hierarchy must be validated thereafter in order to
+     * reflect the changes.
+     *
      * @see #add
      * @see #remove
+     * @see #invalidate
      */
     public void removeAll() {
         synchronized (getTreeLock()) {
@@ -1432,9 +1452,14 @@
 
     /**
      * Sets the layout manager for this container.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param mgr the specified layout manager
      * @see #doLayout
      * @see #getLayout
+     * @see #invalidate
      */
     public void setLayout(LayoutManager mgr) {
         layoutMgr = mgr;
@@ -1502,9 +1527,17 @@
      * <p>If this {@code Container} is not valid, this method invokes
      * the {@code validateTree} method and marks this {@code Container}
      * as valid. Otherwise, no action is performed.
+     * <p>
+     * Note that the {@code invalidate()} method may invalidate not only the
+     * component it is called upon, but also the parents of the component.
+     * Therefore, to restore the validity of the hierarchy, the {@code
+     * validate()} method must be invoked on the top-most invalid container of
+     * the hierarchy. For performance reasons a developer may postpone the
+     * validation of the hierarchy till a bunch of layout-related operations
+     * completes, e.g. after adding all the children to the container.
      *
      * @see #add(java.awt.Component)
-     * @see Component#invalidate
+     * @see #invalidate
      * @see javax.swing.JComponent#revalidate()
      * @see #validateTree
      */
@@ -1588,8 +1621,13 @@
 
     /**
      * Sets the font of this container.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
+     *
      * @param f The font to become this container's font.
      * @see Component#getFont
+     * @see #invalidate
      * @since JDK1.0
      */
     public void setFont(Font f) {
@@ -3386,12 +3424,16 @@
     /**
      * Sets the <code>ComponentOrientation</code> property of this container
      * and all components contained within it.
+     * <p>
+     * This method changes layout-related information, and therefore,
+     * invalidates the component hierarchy.
      *
      * @param o the new component orientation of this container and
      *        the components contained within it.
      * @exception NullPointerException if <code>orientation</code> is null.
      * @see Component#setComponentOrientation
      * @see Component#getComponentOrientation
+     * @see #invalidate
      * @since 1.4
      */
     public void applyComponentOrientation(ComponentOrientation o) {