js.io

Class FilesIterator<T>

java.lang.Object

js.io.FilesIterator<T>

All Implemented Interfaces:

Iterable<T>, Iterator<T>

public class FilesIterator<T>
extends Object
implements Iterator<T>, Iterable<T>

Traverse all files in a directory hierarchy, no mater how deep it is. This class implements both Iterator and Iterable interfaces; as a consequence files can be inspected using both iterator and for...each loops, see sample code below. All files from all sub-directories of given base directory are guaranteed to be exposed exactly once but there is no guarantee for a particular order.

Files iterator provides static helpers for creating couple kind of iterators, absolute or relative, by file or by file name, see getAbsoluteIterator(File) and related.

 FilesIterator<File> it = FilesIterator.getAbsoluteIterator("/var/www/");
 while (it.hasNext()) {
        File file = it.next();
        // do something with the file
 }
 
 for (File file : FilesIterator.getAbsoluteIterator("/var/www/")) {
        // do something with the file
 }
 

This files iterator is able to returns both absolute and relative file paths and both File paths and String file names; there are factory methods for relevant use cases. Note that absolute/relative in this class context means including or not including base directory at the beginning of returned file path. Base directory is that supplied when iterator instance is created.

 for (File file : FilesIterator.getAbsoluteIterator("/var/www/")) {
        // file is something like '/var/www/index.htm'
        // base directory is present on file start
 }
 
 for (File file : FilesIterator.getRelativeIterator("/var/www/")) {
        // file is something like 'index.htm'
        // base directory is not present on file start
 }
 

Finally, this class is not intended to be reused: its state is changing while iterating over files. Also is not thread safe.

Version:

final

Author:

Iulian Rotaru

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	FilesIterator.Directory Working directory context data saved on directory stack.
private class	FilesIterator.FilesHandler Handler for absolute files iterator.
private static interface	FilesIterator.Handler Strategy handler for iterator next operation processing.
private class	FilesIterator.NamesHandler Handler for absolute file names iterator.
private class	FilesIterator.RelativeFilesHandler Handler for relative files iterator.
private class	FilesIterator.RelativeNamesHandler Handler for relative file names iterator.
private static class	FilesIterator.Strategy Strategy for processing files iterator next operation.

Field Summary

Fields

Modifier and Type	Field and Description
private FilesIterator.Handler	handler The actual next() processing strategy.
private Stack<String>	pathComponents Path components used to create file returned by next() operation when relativePath is true.
private int	processedFilesCount Processed files count for audit purposes.
private boolean	relativePath Flag, if true, returned files are relative to base directory, that is, does not include base directory at file path start.
private Stack<FilesIterator.Directory>	stack Keep track of directory hierarchy.
private FilesIterator.Directory	workingDirectory Store current working directory at every given moment.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	FilesIterator(File baseDir, FilesIterator.Strategy strategy) Construct a files iterator instance for given base directory.

Method Summary

Modifier and Type	Method and Description
static FilesIterator<File>	getAbsoluteIterator(File baseDir) Create absolute path files iterator.
static FilesIterator<File>	getAbsoluteIterator(String baseDir) Create absolute path files iterator.
static FilesIterator<String>	getAbsoluteNamesIterator(File baseDir) Create absolute file names iterator.
static FilesIterator<String>	getAbsoluteNamesIterator(String baseDir) Create absolute file names iterator.
int	getProcessedFilesCount() Get processed files count but does not include directories.
static FilesIterator<File>	getRelativeIterator(File baseDir) Create relative path files iterator.
static FilesIterator<File>	getRelativeIterator(String baseDir) Create relative path files iterator.
static FilesIterator<String>	getRelativeNamesIterator(File baseDir) Create relative file names iterator.
static FilesIterator<String>	getRelativeNamesIterator(String baseDir) Create relative file names iterator.
boolean	hasNext() Return true if files iterator instance has at least one file not yet exposed.
private boolean	isLoopExitCondition() Test for iteration loop exit condition.
Iterator<T>	iterator() Implements Iterable interface.
T	next() Returns current file or its name, relative or absolute, based on selected strategy.
private void	pop() Restore current working directory after a sub-directory completes scanning.
private void	push(File directory) Push current directory on directories stack when enter a sub-directory.
void	remove() This operation is not supported.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Iterator

