You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by sk...@apache.org on 2005/11/22 23:30:27 UTC
svn commit: r348276 -
/myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java
Author: skitching
Date: Tue Nov 22 14:30:24 2005
New Revision: 348276
URL: http://svn.apache.org/viewcvs?rev=348276&view=rev
Log:
Added Javadoc
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=348276&r1=348275&r2=348276&view=diff
==============================================================================
--- myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java (original)
+++ myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java Tue Nov 22 14:30:24 2005
@@ -15,8 +15,14 @@
*/
package javax.faces.component;
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
+import java.io.IOException;
+import java.io.Serializable;
+import java.lang.reflect.Array;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
import javax.faces.FactoryFinder;
import javax.faces.context.FacesContext;
@@ -27,14 +33,20 @@
import javax.faces.render.RenderKit;
import javax.faces.render.RenderKitFactory;
import javax.faces.render.Renderer;
-import java.io.IOException;
-import java.io.Serializable;
-import java.lang.reflect.Array;
-import java.util.*;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
/**
- * see Javadoc of JSF Specification
+ * Standard implementation of the UIComponent base class; all standard JSF
+ * components extend this class.
+ * <p>
+ * <i>Disclaimer</i>: The official definition for the behaviour of
+ * this class is the JSF 1.1 specification but for legal reasons the
+ * specification cannot be replicated here. Any javadoc here therefore
+ * describes the current implementation rather than the spec, though
+ * this class has been verified as correctly implementing the spec.
*
* @author Manfred Geiler (latest modification by $Author$)
* @version $Revision$ $Date$
@@ -59,6 +71,30 @@
{
}
+ /**
+ * Get a map through which all the UIComponent's properties, value-bindings
+ * and non-property attributes can be read and written.
+ * <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>Otherwise the key/value pair is stored in a map associated with
+ * the component.
+ * </ul>
+ * <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 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.
+ * </ul>
+ */
public Map getAttributes()
{
if (_attributesMap == null)
@@ -68,6 +104,14 @@
return _attributesMap;
}
+ /**
+ * Get the named value-binding associated with this component.
+ * <p>
+ * Value-bindings are stored in a map associated with the component,
+ * though there is commonly a property (setter/getter methods)
+ * of the same name defined on the component itself which
+ * evaluates the value-binding when called.
+ */
public ValueBinding getValueBinding(String name)
{
if (name == null) throw new NullPointerException("name");
@@ -81,6 +125,10 @@
}
}
+ /**
+ * Put the provided value-binding into a map of value-bindings
+ * associated with this component.
+ */
public void setValueBinding(String name,
ValueBinding binding)
{
@@ -93,8 +141,26 @@
}
/**
- * @param context
- * @return String
+ * Get a string which can be output to the response which uniquely
+ * identifies this UIComponent within the current view.
+ * <p>
+ * The component should have an id attribute already assigned to it;
+ * however if the id property is currently null then a unique id
+ * is generated and set for this component. This only happens when
+ * components are programmatically created without ids, as components
+ * created by a ViewHandler should be assigned ids when they are created.
+ * <p>
+ * If this component is a descendant of a NamingContainer then the
+ * client id is of form "{namingContainerId}:{componentId}". Note that
+ * the naming container's id may itself be of compound form if it has
+ * an ancestor naming container. Note also that this only applies to
+ * naming containers; other UIComponent types in the component's
+ * ancestry do not affect the clientId.
+ * <p>
+ * Finally the renderer associated with this component is asked to
+ * convert the id into a suitable form. This allows escaping of any
+ * characters in the clientId which are significant for the markup
+ * language generated by that renderer.
*/
public String getClientId(FacesContext context)
{
@@ -150,11 +216,35 @@
return _clientId;
}
+ /**
+ * Get a string which uniquely identifies this UIComponent within the
+ * scope of the nearest ancestor NamingContainer component. The id is
+ * not necessarily unique across all components in the current view.
+ */
public String getId()
{
return _id;
}
+ /**
+ * Set an identifier for this component which is unique within the
+ * scope of the nearest ancestor NamingContainer component. The id is
+ * not necessarily unique across all components in the current view.
+ * <p>
+ * The id must start with an underscore if it is generated by the JSF
+ * framework, and must <i>not</i> start with an underscore if it has
+ * been specified by the user (eg in a JSP tag).
+ * <p>
+ * The first character of the id must be an underscore or letter.
+ * Following characters may be letters, digits, underscores or dashes.
+ * <p>
+ * Null is allowed as a parameter, and will reset the id to null.
+ * <p>
+ * The clientId of this component is reset by this method; see
+ * getClientId for more info.
+ *
+ * @throws IllegalArgumentException if the id is not valid.
+ */
public void setId(String id)
{
isIdValid(id);
@@ -172,6 +262,22 @@
_parent = parent;
}
+ /**
+ * Indicates whether this component or its renderer manages the
+ * invocation of the rendering methods of its child components.
+ * When this is true:
+ * <ul>
+ * <li>This component's encodeBegin method will only be called
+ * after all the child components have been created and added
+ * to this component.
+ * <li>This component's encodeChildren method will be called
+ * after its encodeBegin method. Components for which this
+ * method returns false do not get this method invoked at all.
+ * <li>No rendering methods will be called automatically on
+ * child components; this component is required to invoke the
+ * encodeBegin/encodeEnd/etc on them itself.
+ * </ul>
+ */
public boolean getRendersChildren()
{
Renderer renderer = getRenderer(getFacesContext());
@@ -185,6 +291,21 @@
}
}
+ /**
+ * Return a list of the UIComponent objects which are direct children
+ * of this component.
+ * <p>
+ * The list object returned has some non-standard behaviour:
+ * <ul>
+ * <li>The list is type-checked; only UIComponent objects can be added.
+ * <li>If a component is added to the list with an id which is the same
+ * as some other component in the list then an exception is thrown. However
+ * multiple components with a null id may be added.
+ * <li>The component's parent property is set to this component. If the
+ * component already had a parent, then the component is first removed
+ * from its original parent's child list.
+ * </ul>
+ */
public List getChildren()
{
if (_childrenList == null)
@@ -194,15 +315,41 @@
return _childrenList;
}
+ /**
+ * Return the number of direct child components this component has.
+ * <p>
+ * Identical to getChildren().size() except that when this component
+ * has no children this method will not force an empty list to be
+ * created.
+ */
public int getChildCount()
{
return _childrenList == null ? 0 : _childrenList.size();
}
-
/**
- * @param expr
- * @return UIComponent
+ * Standard method for finding other components by id, inherited by
+ * most UIComponent objects. Note that although components have a
+ * strict parent/child hierarchy, component ids are only prefixed
+ * ("namespaced") with the id of their parent when the parent
+ * is a NamingContainer.
+ * <p>
+ * The base node at which the search starts is determined as
+ * follows:
+ * <ul>
+ * <li>When expr starts with ':', the search starts with the root
+ * component of the tree that this component is in (ie the ancestor
+ * whose parent is null).
+ * <li>Otherwise, if this component is a NamingContainer then the search
+ * starts with this component.
+ * <li>Otherwise, the search starts from the nearest ancestor
+ * NamingContainer (or the root component if there is no NamingContainer
+ * ancestor).
+ * </ul>
+ *
+ * @param expr is of form "id1:id2:id3".
+ * @return UIComponent or null if no component with the specified id is
+ * found.
*/
public UIComponent findComponent(String expr)
@@ -271,6 +418,29 @@
return new _FacetsAndChildrenIterator(_facetMap, _childrenList);
}
+ /**
+ * Invoke any listeners attached to this object which are listening
+ * for an event whose type matches the specified event's runtime
+ * type.
+ * <p>
+ * This method does not propagate the event up to parent components,
+ * ie listeners attached to parent components don't automatically
+ * get called.
+ * <p>
+ * If any of the listeners throws AbortProcessingException then
+ * that exception will prevent any further listener callbacks
+ * from occurring, and the exception propagates out of this
+ * method without alteration.
+ * <p>
+ * ActionEvent events are typically queued by the renderer associated
+ * with this component in its decode method; ValueChangeEvent events by
+ * the component's validate method. In either case the event's source
+ * property references a component. At some later time the UIViewRoot
+ * component iterates over its queued events and invokes the broadcast
+ * method on each event's source object.
+ *
+ * @param event must not be null.
+ */
public void broadcast(FacesEvent event)
throws AbortProcessingException
{
@@ -286,6 +456,11 @@
}
}
+ /**
+ * Check the submitted form parameters for data associated with this
+ * component. This default implementation delegates to this component's
+ * renderer if there is one, and otherwise ignores the call.
+ */
public void decode(FacesContext context)
{
if (context == null) throw new NullPointerException("context");