svn commit: r356090 - /myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java

[sk...@apache.org]

Author: skitching
Date: Sun Dec 11 17:28:39 2005
New Revision: 356090

URL: http://svn.apache.org/viewcvs?rev=356090&view=rev
Log:
Update 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=356090&r1=356089&r2=356090&view=diff
==============================================================================
--- myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java (original)
+++ myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java Sun Dec 11 17:28:39 2005
@@ -77,23 +77,36 @@
      * <p>
      * When writing to the returned map:
      * <ul>
-     * <li>If this component has an explicit property (ie a setter method) for
-     * the specified key then the setter method is called.
-     * <li>If this component has a value-binding for the specified key, then
-     * the value-binding is evaluated as the target for the value.
+     * <li>If this component has an explicit property for the specified key
+     *  then the setter method is called. An IllegalArgumentException is
+     *  thrown if the property is read-only. If the property is readable
+     *  then the old value is returned, otherwise null is returned.
      * <li>Otherwise the key/value pair is stored in a map associated with
      * the component.
      * </ul>
+     * Note that value-bindings are <i>not</i> written by put calls to this map.
+     * Writing to the attributes map using a key for which a value-binding 
+     * exists will just store the value in the attributes map rather than
+     * evaluating the binding, effectively "hiding" the value-binding from
+     * later attributes.get calls. Setter methods on components commonly do
+     * <i>not</i> evaluate a binding of the same name; they just store the
+     * provided value directly on the component.
      * <p>
      * When reading from the returned map:
      * <ul>
-     * <li>If this component has an explicit property (ie a getter method) for
-     * the specified key then the getter method is called.
+     * <li>If this component has an explicit property for the specified key
+     *  then the getter method is called. If the property exists, but is
+     *  read-only (ie only a setter method is defined) then an
+     *  IllegalArgumentException is thrown.
+     * <li>If the attribute map associated with the component has an entry
+     *  with the specified key, then that is returned.
      * <li>If this component has a value-binding for the specified key, then
      * the value-binding is evaluated to fetch the value.
-     * <li>Otherwise a map associated with the component is checked for an
-     * entry with the specified key.
+     * <li>Otherwise, null is returned.
      * </ul>
+     * Note that components commonly define getter methods such that they
+     * evaluate a value-binding of the same name if there isn't yet a
+     * local property.
      * <p>
      * Assigning values to the map which are not explicit properties on
      * the underlying component can be used to "tunnel" attributes from