FileLineReader (SAFS API DOCUMENT)

java.lang.Object
- org.safs.text.FileLineReader

Direct Known Subclasses:

INIFileReader, SAFSFile
```
public class FileLineReader
extends java.lang.Object
```
Copyright 2003 SAS Institute GNU General Public License (GPL) http://www.opensource.org/licenses/gpl-license.php
This FileReader class is intended as a generic file instance class for reading text files.

This class represents the most basic reader functionality. It will simply read a line of text for each call to readLine(). It uses a java.io.BufferedReader as the underlying IO mechanism. The file to be read is expected to be ANSI or a supported Charset encoding.

Version:

1.0, 03/24/2004, 11/03/2006 (Carl Nagle) modified to accept mixed-mode UTF-8 files., 03/21/2007 (Carl Nagle) modified to strip utf-8 leader bytes when needed., 07/16/2010 (Carl Nagle) modified to support other Charset encodings., 12/16/2014 (Carl Nagle) Fix NullPointerException on empty files in readLine. Software Automation Framework Support (SAFS) https://safsdev.github.io/
Software Testing Automation Framework (STAF) http://staf.sourceforge.net

Author:

Carl Nagle, SAS Institute

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.lang.String`	`charset`
`static int`	`DEFAULT_BUFFER_SIZE`
`protected boolean`	`eof`
`protected java.io.File`	`file`
`protected java.lang.String`	`filename`
`protected boolean`	`firstline`
`protected java.lang.String`	`fullpath`
`protected java.lang.String`	`linetext`
`protected java.io.BufferedReader`	`reader`
`protected java.io.InputStream`	`stream`

Constructor Summary

Constructors
Constructor and Description
`FileLineReader()` This constructor will create an inoperable (Closed) file object.
`FileLineReader(java.io.File file)` The constructor used by the FileReader if the input is a File.
`FileLineReader(java.io.File file, java.lang.String encoding)` The constructor used by the FileReader if the input is a File.
`FileLineReader(java.io.InputStream stream)` The constructor used by the FileReader if the input is an InputStream.
`FileLineReader(java.io.InputStream stream, java.lang.String encoding)` The constructor used by the FileReader if the input is an InputStream.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()` A call to this routine is essentially telling the object that its useful life is over.
`protected void`	`closeReader()` Shutdown (close) the file reader if it exists.
`java.lang.String`	`getFilename()` Subclasses should not need to override this function.
`java.lang.String`	`getFullpath()` Subclasses should not need to override this function.
`boolean`	`isClosed()` Subclasses should not need to override this function.
`boolean`	`isEOF()` Subclasses should not need to override this function.
`void`	`open()` Subclasses should not need to override this function unless some very interesting things need to be done before or after the file is opened.
`protected void`	`openFile()` Called internally by open().
`protected void`	`openStream()` Called internally by open().
`java.lang.String`	`readLine()` This routine is the most basic readLine function.
`protected void`	`resetpointers()` Resets important fields during Close and other operations.
`protected void`	`setFile(java.io.File newfile)` Allows us to set (and change) the file that will be read.
`protected void`	`setStream(java.io.InputStream stream)` Allows us to set (and change) the data that will be read.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_BUFFER_SIZE
```
public static int DEFAULT_BUFFER_SIZE
```
  - fullpath
```
protected java.lang.String fullpath
```
  - filename
```
protected java.lang.String filename
```
  - stream
```
protected java.io.InputStream stream
```
  - file
```
protected java.io.File file
```
  - reader
```
protected java.io.BufferedReader reader
```
  - eof
```
protected boolean eof
```
  - firstline
```
protected boolean firstline
```
  - charset
```
protected java.lang.String charset
```
  - linetext
```
protected java.lang.String linetext
```
- Constructor Detail
  - FileLineReader
```
public FileLineReader()
```
    This constructor will create an inoperable (Closed) file object. No use whatsoever. :)
  - FileLineReader
```
public FileLineReader(java.io.File file)
```
    The constructor used by the FileReader if the input is a File. All subclasses using File MUST invoke this constructor prior to completing their initialization.
    Invoke this constructor from the subclass with:
    super(file);
    
    Parameters:
    
    file - A File object that references the file to be opened.
  - FileLineReader
```
public FileLineReader(java.io.File file,
                      java.lang.String encoding)
```
    The constructor used by the FileReader if the input is a File. All subclasses using File MUST invoke this constructor prior to completing their initialization.
    Invoke this constructor from the subclass with:
    super(file);
    
    Parameters:
    
    file - File, A File object that references the file to be opened.
    
    encoding - String, a valid Charset encoding like "UTF-16", etc...
  - FileLineReader
