org.safs.staf.service
Class SAFSTextFile

java.lang.Object
  org.safs.text.FileLineReader
      org.safs.staf.service.SAFSFile
          org.safs.staf.service.SAFSTextFile

public class SAFSTextFile
extends SAFSFile

Copyright 2003 SAS Institute GNU General Public License (GPL) http://www.opensource.org/licenses/gpl-license.php

This SAFSTextFile class is intended as the file instance class for services.
Although there are no STAF dependencies, the class is tightly integrated with the reader. It has not been evaluated for any other use. Though, standalone use is likely possible.

The class uses a java.io.BufferedReader as the underlying IO mechanism.

See Also:

SAFSTextFileReader, Software Automation Framework Support (SAFS) http://safsdev.sourceforge.net
Software Testing Automation Framework (STAF) http://staf.sourceforge.net


Field Summary

static int

MARK_INVALID

Fields inherited from class org.safs.staf.service.SAFSFile

fileid, handle, machine, process

Fields inherited from class org.safs.text.FileLineReader

DEFAULT_BUFFER_SIZE, eof, file, filename, firstline, fullpath, linetext, reader, stream

Constructor Summary

SAFSTextFile()
This constructor will create an inoperable (Closed) file object.

SAFSTextFile(java.lang.String machine, java.lang.String process, int handle, java.lang.String fileid, java.io.File file, boolean skipblanklines, boolean nolinenumbers, boolean trimleading, boolean trimtrailing, boolean trimwhitespace, java.util.Vector commentids)
The constructor used by the SAFSTextFileReader.

Method Summary

void	begin() resets the current line pointer location back to the beginning of the file.
long	getLineNumber()
long	getMark()
void	mark() bookMarks the current line pointer location for a subsequent reset().
java.lang.String	next() Reads the lines in the file and returns the next line as required by option settings.
java.lang.String	peek() Returns the last line returned from the 'next' function.
java.lang.String	readLine() This adds to the SAFSFile.readLine function.
void	reset() resets the line pointer location to the position of the last bookMark.
protected void	resetpointers() resets our line and mark pointers to default read-to-get-started values.
void	setMark(long line) sets a new line pointer location for a subsequent reset().

Methods inherited from class org.safs.staf.service.SAFSFile

getFileID, getHandle, getMachine, getProcess

Methods inherited from class org.safs.text.FileLineReader

close, closeReader, getFilename, getFullpath, isClosed, isEOF, open, openFile, openStream, setFile, setStream

Methods inherited from class java.lang.Object

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

Field Detail

MARK_INVALID

public static final int MARK_INVALID

See Also:

Constant Field Values

Constructor Detail

SAFSTextFile

public SAFSTextFile()

This constructor will create an inoperable (Closed) file object. No use whatsoever. :)

SAFSTextFile

public SAFSTextFile(java.lang.String machine,
                    java.lang.String process,
                    int handle,
                    java.lang.String fileid,
                    java.io.File file,
                    boolean skipblanklines,
                    boolean nolinenumbers,
                    boolean trimleading,
                    boolean trimtrailing,
                    boolean trimwhitespace,
                    java.util.Vector commentids)

The constructor used by the SAFSTextFileReader. All subclasses MUST invoke this constructor prior to completing their initialization.
Invoke this constructor from the subclass with:

super(machine, process, handle, fileid, file, skipblanklines, /
nolinenumbers, trimleading, trimtrailing, trimwhitespace, /
commentids);

This class automatically initializes its SAFSFile superclass with a call to:

super(machine, process, handle, fileid, file);

Parameters:

machine - The STAF machine that requested this file be opened.

process - The STAF process that requested this file be opened.

handle - The STAF process handle that requested this file be opened.

fileid - A unique String ID to identify this file for the requesting process. This is not a filename. Multiple open views of the same file can be opened and each should have a unique fileid within the process namespace.

file - A File object that references the file to be opened.

skipblanklines - true to skip empty lines or lines with only whitespace. By default we it will not skip blank lines.

nolinenumbers - true to turn off the line numbering prefix. By defaul line numbers prefix the returned text.

trimleading - trim only leading whitespace from the line.

trimtrailing - trim only trailing whitespace from the line.

trimwhitespace - trim leading AND trailing whitespace from the line.

commentids - essentially a set of strings that identify a line as a comment line. If any are provided, then lines that begin with any one of the stored comment identifier strings will be skipped. The test for leading substring occurs AFTER trimming any whitespace if that is enabled.

Method Detail

getLineNumber

public long getLineNumber()

Returns:

the line number of the last line read.

getMark

public long getMark()

Returns:

the bookMark line pointer for the last bookMark set

readLine

public java.lang.String readLine()

This adds to the SAFSFile.readLine function. While it does not modify the returned line in any way, it does increment the line number pointer appropriately. It also ignores all line skipping settings. It reads the next line regardless.

This routine should always call super.readLine() to take advantage of UTF-8 FORMAT marker handling done in the superclass.

Overrides:

readLine in class FileLineReader

Returns:

the next line in the file using the basic super.readLine function. Returns null once at EOF.

next

public java.lang.String next()

Reads the lines in the file and returns the next line as required by option settings. If the skipping of blank lines and comment lines are enabled, a single call to this function will read any number of lines until the first non-blank, non-comment line is found. The check for leading comment substrings is done AFTER any trimming of leading whitespace.

The returned line will be prefixed with the line number followed by a colon unless 'nolinenumbers' was specified (true) when the object was created.

Returns:

the next line in the file based on the options specified at creation. Returns null once at EOF.

peek

public java.lang.String peek()

Returns the last line returned from the 'next' function. Thus, you can re-read the line any number of times. Note, the value returned may be something unexpected after a reset() or begin() operation. The value only becomes resynchronized and 'correct' after a call to the 'next()' function.

Returns:

the last line that was returned from the 'next' function.

mark

public void mark()

bookMarks the current line pointer location for a subsequent reset().

setMark

public void setMark(long line)
             throws java.lang.IllegalArgumentException

sets a new line pointer location for a subsequent reset().

Throws:

java.lang.IllegalArgumentException

reset

public void reset()

resets the line pointer location to the position of the last bookMark.

begin

public void begin()

resets the current line pointer location back to the beginning of the file.

resetpointers

protected void resetpointers()

resets our line and mark pointers to default read-to-get-started values. This routine also calls the function in SAFSFile:

super.resetpointers();

Overrides:

resetpointers in class FileLineReader