edu.stanford.nlp.io
Class FileSequentialCollection

java.lang.Object
  |
  +--java.util.AbstractCollection
        |
        +--edu.stanford.nlp.io.FileSequentialCollection

All Implemented Interfaces:

Collection

public class FileSequentialCollection

extends AbstractCollection

A FileSequentialCollection maintains a read-only collection of Files. (It's a list, but we don't make it a List or else one needs an iterator that can go backwards.) It is built from a Collection of paths, or just from a single path. Optionally one can also provide a FileFilter which is applied over the files in a recursive traversal, or else an extension and whether to do recursive traversal, which are used to construct a filter. Note that the Collection argument constructor will behave 'normally' iff none of the Collection elements are directories. If they are directories they will be recursed and files in them added. To get the behavior of putting just directories in the collection one needs to use the constructor FileSequentialCollection(c, failFilt, true), where failFilt is a user-supplied FileFilter that accepts no files. The FileSequentialCollection builds from these constructor arguments a collection of Files, which can be iterated over, etc. This class does runtime expansion of paths. That is, it is optimized for iteration and not for random access. It is also an unmodifiable Collection.

The class provides some additional constructors beyond the two recommended by the Collections package, to allow specifying a FileFilter and similar options. Nevertheless, so as to avoid overburdening the the API, not every possibly useful constructor has been provided where these can be easily synthesized using standard Collections package facilities. Useful idioms to know are:

• To make a FileSequentialCollection from an array of Files or Strings arr:
  FileSequentialCollection fcollect = new FileSequentialCollection(Arrays.asList(arr));
• To make a FileSequentialCollection from a single File or String fi:
  FileSequentialCollection fcollect = new FileSequentialCollection(Collections.singletonList(fi));

This class will throw an IllegalArgumentException if there are things that are not existing Files or String paths to existing files in the input collection (from the Iterator).

See Also:

FileArrayList

Constructor Summary

FileSequentialCollection()
Creates an empty FileSequentialCollection, with no Files in it.

FileSequentialCollection(Collection c)
Creates a FileSequentialCollection from the passed in Collection.

FileSequentialCollection(Collection c, FileFilter filt)
Creates a FileSequentialCollection from the passed in Collection.

FileSequentialCollection(Collection c, FileFilter filt, boolean includeDirs)
Creates a FileSequentialCollection from the passed in Collection.

FileSequentialCollection(Collection c, String suffix, boolean recursively)
Creates a FileSequentialCollection from the passed in Collection.

FileSequentialCollection(File path, String suffix, boolean recursively)
Creates a FileSequentialCollection from the passed in File path.

Method Summary

Iterator	iterator() Return an Iterator over files in the collection.
static void	main(String[] args) This is simply a debugging aid that tests the functionality of the class.
int	size() Returns the size of the FileSequentialCollection.

Methods inherited from class java.util.AbstractCollection

add, addAll, clear, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Collection

equals, hashCode

Constructor Detail

FileSequentialCollection

public FileSequentialCollection()

Creates an empty FileSequentialCollection, with no Files in it. Since a FileSequentialCollection is not modifiable, this is largely useless (except if you want an empty one).

FileSequentialCollection

public FileSequentialCollection(Collection c)

Creates a FileSequentialCollection from the passed in Collection. The constructor iterates through the collection. For each element, if it is a File or String, then this file path is traversed for addition to the collection. If the argument is of some other type, an IllegalArgumentException is thrown. For each File or String, if they do not correspond to directories, then they are added to the collection; if they do, they are recursively explored and all non-directories within them are added to the collection.

Parameters:

c - The collection to build the FileSequentialCollection from

FileSequentialCollection

public FileSequentialCollection(File path,
                                String suffix,
                                boolean recursively)

Creates a FileSequentialCollection from the passed in File path. If the File does not correspond to a directory, then it is added to the collection; if it does, it is explored. Files that match the extension, and files in subfolders that match, if appropriate, are added to the collection. This is an additional convenience constructor.

Parameters:

path - file or directory to load from

suffix - suffix (normally "File extension") of files to load

recursively - true means descend into subdirectories as well

FileSequentialCollection

public FileSequentialCollection(Collection c,
                                String suffix,
                                boolean recursively)

Creates a FileSequentialCollection from the passed in Collection. The constructor iterates through the collection. For each element, if it is a File, then the File is added to the collection, if it is a String, then a File corresponding to this String as a file path is added to the collection, and if the argument is of some other type, an IllegalArgumentException is thrown. For the files thus specified, they are included in the collection only if they match an extension filter as specified by the other arguments.

Parameters:

c - Collection of files or directories as Files or Strings

suffix - suffix (normally "File extension") of files to load

recursively - true means descend into subdirectories as well

FileSequentialCollection

public FileSequentialCollection(Collection c,
                                FileFilter filt)

Creates a FileSequentialCollection from the passed in Collection. The constructor iterates through the collection. For each element, if it is a File or String then these file paths are processed as explained below. If the argument is of some other type, an IllegalArgumentException is thrown. For the files specified, if they are not directories, they are included in the collection. If they are directories, files inside them are included iff they match the FileFilter. This will include recursive directory descent iff the FileFilter accepts directories. If the path is a directory then only files within the directory (perhaps recursively) that satisfy the filter are processed. If the pathis a file, then that file is processed regardless of whether it satisfies the filter. (This semantics was adopted, since otherwise there was no easy way to go through all the files in a directory without descending recursively via the specification of a FileFilter.)

Parameters:

c - The collection of file or directory to load from

filt - A FileFilter of files to load. This may be null, in which case all files are accepted.

FileSequentialCollection

public FileSequentialCollection(Collection c,
                                FileFilter filt,
                                boolean includeDirs)

Creates a FileSequentialCollection from the passed in Collection. The constructor iterates through the collection. For each element, if it is a File or String then these file paths are processed as explained below. If the argument is of some other type, an IllegalArgumentException is thrown. For the files specified, if they are not directories, they are included in the collection. If they are directories, files inside them are included iff they match the FileFilter. This will include recursive directory descent iff the FileFilter accepts directories. If the path is a directory then only files within the directory (perhaps recursively) that satisfy the filter are processed. If the pathis a file, then that file is processed regardless of whether it satisfies the filter. (This semantics was adopted, since otherwise there was no easy way to go through all the files in a directory without descending recursively via the specification of a FileFilter.)

Parameters:

c - The collection of file or directory to load from. An argument of null is interpreted like an empty collection.

filt - A FileFilter of files to load. This may be null, in which case all files are accepted

includeDirs - Whether to include director names in the file list

Method Detail

size

public int size()

Returns the size of the FileSequentialCollection.

Specified by:

size in interface Collection

Specified by:

size in class AbstractCollection

Returns:

size How many files are in the collection

iterator

public Iterator iterator()

Return an Iterator over files in the collection. This version lazily works its way down directories.

Specified by:

iterator in interface Collection

Specified by:

iterator in class AbstractCollection

main

public static void main(String[] args)

This is simply a debugging aid that tests the functionality of the class. The supplied arguments are put in a Collection, and passed to the FileSequentialCollection constructor. An iterator is then used to print the names of all the files (but not directories) in the collection.

Parameters:

args - A list of file paths