Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Class java.awt.swing.tree.DefaultMutableTreeNode

java.lang.Object
    |
    +----java.awt.swing.tree.DefaultMutableTreeNode
Subclasses:
JTree.DynamicUtilTreeNode

public class DefaultMutableTreeNode
extends Object
implements Cloneable, MutableTreeNode, Serializable

A DefaultMutableTreeNode is a general-purpose node in a tree data structure. A tree node may have at most one parent and 0 or more children. DefaultMutableTreeNode provides operations for examining and modifying a node's parent and children and also operations for examining the tree that the node is a part of. A node's tree is the set of all nodes that can be reached by starting at the node and following all the possible links to parents and children. A node with no parent is the root of its tree; a node with no children is a leaf. A tree may consist of many subtrees, each node acting as the root for its own subtree.

This class provides enumerations for efficiently traversing a tree or subtree in various orders or for following the path between two nodes. A DefaultMutableTreeNode may also hold a reference to a user object, the use of which is left to the user. Asking a DefaultMutableTreeNode for its string representation with toString() returns the string representation of its user object.

This is not a thread safe class.If you intend to use a DefaultMutableTreeNode (or a tree of TreeNodes) in more than one thread, you need to do your own synchronizing. A good convention to adopt is synchronizing on the root node of a tree.

While DefaultMutableTreeNode implements the MutableTreeNode interface and will allow you to add in any implementation of MutableTreeNode not all of the methods in DefaultMutableTreeNode will be applicable to all MutableTreeNodes implementations. Especially with some of the enumerations that are provided, using some of these methods assumes the DefaultMutableTreeNode contains only DefaultMutableNodes instances. All of the TreeNode/MutableTreeNode methods will behave as defined no matter what implementations are added.

Warning: serialized objects of this class will not be compatible with future swing releases. The current serialization support is appropriate for short term storage or RMI between Swing1.0 applications. It will not be possible to load serialized Swing1.0 objects with future releases of Swing. The JDK1.2 release of Swing will be the compatibility baseline for the serialized form of Swing objects.


Field Summary
boolean  allowsChildren
true iff the node is able to have children
Vector  children
array of children, may be null if this node has no children
static Enumeration  EMPTY_ENUMERATION
 
MutableTreeNode  parent
this node's parent, or null if this node has no parent
Object  userObject
optional user object
 

Constructor Summary
 DefaultMutableTreeNode()
Creates a tree node with no parent and no children.
 DefaultMutableTreeNode(Object userObject)
Creates a tree node with no parent, no children, and a user object userObject allowing children.
 DefaultMutableTreeNode(Object userObject, boolean allowsChildren)
Creates a tree node with no parent, no children, and a user object userObject and allows children set to allowsChildren.
 

Method Summary
void  add(MutableTreeNode newChild)
Removes newChild from its parent and makes it a child of this node by adding it to the end of this node's child array.
Enumeration  breadthFirstEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in breadth-first order.
Enumeration  children()
Creates and returns a forward-order enumeration of this node's children.
Object  clone()
Overridden to make clone public.
Enumeration  depthFirstEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in depth-first order.
boolean  getAllowsChildren()
Returns true if an only if this node is allowed to have children.
TreeNode  getChildAfter(TreeNode aChild)
Returns the child in this node's child array that immediately follows aChild, which must be a child of this node.
TreeNode  getChildAt(int index)
Returns the child at index in this node's child array.
TreeNode  getChildBefore(TreeNode aChild)
Returns the child in this node's child array that immediately precedes aChild, which must be a child of this node.
int  getChildCount()
Returns the number of children of this node.
int  getDepth()
Returns the depth of the tree rooted at this node, i.e.
TreeNode  getFirstChild()
Returns this node's first child.
DefaultMutableTreeNode  getFirstLeaf()
Finds and returns the first leaf that is a descendant of this node, i.e.
int  getIndex(TreeNode aChild)
Returns the index of aChild in this node's child array.
TreeNode  getLastChild()
Returns this node's last child.
DefaultMutableTreeNode  getLastLeaf()
Finds and returns the last leaf that is a descendant of this node, i.e.
int  getLeafCount()
Returns the total number of leaves that are descendants of this node.
int  getLevel()
Returns the number of levels above this node, i.e.
DefaultMutableTreeNode  getNextLeaf()
Returns the leaf after this node or null if this node is the last leaf in its tree.
DefaultMutableTreeNode  getNextNode()
Returns the node that follows this node in a preorder traversal of this node's tree.
DefaultMutableTreeNode  getNextSibling()
Returns the next sibling of this node in the parent's children array.
TreeNode  getParent()
Returns this node's parent or null if this node has no parent.
TreeNode[]  getPath()
Returns the path, from the root, to get to this node.
TreeNode[]  getPathToRoot(TreeNode aNode, int depth)
 
