This patch (committed) fixes the failures in the new Mauve tests I committed earlier
today for the DefaultMutableTreeNode class, and adds API docs:
2006-03-07 David Gilbert <[EMAIL PROTECTED]>
* javax/swing/tree/DefaultMutableTreeNode.java: API docs all over plus
(clone): Reimplemented,
(add): Throw IllegalArgumentException if child is an ancestor,
(remove(int)): Set child's parent to null,
(remove(MutableTreeNode)): Check arguments and set child's parent to
null,
(insert): Check allowsChildren flag, check for null argument, and
check for a node that is an ancestor,
(getIndex): Throw IllegalArgumentException for null argument,
(setAllowsChildren): If setting to false, remove existing children,
(removeAllChildren): Set parent to null for removed children.
Regards,
Dave
Index: javax/swing/tree/DefaultMutableTreeNode.java
===================================================================
RCS file:
/sources/classpath/classpath/javax/swing/tree/DefaultMutableTreeNode.java,v
retrieving revision 1.13
diff -u -r1.13 DefaultMutableTreeNode.java
--- javax/swing/tree/DefaultMutableTreeNode.java 19 Oct 2005 15:03:15
-0000 1.13
+++ javax/swing/tree/DefaultMutableTreeNode.java 7 Mar 2006 11:49:21
-0000
@@ -1,5 +1,5 @@
/* DefaultMutableTreeNode.java --
- Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc.
+ Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -53,7 +53,7 @@
/**
- * DefaultMutableTreeNode
+ * A default implementation of the [EMAIL PROTECTED] MutableTreeNode}
interface.
*
* @author Andrew Selkirk
* @author Robert Schuster ([EMAIL PROTECTED])
@@ -64,18 +64,19 @@
private static final long serialVersionUID = -4298474751201349152L;
/**
- * EMPTY_ENUMERATION
+ * An empty enumeration, returned by [EMAIL PROTECTED] #children()} if a
node has no
+ * children.
*/
public static final Enumeration EMPTY_ENUMERATION =
EmptyEnumeration.getInstance();
/**
- * parent
+ * The parent of this node (possibly <code>null</code>).
*/
protected MutableTreeNode parent;
/**
- * children
+ * The child nodes for this node (may be empty).
*/
protected Vector children = new Vector();
@@ -91,7 +92,7 @@
/**
* Creates a <code>DefaultMutableTreeNode</code> object.
- * This node allows to add child nodes.
+ * This is equivalent to <code>DefaultMutableTreeNode(null, true)</code>.
*/
public DefaultMutableTreeNode()
{
@@ -100,9 +101,10 @@
/**
* Creates a <code>DefaultMutableTreeNode</code> object with the given
- * user object attached to it. This node allows to add child nodes.
+ * user object attached to it. This is equivalent to
+ * <code>DefaultMutableTreeNode(userObject, true)</code>.
*
- * @param userObject the user object
+ * @param userObject the user object (<code>null</code> permitted).
*/
public DefaultMutableTreeNode(Object userObject)
{
@@ -113,7 +115,7 @@
* Creates a <code>DefaultMutableTreeNode</code> object with the given
* user object attached to it.
*
- * @param userObject the user object
+ * @param userObject the user object (<code>null</code> permitted).
* @param allowsChildren <code>true</code> if the code allows to add child
* nodes, <code>false</code> otherwise
*/
@@ -124,28 +126,22 @@
}
/**
- * clone
+ * Returns a clone of the node. The clone contains a shallow copy of the
+ * user object, and does not copy the parent node or the child nodes.
*
- * @return Object
+ * @return A clone of the node.
*/
public Object clone()
{
- try
- {
- return super.clone();
- // TODO: Do we need to do more here ?
- }
- catch (CloneNotSupportedException e)
- {
- // This never happens.
- return null;
- }
+ return new DefaultMutableTreeNode(this.userObject, this.allowsChildren);
}
/**
- * Returns a string representation of this node
+ * Returns a string representation of the node. This implementation returns
+ * <code>getUserObject().toString()</code>, or <code>null</code> if there
+ * is no user object.
*
- * @return a human-readable String representing this node
+ * @return A string representation of the node (possibly <code>null</code>).
*/
public String toString()
{
@@ -156,20 +152,28 @@
}
/**
- * Adds a new child node to this node.
+ * Adds a new child node to this node and sets this node as the parent of
+ * the child node. The child node must not be an ancestor of this node.
*
- * @param child the child node
+ * @param child the child node (<code>null</code> not permitted).
*
- * @throws IllegalArgumentException if <code>child</code> is null
- * @throws IllegalStateException if the node does not allow children
+ * @throws IllegalStateException if [EMAIL PROTECTED] #getAllowsChildren()}
returns
+ * <code>false</code>.
+ * @throws IllegalArgumentException if [EMAIL PROTECTED] #isNodeAncestor}
returns
+ * <code>true</code>.
+ * @throws IllegalArgumentException if <code>child</code> is
+ * <code>null</code>.
*/
public void add(MutableTreeNode child)
{
+ if (! allowsChildren)
+ throw new IllegalStateException();
+
if (child == null)
throw new IllegalArgumentException();
- if (! allowsChildren)
- throw new IllegalStateException();
+ if (isNodeAncestor(child))
+ throw new IllegalArgumentException("Cannot add ancestor node.");
children.add(child);
child.setParent(this);
@@ -178,7 +182,7 @@
/**
* Returns the parent node of this node.
*
- * @return the parent node
+ * @return The parent node (possibly <code>null</code>).
*/
public TreeNode getParent()
{
@@ -186,23 +190,39 @@
}
/**
- * Removes the child with the given index from this node
+ * Removes the child with the given index from this node.
*
- * @param index the index
+ * @param index the index (in the range <code>0</code> to
+ * <code>getChildCount() - 1</code>).
+ *
+ * @throws ArrayIndexOutOfBoundsException if <code>index</code> is outside
+ * the valid range.
*/
public void remove(int index)
{
- children.remove(index);
+ MutableTreeNode child = (MutableTreeNode) children.remove(index);
+ child.setParent(null);
}
/**
- * Removes the given child from this node.
+ * Removes the given child from this node and sets its parent to
+ * <code>null</code>.
*
- * @param node the child node
+ * @param node the child node (<code>null</code> not permitted).
+ *
+ * @throws IllegalArgumentException if <code>node</code> is not a child of
+ * this node.
+ * @throws IllegalArgumentException if <code>node</code> is null.
*/
public void remove(MutableTreeNode node)
{
+ if (node == null)
+ throw new IllegalArgumentException("Null 'node' argument.");
+ if (node.getParent() != this)
+ throw new IllegalArgumentException(
+ "The given 'node' is not a child of this node.");
children.remove(node);
+ node.setParent(null);
}
/**
@@ -235,11 +255,23 @@
/**
* Inserts given child node at the given index.
*
- * @param node the child node
+ * @param node the child node (<code>null</code> not permitted).
* @param index the index.
+ *
+ * @throws IllegalArgumentException if <code>node</code> is
+ * </code>null</code>.
*/
public void insert(MutableTreeNode node, int index)
{
+ if (! allowsChildren)
+ throw new IllegalStateException();
+
+ if (node == null)
+ throw new IllegalArgumentException("Null 'node' argument.");
+
+ if (isNodeAncestor(node))
+ throw new IllegalArgumentException("Cannot insert ancestor node.");
+
children.insertElementAt(node, index);
}
@@ -300,24 +332,33 @@
}
/**
- * Returns the child index for a given node.
- *
- * @param node this node
- *
- * @return the index
+ * Returns the index of the specified child node, or -1 if the node is not
+ * in fact a child of this node.
+ *
+ * @param node the node (<code>null</code> not permitted).
+ *
+ * @return The index of the specified child node, or -1.
+ *
+ * @throws IllegalArgumentException if <code>node</code> is
<code>null</code>.
*/
public int getIndex(TreeNode node)
{
+ if (node == null)
+ throw new IllegalArgumentException("Null 'node' argument.");
return children.indexOf(node);
}
/**
- * setAllowsChildren
+ * Sets the flag that controls whether or not this node allows the addition
/
+ * insertion of child nodes. If the flag is set to <code>false</code>, any
+ * existing children are removed.
*
- * @param allowsChildren TODO
+ * @param allowsChildren the flag.
*/
public void setAllowsChildren(boolean allowsChildren)
{
+ if (!allowsChildren)
+ removeAllChildren();
this.allowsChildren = allowsChildren;
}
@@ -366,15 +407,24 @@
*/
public void removeAllChildren()
{
- children.removeAllElements();
+ for (int i = getChildCount() - 1; i >= 0; i--)
+ remove(i);
}
/**
- * isNodeAncestor
- *
- * @param node TODO
+ * Returns <code>true</code> if <code>node</code> is an ancestor of this
+ * tree node, and <code>false</code> otherwise. An ancestor node is any of:
+ * <ul>
+ * <li>this tree node;</li>
+ * <li>the parent node (if there is one);</li>
+ * <li>any ancestor of the parent node;</li>
+ * </ul>
+ * If <code>node</code> is <code>null</code>, this method returns
+ * <code>false</code>.
+ *
+ * @param node the node (<code>null</code> permitted).
*
- * @return boolean
+ * @return A boolean.
*/
public boolean isNodeAncestor(TreeNode node)
{
@@ -383,19 +433,26 @@
TreeNode current = this;
- while (current != null
- && current != node)
+ while (current != null && current != node)
current = current.getParent();
return current == node;
}
/**
- * isNodeDescendant
- *
- * @param node TODO
+ * Returns <code>true</code> if <code>node</code> is a descendant of this
+ * tree node, and <code>false</code> otherwise. A descendant node is any of:
+ * <ul>
+ * <li>this tree node;</li>
+ * <li>the child nodes belonging to this tree node, if there are any;</li>
+ * <li>any descendants of the child nodes;</li>
+ * </ul>
+ * If <code>node</code> is <code>null</code>, this method returns
+ * <code>false</code>.
+ *
+ * @param node the node (<code>null</code> permitted).
*
- * @return boolean
+ * @return A boolean.
*/
public boolean isNodeDescendant(DefaultMutableTreeNode node)
{
@@ -722,11 +779,13 @@
}
/**
- * isNodeChild
+ * Returns <code>true</code> if <code>node</code> is a child of this tree
+ * node, and <code>false</code> otherwise. If <code>node</code> is
+ * <code>null</code>, this method returns <code>false</code>.
*
- * @param node TODO
+ * @param node the node (<code>null</code> permitted).
*
- * @return boolean
+ * @return A boolean.
*/
public boolean isNodeChild(TreeNode node)
{
