 All Implemented Interfaces:
Serializable
,Cloneable
,MutableTreeNode
,TreeNode
 Direct Known Subclasses:
JTree.DynamicUtilTreeNode
DefaultMutableTreeNode
is a generalpurpose node in a tree data
structure.
For examples of using default mutable tree nodes, see
How to Use Trees
in The Java Tutorial.
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 DefaultMutableNode 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 applications running
the same version of Swing. As of 1.4, support for long term storage
of all JavaBeans
has been added to the java.beans
package.
Please see XMLEncoder
.
 See Also:

Field Summary
Modifier and TypeFieldDescriptionprotected boolean
true if the node is able to have childrenarray of children, may be null if this node has no childrenstatic final Enumeration<TreeNode>
An enumeration that is always empty.protected MutableTreeNode
this node's parent, or null if this node has no parentprotected Object
optional user object 
Constructor Summary
ConstructorDescriptionCreates a tree node that has no parent and no children, but which allows children.DefaultMutableTreeNode
(Object userObject) Creates a tree node with no parent, no children, but which allows children, and initializes it with the specified user object.DefaultMutableTreeNode
(Object userObject, boolean allowsChildren) Creates a tree node with no parent, no children, initialized with the specified user object, and that allows children only if specified. 
Method Summary
Modifier and TypeMethodDescriptionvoid
add
(MutableTreeNode newChild) RemovesnewChild
from its parent and makes it a child of this node by adding it to the end of this node's child array.Creates and returns an enumeration that traverses the subtree rooted at this node in breadthfirst order.children()
Creates and returns a forwardorder enumeration of this node's children.clone()
Overridden to make clone public.Creates and returns an enumeration that traverses the subtree rooted at this node in depthfirst order.boolean
Returns true if this node is allowed to have children.getChildAfter
(TreeNode aChild) Returns the child in this node's child array that immediately followsaChild
, which must be a child of this node.getChildAt
(int index) Returns the child at the specified index in this node's child array.getChildBefore
(TreeNode aChild) Returns the child in this node's child array that immediately precedesaChild
, which must be a child of this node.int
Returns the number of children of this node.int
getDepth()
Returns the depth of the tree rooted at this node  the longest distance from this node to a leaf.Returns this node's first child.Finds and returns the first leaf that is a descendant of this node  either this node or its first child's first leaf.int
Returns the index of the specified child in this node's child array.Returns this node's last child.Finds and returns the last leaf that is a descendant of this node  either this node or its last child's last leaf.int
Returns the total number of leaves that are descendants of this node.int
getLevel()
Returns the number of levels above this node  the distance from the root to this node.Returns the leaf after this node or null if this node is the last leaf in the tree.Returns the node that follows this node in a preorder traversal of this node's tree.Returns the next sibling of this node in the parent's children array.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.protected TreeNode[]
getPathToRoot
(TreeNode aNode, int depth) Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.Returns the leaf before this node or null if this node is the first leaf in the tree.Returns the node that precedes this node in a preorder traversal of this node's tree.Returns the previous sibling of this node in the parent's children array.getRoot()
Returns the root of the tree that contains this node.Returns the nearest common ancestor to this node andaNode
.int
Returns the number of siblings of this node.Returns this node's user object.Object[]
Returns the user object path, from the root, to get to this node.void
insert
(MutableTreeNode newChild, int childIndex) RemovesnewChild
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 indexchildIndex
.boolean
isLeaf()
Returns true if this node has no children.boolean
isNodeAncestor
(TreeNode anotherNode) Returns true ifanotherNode
is an ancestor of this node  if it is this node, this node's parent, or an ancestor of this node's parent.boolean
isNodeChild
(TreeNode aNode) Returns true ifaNode
is a child of this node.boolean
isNodeDescendant
(DefaultMutableTreeNode anotherNode) Returns true ifanotherNode
is a descendant of this node  if it is this node, one of this node's children, or a descendant of one of this node's children.boolean
Returns true if and only ifaNode
is in the same tree as this node.boolean
isNodeSibling
(TreeNode anotherNode) Returns true ifanotherNode
is a sibling of (has the same parent as) this node.boolean
isRoot()
Returns true if this node is the root of the tree.pathFromAncestorEnumeration
(TreeNode ancestor) Creates and returns an enumeration that follows the path fromancestor
to this node.Creates and returns an enumeration that traverses the subtree rooted at this node in postorder.Creates and returns an enumeration that traverses the subtree rooted at this node in preorder.void
remove
(int childIndex) Removes the child at the specified index from this node's children and sets that node's parent to null.void
remove
(MutableTreeNode aChild) RemovesaChild
from this node's child array, giving it a null parent.void
Removes all of this node's children, setting their parents to null.void
Removes the subtree rooted at this node from the tree, giving this node a null parent.void
setAllowsChildren
(boolean allows) Determines whether or not this node is allowed to have children.void
setParent
(MutableTreeNode newParent) Sets this node's parent tonewParent
but does not change the parent's child array.void
setUserObject
(Object userObject) Sets the user object for this node touserObject
.toString()
Returns the result of sendingtoString()
to this node's user object, or the empty string if the node has no user object.