forEachRemaining

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

stack

private Stack<FilesIterator.Directory> stack

Keep track of directory hierarchy.

workingDirectory

private FilesIterator.Directory workingDirectory

Store current working directory at every given moment.

processedFilesCount

private int processedFilesCount

Processed files count for audit purposes.

pathComponents

private Stack<String> pathComponents

Path components used to create file returned by next() operation when relativePath is true. It is updated by push(File) and pop() methods, while iteration is in progress with all directory names from current path.

handler

private FilesIterator.Handler handler

The actual next() processing strategy.

relativePath

private boolean relativePath

Flag, if true, returned files are relative to base directory, that is, does not include base directory at file path start. If false returned files include base directory. Please note that in this class context not relative path does not mean absolute path; it is still relative to base directory but include it.

Constructor Detail

FilesIterator

private FilesIterator(File baseDir,
                      FilesIterator.Strategy strategy)

Construct a files iterator instance for given base directory.

Parameters:

baseDir - base directory to scan for files,

strategy - strategy used for iterator next operation processing.

Method Detail

getAbsoluteIterator

public static FilesIterator<File> getAbsoluteIterator(File baseDir)

Create absolute path files iterator.

Parameters:

baseDir - base directory to scan for files.

Returns:

files iterator.

getRelativeIterator

public static FilesIterator<File> getRelativeIterator(File baseDir)

Create relative path files iterator.

Parameters:

baseDir - base directory to scan for files.

Returns:

files iterator.

getAbsoluteNamesIterator

public static FilesIterator<String> getAbsoluteNamesIterator(File baseDir)

Create absolute file names iterator.

Parameters:

baseDir - base directory to scan for files.

Returns:

files iterator.

getRelativeNamesIterator

public static FilesIterator<String> getRelativeNamesIterator(File baseDir)

Create relative file names iterator.

Parameters:

baseDir - base directory to scan for files.

Returns:

files iterator.

getAbsoluteIterator

public static FilesIterator<File> getAbsoluteIterator(String baseDir)

Create absolute path files iterator.

Parameters:

baseDir - base directory path to scan for files.

Returns:

files iterator.

getRelativeIterator

public static FilesIterator<File> getRelativeIterator(String baseDir)

Create relative path files iterator.

Parameters:

baseDir - base directory path to scan for files.

Returns:

files iterator.

getAbsoluteNamesIterator

public static FilesIterator<String> getAbsoluteNamesIterator(String baseDir)

Create absolute file names iterator.

Parameters:

baseDir - base directory name to scan for files.

Returns:

files iterator.

getRelativeNamesIterator

public static FilesIterator<String> getRelativeNamesIterator(String baseDir)

Create relative file names iterator.

Parameters:

baseDir - base directory path to scan for files.

Returns:

files iterator.

iterator

public Iterator<T> iterator()

Implements Iterable interface.

Specified by:

iterator in interface Iterable<T>

hasNext

public boolean hasNext()

Return true if files iterator instance has at least one file not yet exposed. If this predicate returns true, next call of next() method is guaranteed to return a valid file.

Specified by:

hasNext in interface Iterator<T>

Returns:

true if there is at least one file usable by next().

isLoopExitCondition

private boolean isLoopExitCondition()

Test for iteration loop exit condition. Iteration loop is ended if current working directory index reaches its files count and there is no more directories on stack.

Returns:

true if iterator loop reach its end.

next

public T next()

Returns current file or its name, relative or absolute, based on selected strategy. This method should be invoked only if hasNext() companion returns true; otherwise behavior is not specified.

This method just return the value of selected strategy for next operation processing, that is, delegates handler . Also takes care to increment processed files count.

Specified by:

next in interface Iterator<T>

Returns:

next operation processing result of selected strategy.

getProcessedFilesCount

public int getProcessedFilesCount()

Get processed files count but does not include directories.

Returns:

processed files count.

push

private void push(File directory)

Push current directory on directories stack when enter a sub-directory. Given directory is restored when child finishes, using pop() counterpart.

Parameters:

directory - current directory.

pop

private void pop()

Restore current working directory after a sub-directory completes scanning.

remove

public void remove()

This operation is not supported.

Specified by:

remove in interface Iterator<T>