Mailing-List: contact commits-help@myfaces.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "MyFaces Development" <dev@myfaces.apache.org>
Message-ID: <20051124011940.26193.qmail@minotaur.apache.org>
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r348607 -
 /myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java
Date: Thu, 24 Nov 2005 01:19:39 -0000
To: commits@myfaces.apache.org
From: skitching@apache.org

Author: skitching
Date: Wed Nov 23 17:19:35 2005
New Revision: 348607

URL: http://svn.apache.org/viewcvs?rev=348607&view=rev
Log:
Add javadoc only.

Modified:
    myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java

Modified: myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java
URL: http://svn.apache.org/viewcvs/myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java?rev=348607&r1=348606&r2=348607&view=diff
==============================================================================
--- myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java (original)
+++ myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java Wed Nov 23 17:19:35 2005
@@ -94,6 +94,15 @@
      * <li>Otherwise a map associated with the component is checked for an
      * entry with the specified key.
      * </ul>
+     * <p>
+     * Assigning values to the map which are not explicit properties on
+     * the underlying component can be used to "tunnel" attributes from
+     * the JSP tag (or view-specific equivalent) to the associated renderer
+     * without modifying the component itself.
+     * <p>
+     * Any value-bindings and non-property attributes stored in this map
+     * are automatically serialized along with the component when the view
+     * is serialized.
      */
     public Map getAttributes()
     {
@@ -593,6 +602,15 @@
         }
     }
 
+    /**
+     * This isn't an input component, so just pass on the processUpdates
+     * call to child components and facets that might be input components.
+     * <p>
+     * Components that were never rendered can't possibly be receiving
+     * update data (no corresponding fields were ever put into the response)
+     * so if this component is not rendered then this method does not
+     * invoke processUpdates on its children.
+     */
     public void processUpdates(FacesContext context)
     {
         if (context == null) throw new NullPointerException("context");
@@ -766,6 +784,31 @@
         _transient = transientFlag;
     }
 
+    /**
+     * Serializes objects which are "attached" to this component but which are
+     * not UIComponent children of it. Examples are validator and listener
+     * objects. To be precise, it returns an object which implements
+     * java.io.Serializable, and which when serialized will persist the
+     * state of the provided object.     
+     * <p>
+     * If the attachedObject is a List then every object in the list is saved
+     * via a call to this method, and the returned wrapper object contains
+     * a List object.
+     * <p>
+     * If the object implements StateHolder then the object's saveState is
+     * called immediately, and a wrapper is returned which contains both
+     * this saved state and the original class name. However in the case
+     * where the StateHolder.isTransient method returns true, null is
+     * returned instead.
+     * <p>
+     * If the object implements java.io.Serializable then the object is simply
+     * returned immediately; standard java serialization will later be used
+     * to store this object.
+     * <p>
+     * In all other cases, a wrapper is returned which simply stores the type
+     * of the provided object. When deserialized, a default instance of that
+     * type will be recreated.
+     */
     public static Object saveAttachedState(FacesContext context,
                                            Object attachedObject)
     {
@@ -847,6 +890,13 @@
     }
 
 
+    /**
+     * Invoked after the render phase has completed, this method
+     * returns an object which can be passed to the restoreState
+     * of some other instance of UIComponentBase to reset that
+     * object's state to the same values as this object currently
+     * has.
+     */
     public Object saveState(FacesContext context)
     {
         Object values[] = new Object[7];
@@ -860,6 +910,14 @@
         return ((Object) (values));
     }
 
+    /**
+     * Invoked in the "restore view" phase, this initialises this
+     * object's members from the values saved previously into the
+     * provided state object.
+     * <p>
+     * @param state is an object previously returned by
+     * the saveState method of this class.
+     */
     public void restoreState(FacesContext context, Object state)
     {
         Object values[] = (Object[])state;