Author: nbelaevski Date: 2008-08-20 13:00:39 -0400 (Wed, 20 Aug 2008) New Revision: 10149 Modified: trunk/framework/api/src/main/java/org/richfaces/model/TreeNode.java Log: https://jira.jboss.org/jira/browse/RF-4218 Modified: trunk/framework/api/src/main/java/org/richfaces/model/TreeNode.java =================================================================== --- trunk/framework/api/src/main/java/org/richfaces/model/TreeNode.java 2008-08-20 14:07:15 UTC (rev 10148) +++ trunk/framework/api/src/main/java/org/richfaces/model/TreeNode.java 2008-08-20 17:00:39 UTC (rev 10149) @@ -25,7 +25,9 @@ import java.util.Iterator; import java.util.Map; +import javax.faces.component.NamingContainer; + /** * Interface representing tree ADT nodes * @author Nick Belaevski - nbelaevski(a)exadel.com @@ -51,13 +53,32 @@ public boolean isLeaf(); /** - * getter for children + * Getter for children entries. Each children entry contains identifier (key) and child node (value). + * + * Identifiers are used to generate model keys representing paths to tree node. Model keys are used: + * <ol> + * <li> + * For persisting tree state. That means that identifiers should be serializable when + * some JSF features are used, e.g. client-side state saving. + * </li> + * <li> + * For constructing client identifiers. Client identifier for tree nodes consists of + * {@link Object#toString()} representations of identifier separated with + * {@link NamingContainer#SEPARATOR_CHAR} chars. String representation of identifier + * should be a valid XML ID, e.g. conform to this: <a href="http://www.w3.org/TR/xml11/#NT-Name"> + * XML Name Production</a> + * production. + * </li> + * </ol> + * * @return {@link Iterator} of {@link Map.Entry} instances containing {@link TreeNode} as values - * and their identifiers as keys + * and their identifiers as keys. + * */ public Iterator<Map.Entry<Object, TreeNode<T>>> getChildren(); /** * find child by id + * Please see {@link #getChildren()} for more information about identifier constraints. * @param id identifier of the child to find * @return designated {@link TreeNode} instance or <code>null</code> */ @@ -65,12 +86,14 @@ /** * adds child to children collection - * @param identifier child identifier + * @param identifier child identifier. + * Please see {@link #getChildren()} for more information about identifier constraints. * @param child child */ public void addChild(Object identifier, TreeNode<T> child); /** + * Please see {@link #getChildren()} for more information about identifier constraints. * removes child from children collection by child id * @param id id of the child to remove */