svn commit: r353920 - /myfaces/api/trunk/src/java/javax/faces/model/DataModel.java

[sk...@apache.org]

Author: skitching
Date: Sun Dec  4 13:51:26 2005
New Revision: 353920

URL: http://svn.apache.org/viewcvs?rev=353920&view=rev
Log:
Improved javadoc.

Modified:
    myfaces/api/trunk/src/java/javax/faces/model/DataModel.java

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=353920&r1=353919&r2=353920&view=diff
==============================================================================
--- myfaces/api/trunk/src/java/javax/faces/model/DataModel.java (original)
+++ myfaces/api/trunk/src/java/javax/faces/model/DataModel.java Sun Dec  4 13:51:26 2005
@@ -19,21 +19,34 @@
 import java.util.List;
 
 /**
+  * 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.
+  *  
   * @author Thomas Spiegl (latest modification by $Author$)
   * @version $Revision$ $Date$
 */
 public abstract class DataModel
 {
-
 	// FIELDS
     private List _listeners;
 
-	// CONSTRUCTORS
-/*	public DataModel()
-	{
-		setWrappedData(null);
- 	}
-*/
 	// METHODS
 	public void addDataModelListener(DataModelListener listener)
 	{
@@ -54,14 +67,36 @@
         return (DataModelListener[])_listeners.toArray(new DataModelListener[_listeners.size()]);
 	}
 
+    /**
+     * Return the number of rows of data available.
+     */
 	abstract public int getRowCount();
 
+    /**
+     * Return the object associated with the current row index.
+     * 
+     * @throws some kind of RuntimeException if the current row index
+     * is not within the range of the current wrappedData property.
+     */
 	abstract public Object getRowData();
 
+    /**
+     * Get the current row index.
+     */
 	abstract public int getRowIndex();
 
+    /**
+     * Get the entire list of data associated with this component. Note that
+     * the actual type of the returned object depends upon the concrete
+     * subclass of DataModel; the object will represent an "ordered sequence
+     * of components", but may be implemented as an array, java.util.List,
+     * sql ResultSet or other similar types. 
+     */
 	abstract public Object getWrappedData();
 
+    /**
+     * Returns true if a call to getRowData will return a valid object.
+     */
 	abstract public boolean isRowAvailable();
 
 	public void removeDataModelListener(DataModelListener listener)
@@ -73,8 +108,19 @@
         }
 	}
 
+    /**
+     * Set the current row index. This affects the behaviour of the
+     * getRowData method in particular.
+     * 
+     * Parameter rowIndex may be -1 to indicate "no row", or may be a value
+     * between 0 and getRowCount()-1. 
+     */
 	abstract public void setRowIndex(int rowIndex);
 
+    /**
+     * Set the entire list of data associated with this component. Note that
+     * the actual type of the provided object must match the expectations
+     * of the concrete subclass of DataModel. See getWrappedData.
+     */
 	abstract public void setWrappedData(Object data);
-
 }