Class FileIterator

java.lang.Object
  |
  +--FileIterator

public class FileIterator

extends java.lang.Object

implements java.util.Iterator

A FileIterator provides an iterator interface for enumerating all files in a directory. The iterator can optionally recursively search all subdirectories.

Field Summary

protected boolean	applyFilterToDirs
protected java.io.FileFilter	fileFilter
protected java.util.Stack	fileLists fileLists is a stack of array iterators.
protected int	lastFileType lastFileType is: 0 if last obtained element was a normal file 1 if last obtained element was a directory when first encountered 2 if last obtained element was a directory when just finished it contents The codes 1 and 2 will need to be checked when both useDirsDown and useDirsUp are true in order to tell whether it is the first or second time the directory is being returned.
protected java.io.File	nextFile
protected int	nextFileType
protected boolean	recurseSubdirectories
protected boolean	useDirsDown
protected boolean	useDirsUp

Constructor Summary

FileIterator(java.io.File f)
Constructor.

FileIterator(java.io.File f, java.io.FileFilter filter)
Constructor which specifies both a File and a FileFilter.

Method Summary

int	getLastFileType() Accessor function for lastFileType indicating the type of the last returned element.
boolean	hasNext() Check whether there is a next File, either file or directory, to be returned.
boolean	hasNextFile() Check whether there is a next file (not a directory) to be returned.
java.lang.Object	next() Returns the next file or directory as an object.
java.io.File	nextElement() Returns the next element which can be either a file or a directory.
protected java.io.File	nextElementAll() Returns the next file or directory.
java.io.File	nextFile() Returns the next element which is a file rather than a directory.
protected void	pushFileArrayIterator(java.io.File subDir) Adds a new file or new directory list onto the stack fileLists
protected void	pushFileArrayIterator(java.io.File[] fArray) Adds a new file list iterator onto the stack fileLists This is generally called with the list of files from a directory.
void	remove() This is an unsupported operation and generates an exception
void	setDirectoryModes(boolean useDirsDown, boolean useDirsUp) Sets the modes for returning directories with next() or nextElement().
void	setFilterMode(boolean applyFilterToDirs) Set whether the file filter applies to directories.
void	setRecursive(boolean recurseSubdirectories) Set whether subdirectories are recursively searched.

Methods inherited from class java.lang.Object

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

Field Detail

lastFileType

protected int lastFileType

lastFileType is: 0 if last obtained element was a normal file 1 if last obtained element was a directory when first encountered 2 if last obtained element was a directory when just finished it contents The codes 1 and 2 will need to be checked when both useDirsDown and useDirsUp are true in order to tell whether it is the first or second time the directory is being returned. The value 1 is used for all directories if recurseSubdirectories is false. Accessor: getLastFileType();

fileLists

protected java.util.Stack fileLists

fileLists is a stack of array iterators. Each array iterator is acting on an array of File's.

fileFilter

protected java.io.FileFilter fileFilter

recurseSubdirectories

protected boolean recurseSubdirectories

useDirsDown

protected boolean useDirsDown

useDirsUp

protected boolean useDirsUp

applyFilterToDirs

protected boolean applyFilterToDirs

nextFile

protected java.io.File nextFile

nextFileType

protected int nextFileType

Constructor Detail

FileIterator

public FileIterator(java.io.File f)
             throws java.io.FileNotFoundException

Constructor. Specifies a File which is generally a directory.

Throws:

java.io.FileNotFoundException - if the file is neither a valid file, nor a directory.

FileIterator

public FileIterator(java.io.File f,
                    java.io.FileFilter filter)
             throws java.io.FileNotFoundException

Constructor which specifies both a File and a FileFilter.

Throws:

java.io.FileNotFoundException - if the file is neither a valid file, nor a directory.

See Also:

FileIteratory( File f )

Method Detail

setRecursive

public void setRecursive(boolean recurseSubdirectories)

Set whether subdirectories are recursively searched. The default is to not recursively search subdirectories.

Parameters:

recurseSubdirectories - If true, subdirectories are recursively searched.

setDirectoryModes

public void setDirectoryModes(boolean useDirsDown,
                              boolean useDirsUp)

