com.aliasi.io

Class FileLineReader

java.lang.Object

java.io.Reader

java.io.BufferedReader

java.io.LineNumberReader

com.aliasi.io.FileLineReader

All Implemented Interfaces:

Closeable, AutoCloseable, Iterable<String>, Readable

public class FileLineReader
extends LineNumberReader
implements Iterable<String>

A FileLineReader instance represents the lines of a file. The lines may be streamed through an iterator or eturned all at once. This class encapsulates good practices for resources and adapts file line reading to for-each loops by implementing the Iterable interface.

The definition of a line is defined by the BufferedReader class's BufferedReader.readLine() method.

The two standard usage patterns are streaming and all-at-once reading. For streaming, this class implements the Iterable interface, so for-each loops work:

 File file = ...;
FileLineReader lines = new FileLineReader(file,"UTF-8");
for (String line : lines) {
   processLine(line);
}
lines.close();

The iterable implementation reads a line at a time using a buffered reader, so is scalable.

The readLines() method returns the lines all at once as a collection, and automatically closes all resources used:

 List<String> lines = new FileLines(file,"UTF-8").readLines();

The lines are read into the list, so enough memory should be available to hold the entire file.

Instances of this class may be used as ordinary line number readers, too. The LineNumberReader.getLineNumber() method is particularly useful for error reporting.

Since:

Lingpipe3.8

Version:

3.9

Author:

Bob Carpenter

Field Summary

Fields inherited from class java.io.Reader

lock

Constructor Summary

Constructors

Constructor and Description
FileLineReader(File file, String encoding) Construct a new file lines iterator from the specified file using the specified character encoding, assuming no compression.
FileLineReader(File file, String encoding, boolean gzipped) Construct a new file lines iterator from the specified file using the specified character encoding, uncompressing gzipped input if the compresison flag is true.

Method Summary

Modifier and Type	Method and Description
Iterator<String>	iterator() Returns an iterator over the remaining lines of the file.
static String[]	readLineArray(File in, String encoding) Return the array of lines read from the specified file using the specified character encoding.
List<String>	readLines() Returns the list of lines remaining to be read from this line iterator and closes all resources.
static List<String>	readLines(File in, String encoding) Return the list of lines read from the specified file using the specified character encoding.

Methods inherited from class java.io.LineNumberReader

getLineNumber, mark, read, read, readLine, reset, setLineNumber, skip

Methods inherited from class java.io.BufferedReader

close, lines, markSupported, ready

Methods inherited from class java.io.Reader

read, read

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

FileLineReader

public FileLineReader(File file,
                      String encoding)
               throws IOException

Construct a new file lines iterator from the specified file using the specified character encoding, assuming no compression.

Warning: The iterator should be closed using the BufferedReader.close() method to avoid any dangling file references. Closing the JVM also closes, so short programs may avoid closing the streams explicitly.

If the file is not found or the encoding is not supported, any file-system resources allocated will be released and an IOException thrown.

Parameters:

file - File from which to read lines.

encoding - Character encoding.

Throws:

FileNotFoundException - If the file is not found.

UnsupportedEncodingException - If the specified encoding is not supported.

IOException

FileLineReader

public FileLineReader(File file,
                      String encoding,
                      boolean gzipped)
               throws IOException

Construct a new file lines iterator from the specified file using the specified character encoding, uncompressing gzipped input if the compresison flag is true.

Warning: The iterator should be closed using the BufferedReader.close() method to avoid any dangling file references. Closing the JVM also closes, so short programs may avoid closing the streams explicitly.

If the file is not found or the encoding is not supported, any file-system resources allocated will be released and an IOException thrown.

Parameters:

file - File from which to read lines.

encoding - Character encoding.

gzipped - Set to true if file is gzipped.

Throws:

FileNotFoundException - If the file is not found.

UnsupportedEncodingException - If the specified encoding is not supported.

IOException

Method Detail

iterator

public Iterator<String> iterator()

Returns an iterator over the remaining lines of the file. Because it buffers one line ahead, any use of LineNumberReader.getLineNumber() from this class will be one greater than it should be.

There is no concurrent protection for this method, so it should only be used from a single thread.

Specified by:

iterator in interface Iterable<String>

Returns:

This iterator.

readLines

public List<String> readLines()
                       throws IOException

Returns the list of lines remaining to be read from this line iterator and closes all resources. If this method is called before any calls to iterator(), it returns all the lines read from the file.

Returns:

The list of lines read from the file.

Throws:

IOException - If there is an underlying I/O error reading from the file.

readLines

public static List<String> readLines(File in,
                                     String encoding)
                              throws IOException,
                                     UnsupportedEncodingException

Return the list of lines read from the specified file using the specified character encoding.

Parameters:

in - File whose lines are read.

encoding - Character encoding to decode chars in files.

Returns:

The list of lines read from the file.

Throws:

UnsupportedEncodingException - If the encoding is not supported on the JVM.

IOException - If there is an underlying I/O error reading from the file.

readLineArray

public static String[] readLineArray(File in,
                                     String encoding)
                              throws IOException,
                                     UnsupportedEncodingException

Return the array of lines read from the specified file using the specified character encoding.

Parameters:

in - File whose lines are read.

encoding - Character encoding to decode chars in files.

Returns:

The lines read from the file.

Throws:

UnsupportedEncodingException - If the encoding is not supported on the JVM.

IOException - If there is an underlying I/O error reading from the file.