You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by ma...@apache.org on 2005/12/20 23:05:20 UTC
svn commit: r358122 - in /myfaces/api/trunk/src/java/javax/faces:
component/EditableValueHolder.java component/UIComponentBase.java
component/UIData.java model/DataModel.java webapp/UIComponentTag.java
Author: matzew
Date: Tue Dec 20 14:05:11 2005
New Revision: 358122
URL: http://svn.apache.org/viewcvs?rev=358122&view=rev
Log:
introduced the removed javadoc (accident)
Modified:
myfaces/api/trunk/src/java/javax/faces/component/EditableValueHolder.java
myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java
myfaces/api/trunk/src/java/javax/faces/component/UIData.java
myfaces/api/trunk/src/java/javax/faces/model/DataModel.java
myfaces/api/trunk/src/java/javax/faces/webapp/UIComponentTag.java
Modified: myfaces/api/trunk/src/java/javax/faces/component/EditableValueHolder.java
URL: http://svn.apache.org/viewcvs/myfaces/api/trunk/src/java/javax/faces/component/EditableValueHolder.java?rev=358122&r1=358121&r2=358122&view=diff
==============================================================================
--- myfaces/api/trunk/src/java/javax/faces/component/EditableValueHolder.java (original)
+++ myfaces/api/trunk/src/java/javax/faces/component/EditableValueHolder.java Tue Dec 20 14:05:11 2005
@@ -20,7 +20,39 @@
import javax.faces.validator.Validator;
/**
- * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a>
+ * Defines the methods required for a component whose value can be
+ * modified by the user.
+ * <p>
+ * When a component implementing this interface is rendered, the value
+ * output is (in order):
+ * <ul>
+ * <li>The "submitted value" if non-null.
+ * <li>The component's "local value" if non-null.
+ * <li>The result of evaluating the value-binding expression with name
+ * "value" for this component.
+ * </ul>
+ * <p>
+ * Rendering the submitted value if non-null allows a component to redisplay
+ * a user-provided value when validation fails for the component. The
+ * submitted value is usually just the plain string extracted from the
+ * servlet request. During successful validation of the component, the
+ * submitted value is converted to an appropriate datatype, and stored as
+ * the component's "local value", and then the "submitted value" is
+ * immediately reset to null.
+ * <p>
+ * Rendering the "local value" if non-null allows a component to redisplay
+ * a page when validation fails for some other component; the model can't
+ * be updated unless <i>all</i> components have passed validation. This
+ * also allows components to work without a defined "value" value-binding
+ * expression. When all components validate, the update model phase runs;
+ * all components with "value" value-bindings store the "local value" into
+ * the specified property then reset their local value to null.
+ * <p>
+ * Rendering the value-binding expression named "value" allows components
+ * to display data from the user's model classes. This is the most common
+ * way a component's renderer obtains the value to display.
+ *
+ * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a> for more.
*
* @author Manfred Geiler (latest modification by $Author$)
* @version $Revision$ $Date$
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=358122&r1=358121&r2=358122&view=diff
==============================================================================
--- myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java (original)
+++ myfaces/api/trunk/src/java/javax/faces/component/UIComponentBase.java Tue Dec 20 14:05:11 2005
@@ -39,8 +39,17 @@
/**
- * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a>
+ * 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.
*
+ * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a> for more.
+ *
* @author Manfred Geiler (latest modification by $Author$)
* @version $Revision$ $Date$
*/
Modified: myfaces/api/trunk/src/java/javax/faces/component/UIData.java
URL: http://svn.apache.org/viewcvs/myfaces/api/trunk/src/java/javax/faces/component/UIData.java?rev=358122&r1=358121&r2=358122&view=diff
==============================================================================
--- myfaces/api/trunk/src/java/javax/faces/component/UIData.java (original)
+++ myfaces/api/trunk/src/java/javax/faces/component/UIData.java Tue Dec 20 14:05:11 2005
@@ -40,8 +40,86 @@
import javax.servlet.jsp.jstl.sql.Result;
/**
- * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a>
- *
+ * Represents a component which has multiple "rows" of data.
+ * <p>
+ * The children of this component are expected to be UIColumn components.
+ * <p>
+ * Note that the same set of child components are reused to implement each
+ * row of the table in turn during such phases as apply-request-values and
+ * render-response. Altering any of the members of these components therefore
+ * affects the attribute for every row, except for the following members:
+ * <ul>
+ * <li>submittedValue
+ * <li>value (where no EL binding is used)
+ * <li>valid
+ * </ul>
+ * <p>
+ * This reuse of the child components also means that it is not possible
+ * to save a reference to a component during table processing, then access
+ * it later and expect it to still represent the same row of the table.
+ * <h1>
+ * Implementation Notes
+ * </h1>
+ * <p>
+ * Each of the UIColumn children of this component has a few component
+ * children of its own to render the contents of the table cell. However
+ * there can be a very large number of rows in a table, so it isn't
+ * efficient for the UIColumn and all its child objects to be duplicated
+ * for each row in the table. Instead the "flyweight" pattern is used
+ * where a serialized state is held for each row. When setRowIndex is
+ * invoked, the UIColumn objects and their children serialize their
+ * current state then reinitialise themselves from the appropriate saved
+ * state. This allows a single set of real objects to represent multiple
+ * objects which have the same types but potentially different internal
+ * state. When a row is selected for the first time, its state is set to
+ * a clean "initial" state. Transient components (including any read-only
+ * component) do not save their state; they are just reinitialised as required.
+ * The state saved/restored when changing rows is not the complete
+ * component state, just the fields that are expected to vary between
+ * rows: "submittedValue", "value", "isValid".
+ * </p>
+ * <p>
+ * Note that a table is a "naming container", so that components
+ * within the table have their ids prefixed with the id of the
+ * table. Actually, when setRowIndex has been called on a table with
+ * id of "zzz" the table pretends to its children that its ID is
+ * "zzz_n" where n is the row index. This means that renderers for
+ * child components which call component.getClientId automatically
+ * get ids of form "zzz_n:childId" thus ensuring that components in
+ * different rows of the table get different ids.
+ * </p>
+ * <p>
+ * When decoding a submitted page, this class iterates over all
+ * its possible rowIndex values, restoring the appropriate serialized
+ * row state then calling processDecodes on the child components. Because
+ * the child components (or their renderers) use getClientId to get the
+ * request key to look for parameter data, and because this object pretends
+ * to have a different id per row ("zzz_n") a single child component can
+ * decode data from each table row in turn without being aware that it is
+ * within a table. The table's data model is updated before each call to
+ * child.processDecodes, so the child decode method can assume that the
+ * data model's rowData points to the model object associated with the
+ * row currently being decoded. Exactly the same process applies for
+ * the later validation and updateModel phases.
+ * </p>
+ * <p>
+ * When the data model for the table is bound to a backing bean property,
+ * and no validation errors have occured during processing of a postback,
+ * the data model is refetched at the start of the rendering phase
+ * (ie after the update model phase) so that the contents of the data model
+ * can be changed as a result of the latest form submission. Because the
+ * saved row state must correspond to the elements within the data model,
+ * the row state must be discarded whenever a new data model is fetched;
+ * not doing this would cause all sorts of inconsistency issues. This does
+ * imply that changing the state of any of the members "submittedValue",
+ * "value" or "valid" of a component within the table during the
+ * invokeApplication phase has no effect on the rendering of the table.
+ * When a validation error has occurred, a new DataModel is <i>not</i>
+ * fetched, and the saved state of the child components is <i>not</i>
+ * discarded.
+ * </p>
+ * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a> for more.
+ *
* @author Manfred Geiler (latest modification by $Author$)
* @version $Revision$ $Date$
*/
Modified: myfaces/api/trunk/src/java/javax/faces/model/DataModel.java
URL: http://svn.apache.org/viewcvs/myfaces/api/trunk/src/java/javax/faces/model/DataModel.java?rev=358122&r1=358121&r2=358122&view=diff
==============================================================================
--- myfaces/api/trunk/src/java/javax/faces/model/DataModel.java (original)
+++ myfaces/api/trunk/src/java/javax/faces/model/DataModel.java Tue Dec 20 14:05:11 2005
@@ -19,11 +19,31 @@
import java.util.List;
/**
- * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a>
- *
- * @author Thomas Spiegl (latest modification by $Author$)
- * @version $Revision$ $Date$
- */
+ * Represents the data presented by a UIData component, together with
+ * some "state" information about the currently selected row within the
+ * datalist for use by listeners on UIData components. This class allows
+ * managed bean code to avoid binding directly to UIData components for
+ * typical uses.
+ * <p>
+ * Note that DataModel and its standard subclasses are not serializable,
+ * as there is no state in a DataModel object itself that needs to be
+ * preserved between render and restore-view. UIData components therefore
+ * do not store their DataModel when serialized; they just evaluate their
+ * "value" EL expression to refetch the object during the "apply request"
+ * phase.
+ * <p>
+ * Because DataModel is not serializable, any "managed bean" that needs to
+ * be serialized and which has a member of type DataModel should therefore
+ * mark that member transient. If there is a need to preserve the datalist
+ * contained within the DataModel then ensure a reference to that list is
+ * stored in a non-transient member, or use a custom serialization method
+ * that explicitly serializes dataModel.getWrappedData.
+ *
+ * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a> for more.
+ *
+ * @author Thomas Spiegl (latest modification by $Author$)
+ * @version $Revision$ $Date$
+*/
public abstract class DataModel
{
// FIELDS
Modified: myfaces/api/trunk/src/java/javax/faces/webapp/UIComponentTag.java
URL: http://svn.apache.org/viewcvs/myfaces/api/trunk/src/java/javax/faces/webapp/UIComponentTag.java?rev=358122&r1=358121&r2=358122&view=diff
==============================================================================
--- myfaces/api/trunk/src/java/javax/faces/webapp/UIComponentTag.java (original)
+++ myfaces/api/trunk/src/java/javax/faces/webapp/UIComponentTag.java Tue Dec 20 14:05:11 2005
@@ -36,8 +36,17 @@
import java.util.*;
/**
- * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a>
- *
+ * Base class for all JSP tags that represent a JSF UIComponent.
+ * <p>
+ * <i>Disclaimer</i>: The official definition for the behaviour of
+ * this class is the JSF specification but for legal reasons the
+ * specification cannot be replicated here. Any javadoc present on this
+ * class therefore describes the current implementation rather than the
+ * officially required behaviour, though it is believed that this class
+ * does comply with the specification.
+ *
+ * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a> for more.
+ *
* @author Manfred Geiler (latest modification by $Author$)
* @version $Revision$ $Date$
*/