Field Details

EMPTY_ENUMERATION
An enumeration that is always empty. This is used when an enumeration of a leaf node's children is requested. 
parent
this node's parent, or null if this node has no parent 
children
array of children, may be null if this node has no children 
userObject
optional user object 
allowsChildren
protected boolean allowsChildrentrue if the node is able to have children


Constructor Details

DefaultMutableTreeNode
public DefaultMutableTreeNode()Creates a tree node that has no parent and no children, but which allows children. 
DefaultMutableTreeNode
Creates a tree node with no parent, no children, but which allows children, and initializes it with the specified user object. Parameters:
userObject
 an Object provided by the user that constitutes the node's data

DefaultMutableTreeNode
Creates a tree node with no parent, no children, initialized with the specified user object, and that allows children only if specified. Parameters:
userObject
 an Object provided by the user that constitutes the node's dataallowsChildren
 if true, the node is allowed to have child nodes  otherwise, it is always a leaf node


Method Details

insert
RemovesnewChild
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 indexchildIndex
.newChild
must not be null and must not be an ancestor of this node. Specified by:
insert
in interfaceMutableTreeNode
 Parameters:
newChild
 the MutableTreeNode to insert under this nodechildIndex
 the index in this node's child array where this node is to be inserted Throws:
ArrayIndexOutOfBoundsException
 ifchildIndex
is out of boundsIllegalArgumentException
 ifnewChild
is null or is an ancestor of this nodeIllegalStateException
 if this node does not allow children See Also:

remove
public void remove(int childIndex) Removes the child at the specified index from this node's children and sets that node's parent to null. The child node to remove must be aMutableTreeNode
. Specified by:
remove
in interfaceMutableTreeNode
 Parameters:
childIndex
 the index in this node's child array of the child to remove Throws:
ArrayIndexOutOfBoundsException
 ifchildIndex
is out of bounds

setParent
Sets this node's parent tonewParent
but does not change the parent's child array. This method is called frominsert()
andremove()
to reassign a child's parent, it should not be messaged from anywhere else. Specified by:
setParent
in interfaceMutableTreeNode
 Parameters:
newParent
 this node's new parent

getParent
Returns this node's parent or null if this node has no parent. 
getChildAt
Returns the child at the specified index in this node's child array. Specified by:
getChildAt
in interfaceTreeNode
 Parameters:
index
 an index into this node's child array Returns:
 the TreeNode in this node's child array at the specified index
 Throws:
ArrayIndexOutOfBoundsException
 ifindex
is out of bounds

getChildCount
public int getChildCount()Returns the number of children of this node. Specified by:
getChildCount
in interfaceTreeNode
 Returns:
 an int giving the number of children of this node

