svn commit: r462610 - in /incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model: CollectionModel.java TreeModel.java

[aw...@apache.org]

Author: awiner
Date: Tue Oct 10 15:25:18 2006
New Revision: 462610

URL: http://svn.apache.org/viewvc?view=rev&rev=462610
Log:
Add some improved TreeModel javadoc based on adffaces-user threads

Modified:
    incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model/CollectionModel.java
    incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model/TreeModel.java

Modified: incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model/CollectionModel.java
URL: http://svn.apache.org/viewvc/incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model/CollectionModel.java?view=diff&rev=462610&r1=462609&r2=462610
==============================================================================
--- incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model/CollectionModel.java (original)
+++ incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model/CollectionModel.java Tue Oct 10 15:25:18 2006
@@ -19,9 +19,27 @@
 import javax.faces.model.DataModel;
 
 /**
- * The data model that is used by ADF Table components.
- * This extends the faces DataModel class and adds on support for
- * rowKeys and sorting.
+ * The data model that is used by the Trinidad Table and Iterator components.
+ * This extends the Faces DataModel class and adds on support for
+ * rowKeys and sorting.  Ordinary DataModels are still supported,
+ * and will automatically be wrapped into CollectionModels, but
+ * without the added functionality.
+ * <p>
+ * <h3>Row key support</h3>
+ * <p>
+ * In the Faces DataModel, rows are identified entirely by
+ * index.  This causes major problems if the underlying data
+ * changes from one request to the next - a user request
+ * to delete one row may delete a different row because a
+ * row got added by another user, etc.  To work around
+ * this, CollectionModel is based around row keys instead
+ * of indices.  An implementation of CollectionModel must
+ * implement getRowKey()  and setRowKey(), and handle
+ * conversion from integer indices to row keys.  A trivial
+ * implementation might simply use Integer objects as 
+ * the row keys, but a better version could use a unique ID
+ * in the row.
+ * <p>
  * @author The Oracle ADF Faces Team
  */
 public abstract class CollectionModel extends DataModel

Modified: incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model/TreeModel.java
URL: http://svn.apache.org/viewvc/incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model/TreeModel.java?view=diff&rev=462610&r1=462609&r2=462610
==============================================================================
--- incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model/TreeModel.java (original)
+++ incubator/adffaces/trunk/trinidad/trinidad-api/src/main/java/org/apache/myfaces/trinidad/model/TreeModel.java Tue Oct 10 15:25:18 2006
@@ -20,8 +20,50 @@
 
 
 /**
- * The data model used by ADF Tree components.
- * TreeModel extends CollectionModel to add support for container rows.
+ * The data model used by Trinidad Tree components.  A TreeModel is
+ * responsible for understanding how to iterate through an
+ * object graph, enter and leave containers, and identify
+ * rows of objects within each container.  Within any one
+ * container, a TreeModel looks just like a CollectionModel,
+ * which extends the JSF DataModel class.  (So, to understand
+ * this class, start by learning how DataModel works).
+ * <p>
+ * <h3>Entering and exiting containers</h3>
+ * <p>
+ * TreeModel extends CollectionModel to add support for container rows,
+ * which are entered and exited with enterContainer() and exitContainer()
+ * methods.  Within a container, row indices (get/setRowIndex())
+ * are relative to the container.  However, row keys - get/setRowKey(),
+ * from the CollectionModel API - are always global for the entire
+ * tree model, so it is sufficient to call setRowKey() to enter and
+ * exit all the needed parents.
+ * <p>
+ * <h3>Lazy loading of contents</h3>
+ * <p>
+ * When a tree or treeTable iterates through the model,
+ * it will generally seek to see if a given node is a
+ * container - with the <code>isContainer()</code> method -
+ * and also see if the node is empty (and therefore
+ * not expandable) with the <code>isContainerEmpty()</code>
+ * method.  The default implementation of that latter
+ * method involves entering the child and seeing how
+ * many children it has.  As a result, by default,
+ * you will see one more level of content being
+ * requested than is actually visible on screen.  To
+ * avoid this, provide a custom override of <code>
+ * isContainerEmpty()</code> to return a value
+ * without actually entering the container.  It
+ * is acceptable for this method to return a "false negative" -
+ * to return false when there might actually not be any
+ * contents - if that is the most efficient approach possible.
+ * <p>
+ * The <code>ChildPropertyTreeModel</code> class is a useful
+ * basic subclass, but largely requires that you have the
+ * entire object model fully loaded.  If you require
+ * lazy loading, you'll likely need a custom implementation.
+ * <p>
+ * <h3>Further documentation</h3>
+ * <p>
  * Rows in the TreeModel may (recursively) contain other rows.
  * To figure out if the current row is a container, call the
  * {@link #isContainer} method.