```
public FileLineReader(java.io.InputStream stream)
```
    The constructor used by the FileReader if the input is an InputStream. For example, resources or files stored in JARs loaded via ClassLoaders. Files can be loaded from the file system if the directory is in the System CLASSPATH where getSystemResourceAsStream can find it. All subclasses using InputStreams MUST invoke this constructor prior to completing their initialization.
    Invoke this constructor from the subclass with:
    super(stream);
    
    Parameters:
    
    stream - an InputStream object that references the data to be opened.
    
    See Also:
    
    ClassLoader.getSystemResourceAsStream(java.lang.String)
  - FileLineReader
```
public FileLineReader(java.io.InputStream stream,
                      java.lang.String encoding)
```
    The constructor used by the FileReader if the input is an InputStream. For example, resources or files stored in JARs loaded via ClassLoaders. Files can be loaded from the file system if the directory is in the System CLASSPATH where getSystemResourceAsStream can find it. All subclasses using InputStreams MUST invoke this constructor prior to completing their initialization.
    Invoke this constructor from the subclass with:
    super(stream);
    
    Parameters:
    
    stream - InputStream, an InputStream object that references the data to be opened.
    
    encoding - String, a valid Charset encoding like "UTF-16", etc...
    
    See Also:
    
    ClassLoader.getSystemResourceAsStream(java.lang.String)
- Method Detail
  - setFile
```
protected void setFile(java.io.File newfile)
```
    Allows us to set (and change) the file that will be read. Setting the file also opens the file for reading (assuming it is a valid file).
  - setStream
```
protected void setStream(java.io.InputStream stream)
```
    Allows us to set (and change) the data that will be read. Setting the stream also "open()s" it for reading through the BufferedReader.
  - getFilename
```
public java.lang.String getFilename()
```
    Subclasses should not need to override this function.
    
    Returns:
    
    the short format of the filename--no path information. An empty string if this object failed to open the file.
  - getFullpath
```
public java.lang.String getFullpath()
```
    Subclasses should not need to override this function.
    
    Returns:
    
    the full filename path of the file. An empty string if this object failed to open.
  - isClosed
```
public boolean isClosed()
```
    Subclasses should not need to override this function.
    
    Returns:
    
    true if the BufferedReader was not successfully opened or has been closed (nulled).
  - isEOF
```
public boolean isEOF()
```
    Subclasses should not need to override this function.
    
    Returns:
    
    true if we have reached the end of the file. Reaching end of file does not Close the file. However, this file cannot be reset. So reaching end of file pretty much means this object has reached the end of its usefulness.
  - readLine
```
public java.lang.String readLine()
```
    This routine is the most basic readLine function. It simply gets the next line in the file. It will remove any leading ignorable Unicode FORMAT character from the first line of a file. This is generally required when reading UTF-8 files with the leading FORMAT marker (BOM).
    Subclasses that intend to maintain any kind of pointers MUST override this method in order to maintain their pointer counts but should still call this method with super.readLine() to retain the Unicode character removal on the retrieved text.
    It is still desirable to maintain the basic functionality of returning the text value unmodified in each subclass intending to return lines of text. A subclass wishing to embellish or otherwise process the line of text before returning it should do so in a different method specific to that subclass.
    
    Returns:
    
    the next line in the file. If the file is closed or has reached the end of file, then a NULL value is returned and EOF is set true.
  - resetpointers
```
protected void resetpointers()
```
    Resets important fields during Close and other operations. Subclasses should override this function to add any additional pointer or value reset operations. Those subclasses should still call the superclass method with:
    super.resetpointers();
  - openFile
```
protected void openFile()
```
    Called internally by open(). Sets BufferedReader to a valid reader or null;
  - openStream
```
protected void openStream()
```
    Called internally by open(). Sets BufferedReader to a valid reader or null;
  - open
```
public void open()
```
    Subclasses should not need to override this function unless some very interesting things need to be done before or after the file is opened. However, since the file is opened during object construction, all that interesting stuff should be handled there, not here.
  - closeReader
```
protected void closeReader()
```
    Shutdown (close) the file reader if it exists. The reader will be nulled on exit.
  - close
```
public void close()
```
    A call to this routine is essentially telling the object that its useful life is over. This is the equivalent of "terminate". You are soon to be NULLED and garbage collected. The open BufferedReader is closed by calling closeReader. The remaining API will respond accordingly signalling that the file isClosed.
    Subclasses should not need to override this function unless there is additional cleanup needed prior to getting whacked. If the method is overridden, the subclass should still call this routine with:
    super.close();
    
    See Also:
    
    closeReader(), resetpointers()

Class FileLineReader

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_BUFFER_SIZE

fullpath

filename

stream

file

reader

eof

firstline

charset

linetext

Constructor Detail

FileLineReader

FileLineReader

FileLineReader

FileLineReader

FileLineReader

Method Detail

setFile

setStream

getFilename

getFullpath

isClosed

isEOF

readLine

resetpointers

openFile

openStream

open

closeReader

close