getIndex
Returns the index of the specified child in this node's child array. If the specified node is not a child of this node, returns1
. This method performs a linear search and is O(n) where n is the number of children. Specified by:
getIndex
in interfaceTreeNode
 Parameters:
aChild
 the TreeNode to search for among this node's children Returns:
 an int giving the index of the node in this node's child
array, or
1
if the specified node is a not a child of this node  Throws:
IllegalArgumentException
 ifaChild
is null

children
Creates and returns a forwardorder enumeration of this node's children. Modifying this node's child array invalidates any child enumerations created before the modification. 
setAllowsChildren
public void setAllowsChildren(boolean allows) Determines whether or not this node is allowed to have children. Ifallows
is false, all of this node's children are removed.Note: By default, a node allows children.
 Parameters:
allows
 true if this node is allowed to have children

getAllowsChildren
public boolean getAllowsChildren()Returns true if this node is allowed to have children. Specified by:
getAllowsChildren
in interfaceTreeNode
 Returns:
 true if this node allows children, else false

setUserObject
Sets the user object for this node touserObject
. Specified by:
setUserObject
in interfaceMutableTreeNode
 Parameters:
userObject
 the Object that constitutes this node's userspecified data See Also:

getUserObject
Returns this node's user object. Returns:
 the Object stored at this node by the user
 See Also:

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. Specified by:
removeFromParent
in interfaceMutableTreeNode

remove
RemovesaChild
from this node's child array, giving it a null parent. Specified by:
remove
in interfaceMutableTreeNode
 Parameters:
aChild
 a child of this node to remove Throws:
IllegalArgumentException
 ifaChild
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
RemovesnewChild
from its parent and makes it a child of this node by adding it to the end of this node's child array. Parameters:
newChild
 node to add as a child of this node Throws:
IllegalArgumentException
 ifnewChild
is nullIllegalStateException
 if this node does not allow children See Also:

isNodeAncestor
Returns true ifanotherNode
is an ancestor of this node  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.) IfanotherNode
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
Returns true ifanotherNode
is a descendant of this node  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. IfanotherNode
is null, returns false. This operation is at worst O(h) where h is the distance from the root toanotherNode
. Parameters:
anotherNode
 node to test as descendant of this node Returns:
 true if this node is an ancestor of
anotherNode
 See Also:

isNodeRelated
Returns true if and only ifaNode
is in the same tree as this node. Returns false ifaNode
is null. Parameters:
aNode
 node to find common ancestor with Returns:
 true if
aNode
is in the same tree as this node; false ifaNode
is null  See Also:

getDepth
public int getDepth()Returns the depth of the tree rooted at this node  the longest distance from this node to a leaf. If this node has no children, returns 0. This operation is much more expensive thangetLevel()
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
public int getLevel()Returns the number of levels above this node  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:

getPath
Returns the path from the root, to get to this node. The last element in the path is this node. Returns:
 an array of TreeNode objects giving the path, where the first element in the path is the root and the last element is this node.

getPathToRoot
Builds the parents of node up to and including the root node, where the original node is the last element in the returned array. The length of the returned array gives the node's depth in the tree. Parameters:
aNode
 the TreeNode to get the path fordepth
 an int giving the number of steps already taken towards the root (on recursive calls), used to size the returned array Returns:
 an array of TreeNodes giving the path from the root to the specified node

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. Returns:
 the user object path, from the root, to get to this node

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:

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
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:

getPreviousNode
Returns the node that precedes this node in a preorder traversal of this node's tree. Returnsnull
if this node is the first node of the traversal  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
Creates and returns an enumeration that traverses the subtree rooted at this node in preorder. The first node returned by the enumeration'snextElement()
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
Creates and returns an enumeration that traverses the subtree rooted at this node in postorder. The first node returned by the enumeration'snextElement()
method is the leftmost leaf. This is the same as a depthfirst 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:

breadthFirstEnumeration
Creates and returns an enumeration that traverses the subtree rooted at this node in breadthfirst order. The first node returned by the enumeration'snextElement()
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 breadthfirst order
 See Also:

depthFirstEnumeration
Creates and returns an enumeration that traverses the subtree rooted at this node in depthfirst order. The first node returned by the enumeration'snextElement()
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 depthfirst order
 See Also:

pathFromAncestorEnumeration
Creates and returns an enumeration that follows the path fromancestor
to this node. The enumeration'snextElement()
method first returnsancestor
, then the child ofancestor
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 andancestor
, inclusive. EachnextElement()
message is O(1).Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.
 Parameters:
ancestor
 the node to start enumeration from Returns:
 an enumeration for following the path from an ancestor of this node to this one
 Throws:
IllegalArgumentException
 ifancestor
is not an ancestor of this node See Also:

isNodeChild
Returns true ifaNode
is a child of this node. IfaNode
is null, this method returns false. Parameters:
aNode
 the node to determinate whether it is a child Returns:
 true if
aNode
is a child of this node; false ifaNode
is null

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
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
Returns the child in this node's child array that immediately followsaChild
, which must be a child of this node. IfaChild
is the last child, returns null. This method performs a linear search of this node's children foraChild
and is O(n) where n is the number of children; to traverse the entire array of children, use an enumeration instead. Parameters:
aChild
 the child node to look for next child after it Returns:
 the child of this node that immediately follows
aChild
 Throws:
IllegalArgumentException
 ifaChild
is null or is not a child of this node See Also:

getChildBefore
Returns the child in this node's child array that immediately precedesaChild
, which must be a child of this node. IfaChild
is the first child, returns null. This method performs a linear search of this node's children foraChild
and is O(n) where n is the number of children. Parameters:
aChild
 the child node to look for previous child before it Returns:
 the child of this node that immediately precedes
aChild
 Throws:
IllegalArgumentException
 ifaChild
is null or is not a child of this node

isNodeSibling
Returns true ifanotherNode
is a sibling of (has the same parent as) this node. A node is its own sibling. IfanotherNode
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 (if it has no parent or no siblings, this method returns1
). Returns:
 the number of siblings of this node

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:

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 withgetAllowsChildren

getFirstLeaf
Finds and returns the first leaf that is a descendant of this node  either this node or its first child's first leaf. Returns this node if it is a leaf. Returns:
 the first leaf in the subtree rooted at this node
 See Also:

getLastLeaf
Finds and returns the last leaf that is a descendant of this node  either this node or its last child's last leaf. Returns this node if it is a leaf. Returns:
 the last leaf in the subtree rooted at this node
 See Also:

getNextLeaf
Returns the leaf after this node or null if this node is the last leaf in the tree.In this implementation of the
MutableNode
interface, this operation is very inefficient. In order to determine the next node, this method first performs a linear search in the parent's childlist in order to find the current node.That implementation makes the operation suitable for short traversals from a known position. But to traverse all of the leaves in the tree, you should use
depthFirstEnumeration
to enumerate the nodes in the tree and useisLeaf
on each node to determine which are leaves. Returns:
 returns the next leaf past this node
 See Also:

getPreviousLeaf
Returns the leaf before this node or null if this node is the first leaf in the tree.In this implementation of the
MutableNode
interface, this operation is very inefficient. In order to determine the previous node, this method first performs a linear search in the parent's childlist in order to find the current node.That implementation makes the operation suitable for short traversals from a known position. But to traverse all of the leaves in the tree, you should use
depthFirstEnumeration
to enumerate the nodes in the tree and useisLeaf
on each node to determine which are leaves. Returns:
 returns the leaf before this node
 See Also:

getLeafCount
public int getLeafCount()Returns the total number of leaves that are descendants of this node. If this node is a leaf, returns1
. 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:

toString
Returns the result of sendingtoString()
to this node's user object, or the empty string if the node has no user 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.