DefaultMutableTreeNode  getPreviousLeaf()
Returns the leaf before this node or null if this node is the first leaf in its tree.
DefaultMutableTreeNode  getPreviousNode()
Returns the node that precedes this node in a preorder traversal of this node's tree.
DefaultMutableTreeNode  getPreviousSibling()
Returns the previous sibling of this node in the parent's children array.
TreeNode  getRoot()
Returns the root of the tree that contains this node.
TreeNode  getSharedAncestor(DefaultMutableTreeNode aNode)
Returns the nearest common ancestor to this node and aNode.
int  getSiblingCount()
Returns the number of siblings of this node.
Object  getUserObject()
Returns the user object.
Object[]  getUserObjectPath()
Returns the user object path, from the root, to get to this node.
void  insert(MutableTreeNode newChild, int childIndex)
Removes newChild from its present parent (if it has a parent), sets the child's parent to this node, and then adds the child to this node's child array at index childIndex.
boolean  isLeaf()
Returns true if this node has no children.
boolean  isNodeAncestor(TreeNode anotherNode)
Returns true if anotherNode is an ancestor of this node, i.e.
boolean  isNodeChild(TreeNode aNode)
Returns true if aNode is a child of this node.
boolean  isNodeDescendant(DefaultMutableTreeNode anotherNode)
Returns true if anotherNode is a descendant of this node; i.e.
boolean  isNodeRelated(DefaultMutableTreeNode aNode)
Returns true if and only if aNode is in the same tree as this node.
boolean  isNodeSibling(TreeNode anotherNode)
Returns true if anotherNode is a sibling of (i.e.
boolean  isRoot()
Returns true if this node is the root of the tree.
Enumeration  pathFromAncestorEnumeration(TreeNode ancestor)
Creates and returns an enumeration that follows the path from ancestor to this node.
Enumeration  postorderEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in postorder.
Enumeration  preorderEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in preorder.
void  remove(int childIndex)
Removes the child at childIndex from this node's children index and sets its parent to null.
void  remove(MutableTreeNode aChild)
Removes aChild from this node's child array, giving it a null parent.
void  removeAllChildren()
Removes all of this node's children, setting their parents to null.
void  removeFromParent()
Removes the subtree rooted at this node from the tree, giving this node a null parent.
void  setAllowsChildren(boolean allows)
Sets whether or not this node is allowed to have children.
void  setParent(MutableTreeNode newParent)
Sets this node's parent to newParent but does not change the parent's child array.
void  setUserObject(Object userObject)
Sets the user object to userObject.
String  toString()
Returns the result of sending toString() to this node's user object, or null if this node has no user object.
 
Methods inherited from class java.lang.Object
 clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY_ENUMERATION

public static final Enumeration EMPTY_ENUMERATION

parent

protected MutableTreeNode parent
this node's parent, or null if this node has no parent

children

protected Vector children
array of children, may be null if this node has no children

userObject

protected transient Object userObject
optional user object

allowsChildren

protected boolean allowsChildren
true iff the node is able to have children
Constructor Detail

DefaultMutableTreeNode

public DefaultMutableTreeNode()
Creates a tree node with no parent and no children.

DefaultMutableTreeNode

public DefaultMutableTreeNode(Object userObject)
Creates a tree node with no parent, no children, and a user object userObject allowing children.

DefaultMutableTreeNode

public DefaultMutableTreeNode(Object userObject,
                              boolean allowsChildren)
Creates a tree node with no parent, no children, and a user object userObject and allows children set to allowsChildren.
Method Detail

insert

public void insert(MutableTreeNode newChild,
                   int childIndex)
Removes newChild from its present parent (if it has a parent), sets the child's parent to this node, and then adds the child to this node's child array at index childIndex. newChild must not be null and must not be an ancestor of this node.
Implements:
insert in interface MutableTreeNode
Parameters:
newChild - the node to become a child of this node
childIndex - the index in this node's child array where this node should be inserted
Throws:
ArrayIndexOutOfBoundsException - if childIndex is out of bounds
IllegalArgumentException - if newChild is null or is an ancestor of this node
IllegalStateException - if this node does not allow children
See Also:
isNodeDescendant

remove

public void remove(int childIndex)
Removes the child at childIndex from this node's children index and sets its parent to null. setParent is messaged to the child, meaning it must be a MutableTreeNode.
Implements:
remove in interface MutableTreeNode
Parameters:
childIndex - the index in this node's child array of the child to remove
Throws:
ArrayIndexOutOfBoundsException - if childIndex is out of bounds

setParent

public void setParent(MutableTreeNode newParent)
Sets this node's parent to newParent but does not change the parent's child array. This method is sent from insert() and remove() to reassign a child's parent, it should not be messaged from anywhere else.
Implements:
setParent in interface MutableTreeNode
Parameters:
newParent - this node's new parent

getParent

public TreeNode getParent()
Returns this node's parent or null if this node has no parent.
Returns:
this node's parent, or null if this node has no parent

getChildAt

public TreeNode getChildAt(int index)
Returns the child at index in this node's child array.
Parameters:
index - an index into this node's child array
Returns:
the child in this node's child array at index
Throws:
ArrayIndexOutOfBoundsException - if index is out of bounds

getChildCount

public int getChildCount()
Returns the number of children of this node.
Returns:
the number of children of this node

getIndex

public int getIndex(TreeNode aChild)
Returns the index of aChild in this node's child array. If aChild is not a child of this node, returns -1. This method performs a linear search and is O(n) where n is the number of children.
Parameters:
aChild - a child to search this node's children for
Returns:
the index into this node's child array of aChild, or -1
Throws:
IllegalArgumentException - if aChild is null

children

public Enumeration children()
Creates and returns a forward-order enumeration of this node's children. Modifying this node's child array invalidates any child enumerations created before the modification.
Returns:
an enumeration of this node's children

setAllowsChildren

public void setAllowsChildren(boolean allows)
Sets whether or not this node is allowed to have children. If allows is false, all of this node's children are removed.

By default, a node allows children.

Parameters:
allows - true if and only iff this node should be allowed to have children
See Also:
allowsChildren

getAllowsChildren

public boolean getAllowsChildren()
Returns true if an only if this node is allowed to have children.
Returns:
true if and only if this node allows children

setUserObject

public void setUserObject(Object userObject)
Sets the user object to userObject.
Implements:
setUserObject in interface MutableTreeNode
Parameters:
userObject - this node's new user object
See Also:
getUserObject, toString

getUserObject

public Object getUserObject()
Returns the user object.
Returns:
this node's user object
See Also:
setUserObject, toString

removeFromParent

public void removeFromParent()
Removes the subtree rooted at this node from the tree, giving this node a null parent. Does nothing if this node is the root of its tree.
Implements:
removeFromParent in interface MutableTreeNode

remove

public void remove(MutableTreeNode aChild)
Removes aChild from this node's child array, giving it a null parent.
Implements:
remove in interface MutableTreeNode
Parameters:
aChild - a child of this node to remove
Throws:
IllegalArgumentException - if aChild is null or is not a child of this node

removeAllChildren

public void removeAllChildren()
Removes all of this node's children, setting their parents to null. If this node has no children, this method does nothing.

add

public void add(MutableTreeNode newChild)
Removes newChild from its parent and makes it a child of this node by adding it to the end of this node's child array.
Parameters:
aNode - node to add as a child of this node
Throws:
IllegalArgumentException - if newChild is null
IllegalStateException - if this node does not allow children
See Also:
insert

isNodeAncestor

public boolean isNodeAncestor(TreeNode anotherNode)
Returns true if anotherNode is an ancestor of this node, i.e. if it is this node, this node's parent, or an ancestor of this node's parent. Note that a node is considered an ancestor of itself. If anotherNode is null, this method returns false. This operation is at worst O(h) where h is the distance from the root to this node.
Parameters:
anotherNode - node to test as an ancestor of this node
Returns:
true if this node is a descendant of anotherNode
See Also:
isNodeDescendant, getSharedAncestor

isNodeDescendant

public boolean isNodeDescendant(DefaultMutableTreeNode anotherNode)
Returns true if anotherNode is a descendant of this node; i.e. if it is this node, one of this node's children, or a descendant of one of this node's children. Note that a node is considered a descendant of itself. If anotherNode is null, returns false. This operation is at worst O(h) where h is the distance from the root to anotherNode.
Parameters:
anotherNode - node to test as descendant of this node
Returns:
true if this node is an ancestor of anotherNode
See Also:
isNodeAncestor, getSharedAncestor

getSharedAncestor

public TreeNode getSharedAncestor(DefaultMutableTreeNode aNode)
Returns the nearest common ancestor to this node and aNode. Returns null, if no such ancestor exists, i.e. if this node and aNode are in different trees or if aNode is null. A node is considered an ancestor of itself.
Parameters:
aNode - node to find common ancestor with
Returns:
nearest ancestor common to this node and aNode, or null if none
See Also:
isNodeAncestor, isNodeDescendant

isNodeRelated

public boolean isNodeRelated(DefaultMutableTreeNode aNode)
Returns true if and only if aNode is in the same tree as this node. Returns false if aNode is null.
Returns:
true if aNode is in the same tree as this node; false if aNode is null
See Also:
getSharedAncestor, getRoot

getDepth

public int getDepth()
Returns the depth of the tree rooted at this node, i.e. the longest distance from this node to a leaf. If this node has no children, returns 0. This operation is much more expensive than getLevel() because it must effectively traverse the entire tree rooted at this node.
Returns:
the depth of the tree whose root is this node
See Also:
getLevel

getLevel

public int getLevel()
Returns the number of levels above this node, i.e. the distance from the root to this node. If this node is the root, returns 0.
Returns:
the number of levels above this node
See Also:
getDepth

getPath

public TreeNode[] getPath()
Returns the path, from the root, to get to this node. The last element in the path will be this node.

getPathToRoot

protected TreeNode[] getPathToRoot(TreeNode aNode,
                                   int depth)

getUserObjectPath

public Object[] getUserObjectPath()
Returns the user object path, from the root, to get to this node. If some of the TreeNodes in the path have null user objects, the returned path will contain nulls.

getRoot

public TreeNode getRoot()
Returns the root of the tree that contains this node. The root is the ancestor with a null parent.
Returns:
the root of the tree that contains this node
See Also:
isNodeAncestor

isRoot

public boolean isRoot()
Returns true if this node is the root of the tree. The root is the only node in the tree with a null parent; every tree has exactly one root.
Returns:
true if this node is the root of its tree

getNextNode

public DefaultMutableTreeNode getNextNode()
Returns the node that follows this node in a preorder traversal of this node's tree. Returns null if this node is the last node of the traversal. This is an inefficient way to traverse the entire tree; use an enumeration, instead.
Returns:
the node that follows this node in a preorder traversal, or null if this node is last
See Also:
preorderEnumeration

getPreviousNode

public DefaultMutableTreeNode getPreviousNode()
Returns the node that precedes this node in a preorder traversal of this node's tree. Returns null if this node is the first node of the traveral, i.e. the root of the tree. This is an inefficient way to traverse the entire tree; use an enumeration, instead.
Returns:
the node that precedes this node in a preorder traversal, or null if this node is the first
See Also:
preorderEnumeration

preorderEnumeration

public Enumeration preorderEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in preorder. The first node returned by the enumeration's nextElement() method is this node.

Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.

Returns:
an enumeration for traversing the tree in preorder
See Also:
postorderEnumeration

postorderEnumeration

public Enumeration postorderEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in postorder. The first node returned by the enumeration's nextElement() method is the leftmost leaf. This is the same as a depth-first traversal.

Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.

Returns:
an enumeration for traversing the tree in postorder
See Also:
depthFirstEnumeration, preorderEnumeration

breadthFirstEnumeration

public Enumeration breadthFirstEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in breadth-first order. The first node returned by the enumeration's nextElement() method is this node.

Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.

Returns:
an enumeration for traversing the tree in breadth-first order
See Also:
depthFirstEnumeration

depthFirstEnumeration

public Enumeration depthFirstEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in depth-first order. The first node returned by the enumeration's nextElement() method is the leftmost leaf. This is the same as a postorder traversal.

Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.

Returns:
an enumeration for traversing the tree in depth-first order
See Also:
breadthFirstEnumeration, postorderEnumeration

pathFromAncestorEnumeration

public Enumeration pathFromAncestorEnumeration(TreeNode ancestor)
Creates and returns an enumeration that follows the path from ancestor to this node. The enumeration's nextElement() method first returns ancestor, then the child of ancestor that is an ancestor of this node, and so on, and finally returns this node. Creation of the enumeration is O(m) where m is the number of nodes between this node and ancestor, inclusive. Each nextElement() message is O(1).

Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.

Returns:
an enumeration for following the path from an ancestor of this node to this one
Throws:
IllegalArgumentException - if ancestor is not an ancestor of this node
See Also:
isNodeAncestor, isNodeDescendant

isNodeChild

public boolean isNodeChild(TreeNode aNode)
Returns true if aNode is a child of this node. If aNode is null, this method returns false.
Returns:
true if aNode is a child of this node; false if aNode is null

getFirstChild

public TreeNode getFirstChild()
Returns this node's first child. If this node has no children, throws NoSuchElementException.
Returns:
the first child of this node
Throws:
NoSuchElementException - if this node has no children

getLastChild

public TreeNode getLastChild()
Returns this node's last child. If this node has no children, throws NoSuchElementException.
Returns:
the last child of this node
Throws:
NoSuchElementException - if this node has no children

getChildAfter

public TreeNode getChildAfter(TreeNode aChild)
Returns the child in this node's child array that immediately follows aChild, which must be a child of this node. If aChild is the last child, returns null. This method performs a linear search of this node's children for aChild and is O(n) where n is the number of children; to traverse the entire array of children, use an enumeration instead.
Returns:
the child of this node that immediately follows aChild
Throws:
IllegalArgumentException - if aChild is null or is not a child of this node
See Also:
children

getChildBefore

public TreeNode getChildBefore(TreeNode aChild)
Returns the child in this node's child array that immediately precedes aChild, which must be a child of this node. If aChild is the first child, returns null. This method performs a linear search of this node's children for aChild and is O(n) where n is the number of children.
Returns:
the child of this node that immediately precedes aChild
Throws:
IllegalArgumentException - if aChild is null or is not a child of this node

isNodeSibling

public boolean isNodeSibling(TreeNode anotherNode)
Returns true if anotherNode is a sibling of (i.e. has the same parent as) this node. A node is its own sibling. If anotherNode is null, returns false.
Parameters:
anotherNode - node to test as sibling of this node
Returns:
true if anotherNode is a sibling of this node

getSiblingCount

public int getSiblingCount()
Returns the number of siblings of this node. A node is its own sibling (i.e. if it has no parent or no siblings, this method returns 1).
Returns:
the number of siblings of this node

getNextSibling

public DefaultMutableTreeNode getNextSibling()
Returns the next sibling of this node in the parent's children array. Returns null if this node has no parent or is the parent's last child. This method performs a linear search that is O(n) where n is the number of children; to traverse the entire array, use the parent's child enumeration instead.
Returns:
the sibling of this node that immediately follows this node
See Also:
children

getPreviousSibling

public DefaultMutableTreeNode getPreviousSibling()
Returns the previous sibling of this node in the parent's children array. Returns null if this node has no parent or is the parent's first child. This method performs a linear search that is O(n) where n is the number of children.
Returns:
the sibling of this node that immediately precedes this node

isLeaf

public boolean isLeaf()
Returns true if this node has no children. To distinguish between nodes that have no children and nodes that cannot have children (e.g. to distinguish files from empty directories), use this method in conjunction with getAllowsChildren
Returns:
true if this node has no children
See Also:
getAllowsChildren

getFirstLeaf

public DefaultMutableTreeNode getFirstLeaf()
Finds and returns the first leaf that is a descendant of this node, i.e. this node or its first child's first leaf. Note that if this node is a leaf, this method returns this node.
Returns:
the first leaf in the subtree rooted at this node
See Also:
isLeaf, isNodeDescendant

getLastLeaf

public DefaultMutableTreeNode getLastLeaf()
Finds and returns the last leaf that is a descendant of this node, i.e. this node or its last child's last leaf. Note that if this node is a leaf, this method returns this node.
Returns:
the last leaf in the subtree rooted at this node
See Also:
isLeaf, isNodeDescendant

getNextLeaf

public DefaultMutableTreeNode getNextLeaf()
Returns the leaf after this node or null if this node is the last leaf in its tree. This method performs a linear search that is O(n) where n is the number of children in this node's parent; to traverse all of the leaves in the tree, use an enumeration and isLeaf() instead. PENDING: better description?
Returns:
returns the next leaf past this node
See Also:
depthFirstEnumeration, isLeaf

getPreviousLeaf

public DefaultMutableTreeNode getPreviousLeaf()
Returns the leaf before this node or null if this node is the first leaf in its tree. This method performs a linear search that is O(n) where n is the number of children in this node's parent; to traverse all of the leaves in the tree, structure the code to use an enumeration and isLeaf() instead. PENDING: better description?
Returns:
returns the leaf before this node
See Also:
depthFirstEnumeration, isLeaf

getLeafCount

public int getLeafCount()
Returns the total number of leaves that are descendants of this node. If this node is a leaf, returns 1. This method is O(n) where n is the number of descendants of this node.
Returns:
the number of leaves beneath this node
See Also:
isNodeAncestor

toString

public String toString()
Returns the result of sending toString() to this node's user object, or null if this node has no user object.
Overrides:
toString in class Object
See Also:
getUserObject

clone

public Object clone()
Overridden to make clone public. Returns a shallow copy of this node; the new node has no parent or children and has a reference to the same user object, if any.
Returns:
a copy of this node
Overrides:
clone in class Object

Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Submit a bug or feature
Submit comments/suggestions about new javadoc look.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.