com.myarch.treeiterator
Class TreeIterator

java.lang.Object
  |
  +--com.myarch.treeiterator.TreeIterator
All Implemented Interfaces:
java.util.Iterator, TreeConstants

public class TreeIterator
extends java.lang.Object
implements TreeConstants, java.util.Iterator

Iterates over the tree. Preorder traversal is used, i.e., node is processed before its children.
Depth of traversal can be limited by setMaxDepth.
Branches can be traversed selectively using skipChildren().
Unlike java.util.Iterator, the tree iterator points directly at the element (tree node), not BETWEEN elements. It means that, for example, if next() is called before processing, root won't be processed. current() can be used to obtain the current element at any time (except right after moveToChildren() was called).

Usage:
Instantiation:
TreeIterator tIterator = new TreeIterator ( rootNode , new DOMAdapter() );

Tree traversal INCLUDING the root:


 for( Object node = tIterator.current(); node!=null; node=tIterator.next() ){
     // processing...
 }
 

Tree traversal EXCLUDING the root:

 while( (node=(Node)tIterator.next()) != null )  {
     // processing...
 }
 

Tree traversal using hasNext():

 while( tIterator.hasNext() ) {
     Node node=(Node)tIterator.next();
     // processing...
  }
 

Note that hasNext() implementation is not very efficient for a tree structure from the performance standpoint, so refrain from using it for large trees.

Author:
Alexander Ananiev

Fields inherited from interface com.myarch.treeiterator.TreeConstants
DEPTH_UNLIMITED
 
Constructor Summary
TreeIterator(java.lang.Object root, TreeNodeAdapter nodeAdapter)
          Creates iterator and sets the root of a tree and tree adapter.
TreeIterator(java.lang.Object root, TreeNodeAdapter nodeAdapter, int maxDepth)
          Creates iterator and sets the root of a tree, tree adapter and depth of the traversal.
 
Method Summary
 java.lang.Object current()
          Returns the current node.
 int getDepth()
          Returns the depth of the level being traversed.
 int getIndex()
          Returns index of the of the current node among siblings.
 int getMaxDepth()
          Returns the maximum depth of the traversal.
 boolean hasChildren()
          Returns true if current node has children and iterator is allowed to traverse them.
 boolean hasNext()
          Returns true if not all elements of the tree have been traversed.
 boolean isMaxDepth()
          Returns true if the maximum allowed level is reached.
 void moveToChildren()
          Moves iterator to the children of the node regardless of current level depth setting.
 void moveToChildren(int depth)
          Moves iterator to the children of the node regardless of current level depth setting.
 java.lang.Object next()
          Returns the next element of a tree.
 void remove()
          This method is defined to comply with Iterator but it is not supported.
 void setDepth(int depth)
          Sets the initial depth value.
 void setLevelDepth(int depth)
          Same with moveToChildren.
 void setMaxDepth(int maxDepth)
          Sets the maximum depth of the traversal.
 void setRoot(java.lang.Object node)
          Sets the root of the tree.
 void skipChildren()
          After this method is called, next() will skip children of the current node and move to the next sibling instead.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TreeIterator

public TreeIterator(java.lang.Object root,
                    TreeNodeAdapter nodeAdapter)
Creates iterator and sets the root of a tree and tree adapter.
Parameters:
root - root of the tree; note that next() moves to the first child, not to the root
nodeAdapter - tree node adapter

TreeIterator

public TreeIterator(java.lang.Object root,
                    TreeNodeAdapter nodeAdapter,
                    int maxDepth)
Creates iterator and sets the root of a tree, tree adapter and depth of the traversal.
Parameters:
root - root of the tree
nodeAdapter - tree node adapter
maxDepth - depth of the traversal; 0 -- traverse only the root; 1-- traverse root and childrenl; 2-- traverse root, children and grandchildren and so forth
Method Detail

remove

public void remove()
            throws java.lang.UnsupportedOperationException
This method is defined to comply with Iterator but it is not supported.
Specified by:
remove in interface java.util.Iterator
Throws:
java.lang.UnsupportedOperationException - whenever it is called

setRoot

public void setRoot(java.lang.Object node)
Sets the root of the tree.
Parameters:
root - root of the tree; note that next() moves to the first child, not to the root

current

public java.lang.Object current()
Returns the current node. After iterator is created, root becomes current. Every next() call moves current to the next node.
Returns:
current node

setMaxDepth

public void setMaxDepth(int maxDepth)
Sets the maximum depth of the traversal.
Parameters:
maxDepth - depth of the traversal; 0 -- traverse only the root; 1-- traverse root and childrenl; 2-- traverse root, children and grandchildren and so forth

getMaxDepth

public int getMaxDepth()
Returns the maximum depth of the traversal.
Returns:
maximum allowed traversal depth set by setMaxDepth().

moveToChildren

public void moveToChildren()
Moves iterator to the children of the node regardless of current level depth setting.

Iterator doesn't have the current node after this call. It is positioned before the first child. next() must be called to position it to the first child. The entire branch will be processed. Previous max depth is restored after the branch is processed.


moveToChildren

public void moveToChildren(int depth)
Moves iterator to the children of the node regardless of current level depth setting.

Iterator doesn't have current node after this call. It is positioned before the first child. Next() must be called to position to the first child.

It is the alternative and more sophisticated approach to using skipChildren().

setLevelDepth does the same thing.

Parameters:
depth - New depth that applies to all children of the current node. Previous depth is restored after the branch is processed. This depth setting is differeent from the maximum depth of the traversal as it only applies to the current branch. It overrides the maximum depth previously set by setMaxDepth().

setLevelDepth

public void setLevelDepth(int depth)
Same with moveToChildren.

skipChildren

public void skipChildren()
After this method is called, next() will skip children of the current node and move to the next sibling instead.

isMaxDepth

public boolean isMaxDepth()
Returns true if the maximum allowed level is reached.
Returns:
true if this is the level set by setMaxDepth()

getDepth

public int getDepth()
Returns the depth of the level being traversed.
Returns:
depth of the current node; root has depth 0, children -- 1, grandchildren -- 2 and so on

setDepth

public void setDepth(int depth)
Sets the initial depth value. It does not move the iterator, it simply forces it to start counting depth not from 0, but from this value. I.e., if initial depth is set to 2, root depth would be 2, depth of its children would be 3 and so on.
Parameters:
depth - initial depth

getIndex

public int getIndex()
Returns index of the of the current node among siblings. Index starts with 0.
Returns:
index of the current node

hasNext

public boolean hasNext()
Returns true if not all elements of the tree have been traversed.

It is not recommended to use this method, since this check is performed anyway inside next(). It is more efficient to use next() and check for null.

Specified by:
hasNext in interface java.util.Iterator
Returns:
true if end of tree is not reached

hasChildren

public boolean hasChildren()
Returns true if current node has children and iterator is allowed to traverse them.
Returns:
true if current node has children

next

public java.lang.Object next()
Returns the next element of a tree. Preorder traversal is perfromed.
Note that unlike java.util.Iterator it does not raise exception when the end of the tree is reached, null is returned instead.
Specified by:
next in interface java.util.Iterator
Returns:
the next node or null when there is no more nodes to traverse


Copyright © 2001 Alexander Ananiev & MyArch.com. All Rights Reserved.