com.bristle.javalib.io
Class FileTreeIterator

java.lang.Object
  com.bristle.javalib.io.FileTreeIterator

All Implemented Interfaces:

Iterator

public class FileTreeIterator
extends Object
implements Iterator

This class implements an iterator for a directory tree of files and subdirectories. Within each subdirectory, it returns the immediate children (files and subdirectories) in case-insensitive alphabetic order. However, after returning each subdirectory, it returns the contents of the subdirectory, recursively, before continuing with the remaining siblings of that subdirectory. That is, it performs a "depth-first pre-order left-to-right" traversal. It does not return the top-level directory that was originally specified for traversal -- only its descendants.

Usage:
   - The typical scenario for using this class is:
       for (Iterator i = new FileTreeIterator("/dir"); i.hasNext(); )
       {
           File file = (File)i.next();
           doSomething(file);
       }

   - See the source code of the inner Tester class for more examples.
  
Assumptions:
Effects:
       - None.  Iterates over the directory tree, but does not change it.
Anticipated Changes:
       - Currently iterates forward only.  May add hasPrev() and prev() to 
         support reverse iteration and reversing during an iteration. 
       - May add support for resetting the iteration to a specified index 
         within the current subdirectory (the 3rd file, 5th file, etc.)
       - May add support for querying the index within the current 
         subdirectory.
       - Currently caches the entire set of filenames in a single directory,
         internally as an array of Strings.  May add an option to cache less
         and retrieve more directly from the filesystem on each iteration.
       - May add new constructor with a FilenameFilter parameter, so the 
         iterator returns a set of Files filtered by name.
       - May add new constructor with a FileFilter parameter, so the 
         iterator returns a set of Files filtered by other File properties.
         Note:  Supporting FileFilter will be easiest to do by switching 
                internally from File.list() to File.listFiles(), but that
                will make it harder to sort by filename.
       - May add additional traversal orders:
         - breadth-first, instead of depth-first
         - case-sensitive, instead of case-insensitive
         - post-order, instead of pre-order
         - right-to-left, instead of left-to-right     
       - May add a limit on the depth to traverse, so caller can limit a
         traversal to children only, children and grandchildren only, etc. 
Notes:
Implementation Notes:
Portability Issues:
Revision History:
   $Log$

Nested Class Summary

static class

FileTreeIterator.Tester Each class contains a Tester inner class with a main() for easier unit testing.

Field Summary

(package private) String[]	m_arrNames
(package private) Stack	m_stackIndexes
(package private) String	m_strDirectory

Constructor Summary

FileTreeIterator(String strDirectoryName)
Constructor.

Method Summary

private void	findNext() Advance to the next file (which may be a subdirectory) in the iteration, if any.
private int	getIndex() Get the value on the top of the stack of indexes.
boolean	hasNext() Returns true if there are more Files to be iterated; false otherwise.
private void	incrementIndex() Increment the value on the top of the stack of indexes.
Object	next() Returns the next File in the iteration.
void	remove() Not implemented.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_strDirectory

String m_strDirectory

m_stackIndexes

Stack m_stackIndexes

m_arrNames

String[] m_arrNames

Constructor Detail

FileTreeIterator

public FileTreeIterator(String strDirectoryName)

Constructor.

Parameters:

strDirectoryName - String name of the directory tree to iterate.

Throws:

NullPointerException - If strDirectoryName is null.

Method Detail

hasNext

public boolean hasNext()

Returns true if there are more Files to be iterated; false otherwise.

Specified by:

hasNext in interface Iterator

Returns:

true if there are more Files to be iterated; false otherwise

next

public Object next()
            throws NoSuchElementException

Returns the next File in the iteration.

Specified by:

next in interface Iterator

Returns:

the next File in the iteration

Throws:

NoSuchElementException - when no more Files in the iteration

remove

public void remove()

Not implemented. This is an optional method of the Iterator interface.

Specified by:

remove in interface Iterator

Throws:

UnsupportedOperationException

getIndex

private int getIndex()

Get the value on the top of the stack of indexes.

Returns:

Value from the top of the stack.

incrementIndex

private void incrementIndex()

Increment the value on the top of the stack of indexes.

findNext

private void findNext()

Advance to the next file (which may be a subdirectory) in the iteration, if any.