Sets the modes for returning directories with next() or nextElement(). The default values are useDirsDown=true and useDirsUp=false. Note that nextFile() can be used instead of setting both to false. If you set both to true, then you may use the helper function getLastFileType() to decide whether a directory entry is being returned before or after the directory is listed. Strange results may occur if you change these parameters after beginning to use next, nextFile or nextElement.

Parameters:

useDirsDown - If true, nextElement() returns directories as they are opened. This is needed for "preorder" enumeration order.

useDirsUp - If true, nextElement() returns directories as they are finished being processed. This is needed for "postorder" enumeration order.

setFilterMode

public void setFilterMode(boolean applyFilterToDirs)

Set whether the file filter applies to directories. The default is to not apply the filter to directories and thus a recursive search by default opens all subdirectories encountered.

Parameters:

applyFilterToDirs - If true, skip directories that do not match the filter.

getLastFileType

public int getLastFileType()

Accessor function for lastFileType indicating the type of the last returned element. The value of lastFileType is equal to:

• 0, if last element returned by one of the getNext... functions was a normal file (not a directory).
• 1, if last returned by one of the getNext... functions was a directory when first encountered.
• 2, if last returned by one of the getNext... functions was a directory when just finished with its contents.

An alternate way to distinguish files from directories is to use the methods isFile or isDirectory of java.io.File. However, the codes 1 and 2 will need to be checked when both useDirsDown and useDirsUp are true in order to tell whether it is the first or second time the directory is being returned. If useDirsDown is true and useDirsUp is false, then the value 1 is used for all directories. If useDirsDown is false and useDirsUp is true, then the value 2 is used for all directories. The value 1 is used for all directories if recurseSubdirectories is false.

hasNextFile

public boolean hasNextFile()

Check whether there is a next file (not a directory) to be returned. This repositions the iterator to point at the said next file, so strange results may occur if next() or nextElement is called afterwards instead of nextFile.

nextFile

public java.io.File nextFile()
                      throws java.util.NoSuchElementException

Returns the next element which is a file rather than a directory. Recommended that this be used only if useDirsDown and useDirsUp are both false.

Throws:

java.util.NoSuchElementException - if there is no next element to return.

hasNext

public boolean hasNext()

Check whether there is a next File, either file or directory, to be returned. This repositions the iterator to point at the said next File.

Specified by:

hasNext in interface java.util.Iterator

nextElement

public java.io.File nextElement()
                         throws java.util.NoSuchElementException

Returns the next element which can be either a file or a directory. Use getLastFileType to distinguish files from directories, and to recognise when a directory is encountered for the second time.

Returns:

The next file or directory. The return type is File.

Throws:

java.util.NoSuchElementException - if there is no next element to return.

next

public java.lang.Object next()
                      throws java.util.NoSuchElementException

Returns the next file or directory as an object. Included mainly to fully implement the Iterator interface. It is usually more convenient to use nextFile() or nextElement(). In fact, next() is equivalent to nextElement(), except that next() returns a file as an Object.

Specified by:

next in interface java.util.Iterator

Throws:

java.util.NoSuchElementException - if there is no next element to return.

nextElementAll

protected java.io.File nextElementAll()

Returns the next file or directory. The suffix "All" indicates that directories are returned both when encountered and when completed as if both useDirsDown and useDirsUp were true. This is intended for internal use by nextFile() and nextElement and by hasNextFile and hasNextElement. It returns the next File (a file or a directory) both as the returned object, and as the value of nextFile. It sets the value of nextFileType to indicate the type of File returned. If no next element is found, it returns null

remove

public void remove()
            throws java.lang.UnsupportedOperationException

This is an unsupported operation and generates an exception

Specified by:

remove in interface java.util.Iterator

Throws:

java.lang.UnsupportedOperationException -

pushFileArrayIterator

protected void pushFileArrayIterator(java.io.File subDir)

Adds a new file or new directory list onto the stack fileLists

pushFileArrayIterator

protected void pushFileArrayIterator(java.io.File[] fArray)

Adds a new file list iterator onto the stack fileLists This is generally called with the list of files from a directory.