org.safs.staf.service
Class SAFSTextFileReader

java.lang.Object
  org.safs.staf.service.SAFSFileReader
      org.safs.staf.service.SAFSTextFileReader

All Implemented Interfaces:

com.ibm.staf.service.STAFServiceInterfaceLevel1

public class SAFSTextFileReader
extends SAFSFileReader
implements com.ibm.staf.service.STAFServiceInterfaceLevel1

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

This SAFSTextFileReader class is an external STAF service run by the JSTAF Service Proxy.
The intention is to provide buffered read-only file services for reading text files line-by-line, bookmarking a particular line, and even going back to the beginning of the file.

The TextFileReader service provides the following commands:

• OPEN - open a text file for read operations
• NEXT - return the next line (record) from the file
• PEEK - get the current line (again) without incrementing the line pointer
• MARK - bookmark the file position for any subsequent RESET
• RESET - reset the line pointer to the previous MARK
• BEGIN - reset the line pointer to the beginning of the file
• QUERY - retrieve status information from the file
• CLOSE - close and release resources on the text file
• LIST - list open information for the service instance
• HELP - returns syntax information

1.0 SAFSTextFileReader Service Registration

Each instance of the service must be registered via the STAF Service service.

Example showing comandline registration:

 STAF LOCAL SERVICE ADD SERVICE <servicename> LIBRARY JSTAF /
            EXECUTE org/safs/staf/service/SAFSTextFileReader [PARMS <Parameters>]

 Other examples:

 SERVICE ADD SERVICE FileReader  LIBRARY JSTAF EXECUTE org/safs/staf/service/TextFileReader

 SERVICE ADD SERVICE StepReader  LIBRARY JSTAF EXECUTE org/safs/staf/service/TextFileReader PARMS DIR c:\repo\Datapool EXT ".sdd"

 SERVICE ADD SERVICE BenchReader LIBRARY JSTAF EXECUTE org/safs/staf/service/TextFileReader PARMS DIR "c:\new repo\Datapool\Bench"

 

1.1 Valid Parameters when registering a SAFSTextFileReader service:

1.1.1 DIR <default directory>
If provided, the DIR parameter specifies a default directory to use if the OPEN request provides relative path information or no path information at all. File searches will not use environment PATH information. The OPEN request expects a full filename path, or a path relative to this DIR option.

EX: PARMS DIR "c:\testrepo\Datapool"

If the DIR parameter is not provided, then OPEN requests will not attempt relative path searches. The filename provided to the OPEN request must then be an exact full filepath match or the OPEN request will fail.

1.1.2 EXT <default file extension>
If provided, the EXT parameter specifies a default file extension (suffix) to try if the OPEN request does not find the file as provided. You must include any period (.) if it is to be part of any appended suffix.

EX: PARMS EXT .txt

If the EXT parameter is not provided, then OPEN requests will not attempt the additional file search with the appended extension if the provided filename was not found. The filename provided to the OPEN request must then be an exact filename.ext match or the OPEN request will fail.

2.0 SAFSTextFileReader Commands

Note, there must be a uniquely qualified match for NAME/ID combinations listed below. If the same Process has opened two different files with the same ID from 2 different Handles, then you will have to use HANDLE, instead of NAME.

2.1 OPEN

The OPEN command attempts to open a file for read operations.

Syntax:

OPEN ID < FileID > FILE < Filename > /
[ TRIMLEADING | TRIMTRAILING | TRIMWHITESPACE ] [ SKIPBLANKLINES ] /
[ COMMENTLINE <Prefix> ]... [ NOLINENUMBERS ]

2.1.1 ID is a unique name for this file handling instance.

2.1.2 FILE is the filename of the file to open.
If a default Directory was specified when the service was launched, then the filename can be relative to that directory. Otherwise, the full filepath must be specified.
If a default Extension (Ext) was specified when the service was launched, then the filename can be specified without the extension.

2.1.3 TRIMLEADING, TRIMTRAILING, TRIMWHITESPACE
If provided, the TrimLeading option specifies that each line should be trimmed of leading whitespace only. TrimTrailing specifies that each line should be trimmed of trailing whitespace only. TrimWhitespace specifies that each line should be trimmed of both leading and trailing whitespace.
"Whitespace" is considered to be all control characters below ' '(SPACE).

2.1.4 SKIPBLANKLINES instructs the reader to skip empty lines and lines containing only whitespace. Skipped blank lines are still counted.
"Whitespace" is considered to be all control characters below ' '(SPACE).

2.1.5 COMMENTLINE specifies a substring of 1 or more characters that prefix a line and identify the line as a comment. If COMMENTLINE options are specified, lines that begin with the specified prefix are skipped (though counted) for read operations. You can specify up to 10 COMMENTLINE options and each will separately identify comment lines in the file. The test for a comment line occurs after leading whitespace has been trimmed if TRIMLEADING or TRIMWHITESPACE options have been specified.
"Whitespace" is considered to be all control characters below ' '(SPACE).

2.1.6 NOLINENUMBERS specifies lines read from the file should not be returned with line numbers prefixed.

2.2 NEXT

The NEXT command returns the next available line in the specified file. The text will be trimmed and prefixed with linenumbers according to parameters provided when the file was OPENed. Blank lines and/or comment lines will also be skipped according to OPEN parameters.

Syntax:

[ HANDLE < Handle > | NAME < Process > ] ID < fileID > NEXT

2.2.1 HANDLE specifies the handle of the process that OPENed the file. You can instead provide the NAME of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.2.2 NAME specifies the name of the process that OPENed the file. You can instead provide the HANDLE of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.2.3 ID is the unique fileID that was provided when the file was OPENed.

2.3 PEEK

The PEEK command returns (again) the current line without incrementing line pointers. This is the same text that would have been received from the most recent NEXT command. The value returned from PEEK is undefined following a RESET or BEGIN command. Not until the NEXT command will PEEK accurately reflect the last (current) read.

Syntax:

[ HANDLE < Handle > | NAME < Process > ] ID < fileID > PEEK

2.3.1 HANDLE specifies the handle of the process that OPENed the file. You can instead provide the NAME of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.3.2 NAME specifies the name of the process that OPENed the file. You can instead provide the HANDLE of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.3.3 ID is the unique fileID that was given provided when the file was OPENed.

2.4 MARK

The MARK command bookmarks the current line number (the start of the next line) for any subsequent RESET. That is: MARK points to the line BEFORE the first line that will be read after a RESET.

Syntax:

[ HANDLE < Handle > | NAME < Process > ] ID < FileID > MARK

2.4.1 HANDLE specifies the handle of the process that OPENed the file. You can instead provide the NAME of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.4.2 NAME specifies the name of the process that OPENed the file. You can instead provide the HANDLE of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.4.3 ID is the unique fileID that was given provided when the file was OPENed.

2.5 RESET

The RESET command resets the reader to the previous MARK position. The MARK effectively points to the next line to read, and any "current" line text (such as returned in PEEK) may not be accurate until the NEXT command is performed.

Syntax:

[ HANDLE < Handle > | NAME < Process > ] ID < FileID > RESET

2.5.1 HANDLE specifies the handle of the process that OPENed the file. You can instead provide the NAME of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.5.2 NAME specifies the name of the process that OPENed the file. You can instead provide the HANDLE of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.5.3 ID is the unique fileID that was given provided when the file was OPENed.

2.6 BEGIN

The BEGIN command resets the line pointer to the beginning of the file. The pointer is set to read the first line in the file, and any "current" line text (such as returned in PEEK) may not be accurate until that first NEXT read is performed.

Syntax:

[ HANDLE < Handle > | NAME < Process > ] ID < FileID > BEGIN

2.6.1 HANDLE specifies the handle of the process that OPENed the file. You can instead provide the NAME of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.6.2 NAME specifies the name of the process that OPENed the file. You can instead provide the HANDLE of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.6.3 ID is the unique fileID that was given provided when the file was OPENed.

2.7 CLOSE

The CLOSE command closes and releases resources for the file.

Syntax:

[ HANDLE < Handle > | NAME < Process > ] ID < FileID > CLOSE

2.7.1 HANDLE specifies the handle of the process that OPENed the file. You can instead provide the NAME of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.7.2 NAME specifies the name of the process that OPENed the file. You can instead provide the HANDLE of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.7.3 ID is the unique fileID that was given provided when the file was OPENed.

2.8 QUERY

The QUERY command returns requested information about an open file.

Syntax:

[ HANDLE < Handle > | NAME < Process > ] ID < FileID > QUERY < STATUS | LINEPOINTER | MARKPOINTER | FULLPATH | LASTERROR >

2.8.1 HANDLE specifies the handle of the process that OPENed the file. You can instead provide the NAME of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.8.2 NAME specifies the name of the process that OPENed the file. You can instead provide the HANDLE of the process that OPENed the file. If neither is provided then the Handle of the process that originated this request is assumed.

2.8.3 ID is the unique fileID that was given provided when the file was OPENed.

2.8.4 STATUS returns one of "OPEN", "CLOSED", or "EOF". If the "CLOSED" status is returned, that generally means some type of critical failure has occurred. A file that is OPEN or at EOF can still be RESET or sent to the first line with BEGIN.

2.8.5 LINEPOINTER returns the current value of the line pointer. This generally contains the number of the "current" line--the last line read. The first line of a file is line 1.

2.8.6 MARKPOINTER returns the current value of the MARK pointer. If a bookMARK has been set, the pointer contains the line number of the line BEFORE the line that will be read after a RESET. That is, the line number of the line that was just read before the MARK command was performed. This is, effectively, a pointer to the next line. 8^p

2.8.7 FULLPATH is the full path to the file. Due to the OPEN parameters DIR and EXT, the full path to the file may be different than any relative path information that was provided to the OPEN command.

2.8.8 LASTERROR is not yet implemented.

2.9 LIST

The LIST command returns info on each open file for the service.

Syntax:

[ HANDLE < Handle > | NAME < Process > ] LIST

2.9.1 HANDLE specifies the handle of the process to query. You can instead provide the NAME of the process to query. If neither is provided then the Handle of the process that originated this request is assumed.

2.9.2 NAME specifies the name of the process to query. You can instead provide the HANDLE of the process to query. If neither is provided then the Handle of the process that originated this request is assumed.

2.10 HELP

The HELP command returns syntax information for the TextFileReader service.

Syntax:

HELP

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

Field Summary

static java.lang.String	SFR_SERVICE_PARM_COMMENT
protected int	SFR_SERVICE_PARM_COMMENT_MAX The maximum number of COMMENT options handled in a request.
static java.lang.String	SFR_SERVICE_PARM_LINEPOINTER
static java.lang.String	SFR_SERVICE_PARM_MARKPOINTER
static java.lang.String	SFR_SERVICE_PARM_NOLINENUMBERS
static java.lang.String	SFR_SERVICE_PARM_SKIPBLANKLINES
static java.lang.String	SFR_SERVICE_PARM_TRIMLEADING
static java.lang.String	SFR_SERVICE_PARM_TRIMTRAILING
static java.lang.String	SFR_SERVICE_PARM_TRIMWHITESPACE
protected int	SFR_SERVICE_REQUEST_ARGS_MAX Overrides the superclass limit of maximum request arguments.
static java.lang.String	SFR_SERVICE_REQUEST_BEGIN
static java.lang.String	SFR_SERVICE_REQUEST_MARK
static java.lang.String	SFR_SERVICE_REQUEST_NEXT
static java.lang.String	SFR_SERVICE_REQUEST_PEEK
static java.lang.String	SFR_SERVICE_REQUEST_RESET
protected java.lang.String	SFR_SERVICE_SAFSFILE_LISTINFO Override the superclass file type information.

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

c, dir, ext, file_extension_available, parser, r, relative_path_allowed, s, safsfilereader_resources, servicename, serviceparams, SFR_RBKEY_ERROR_NOT_INTEGER, SFR_RBKEY_NOT_IMPLEMENTED, SFR_RBKEY_OPEN_FILES, SFR_RBKEY_REQUIRED, SFR_RBKEY_SYNC_ERROR, SFR_RBKEY_UCPATH, SFR_SERVICE_FILE_STATE_CLOSED, SFR_SERVICE_FILE_STATE_EOF, SFR_SERVICE_FILE_STATE_ERROR, SFR_SERVICE_FILE_STATE_OPEN, SFR_SERVICE_INIT_PARMS_MAX, SFR_SERVICE_OPTION_DIR, SFR_SERVICE_OPTION_EXT, SFR_SERVICE_PARM_FILE, SFR_SERVICE_PARM_FILENAME, SFR_SERVICE_PARM_FULLPATH, SFR_SERVICE_PARM_HANDLE, SFR_SERVICE_PARM_ID, SFR_SERVICE_PARM_LASTERROR, SFR_SERVICE_PARM_NAME, SFR_SERVICE_PARM_STATUS, SFR_SERVICE_REQUEST_CLOSE, SFR_SERVICE_REQUEST_HELP, SFR_SERVICE_REQUEST_LIST, SFR_SERVICE_REQUEST_OPEN, SFR_SERVICE_REQUEST_QUERY, SFR_SERVICE_REQUEST_READL, SFR_SERVICE_SAFSFILE_BUNDLE_NAME

Constructor Summary

SAFSTextFileReader()
Default constructor MUST call the superclass constructor.

Method Summary

protected void	addCommandOptions(com.ibm.staf.service.STAFCommandParser aparser) Add all our new keywords to the list of superclass keywords.
protected java.lang.String	buildCommandList(java.lang.String requestoptions) Add our new commands to the list of superclass commands.
protected void	buildCommandOptionNeeds(com.ibm.staf.service.STAFCommandParser aparser) Add our new command dependencies to superclass dependencies.
protected java.lang.String	buildQueryCommandList(java.lang.String queryoptions) Add our new QUERY options to existing superclass QUERY options.
protected java.lang.String	getHELPInfo(java.lang.String info) Prepend our HELP text to the superclass HELP.
protected java.lang.String	getLISTInfo() Overrides the superclass function to return our SAFSTextFile type.
protected java.lang.String	getOPENInfo(com.ibm.staf.service.STAFCommandParseResult parsedData, java.lang.String info) Append our string response to the OPEN file request.
protected java.lang.String	getQUERYInfo(SAFSFile textfile, com.ibm.staf.service.STAFCommandParseResult parsedData, java.lang.String info) Handle the new QUERY options we have added for this service.
protected SAFSFile	openFile(java.lang.String machine, java.lang.String process, int handle, java.lang.String fileid, java.io.File file, com.ibm.staf.service.STAFCommandParseResult parsedData) Overrides the superclass function to instantiate SAFSTextFiles instead.
protected com.ibm.staf.STAFResult	processRequest(com.ibm.staf.STAFResult result, java.lang.String machine, java.lang.String process, int handle, com.ibm.staf.service.STAFCommandParseResult parsedData) Process any of the new commands we have added for this service.

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

acceptRequest, addBaseCommandOptionGroups, addBaseCommandOptionNeeds, addBaseCommandOptions, addBaseServiceInitOptions, addCommandOptionGroups, addCommandOptionNeeds, addServiceInitOptions, buildBaseCommandList, buildBaseQueryCommandList, buildHELPInfo, getParsedDataTextFile, getSTATUSInfo, init, removeParsedDataTextFile, shutdown, term, text, validateBaseServiceParseResult, validateServiceParseResult

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.ibm.staf.service.STAFServiceInterfaceLevel1

acceptRequest, init, term

Field Detail

SFR_SERVICE_SAFSFILE_LISTINFO

protected java.lang.String SFR_SERVICE_SAFSFILE_LISTINFO

Override the superclass file type information.

SFR_SERVICE_PARM_COMMENT_MAX

protected int SFR_SERVICE_PARM_COMMENT_MAX

The maximum number of COMMENT options handled in a request.

SFR_SERVICE_REQUEST_ARGS_MAX

protected int SFR_SERVICE_REQUEST_ARGS_MAX

Overrides the superclass limit of maximum request arguments.

SFR_SERVICE_REQUEST_NEXT

public static final java.lang.String SFR_SERVICE_REQUEST_NEXT

See Also:

Constant Field Values

SFR_SERVICE_REQUEST_PEEK

public static final java.lang.String SFR_SERVICE_REQUEST_PEEK

See Also:

Constant Field Values

SFR_SERVICE_REQUEST_MARK

public static final java.lang.String SFR_SERVICE_REQUEST_MARK

See Also:

Constant Field Values

SFR_SERVICE_REQUEST_RESET

public static final java.lang.String SFR_SERVICE_REQUEST_RESET

See Also:

Constant Field Values

SFR_SERVICE_REQUEST_BEGIN

public static final java.lang.String SFR_SERVICE_REQUEST_BEGIN

See Also:

Constant Field Values

SFR_SERVICE_PARM_COMMENT

public static final java.lang.String SFR_SERVICE_PARM_COMMENT

See Also:

Constant Field Values

SFR_SERVICE_PARM_TRIMLEADING

public static final java.lang.String SFR_SERVICE_PARM_TRIMLEADING

See Also:

Constant Field Values

SFR_SERVICE_PARM_TRIMTRAILING

public static final java.lang.String SFR_SERVICE_PARM_TRIMTRAILING

See Also:

Constant Field Values

SFR_SERVICE_PARM_TRIMWHITESPACE

public static final java.lang.String SFR_SERVICE_PARM_TRIMWHITESPACE

See Also:

Constant Field Values

SFR_SERVICE_PARM_SKIPBLANKLINES

public static final java.lang.String SFR_SERVICE_PARM_SKIPBLANKLINES

See Also:

Constant Field Values

SFR_SERVICE_PARM_NOLINENUMBERS

public static final java.lang.String SFR_SERVICE_PARM_NOLINENUMBERS

See Also:

Constant Field Values

SFR_SERVICE_PARM_LINEPOINTER

public static final java.lang.String SFR_SERVICE_PARM_LINEPOINTER

See Also:

Constant Field Values

SFR_SERVICE_PARM_MARKPOINTER

public static final java.lang.String SFR_SERVICE_PARM_MARKPOINTER

See Also:

Constant Field Values

Constructor Detail

SAFSTextFileReader

public SAFSTextFileReader()

Default constructor MUST call the superclass constructor.

Method Detail

addCommandOptions

protected void addCommandOptions(com.ibm.staf.service.STAFCommandParser aparser)

Add all our new keywords to the list of superclass keywords.

Overrides:

addCommandOptions in class SAFSFileReader

Parameters:

aparser - the instance of the parser that will handle requests.

buildCommandList

protected java.lang.String buildCommandList(java.lang.String requestoptions)

Add our new commands to the list of superclass commands.

Overrides:

buildCommandList in class SAFSFileReader

Parameters:

requestoptions - the space-delimited list of commands

buildQueryCommandList

protected java.lang.String buildQueryCommandList(java.lang.String queryoptions)

Add our new QUERY options to existing superclass QUERY options.

Overrides:

buildQueryCommandList in class SAFSFileReader

Parameters:

queryoptions - the space-delimited list of options

buildCommandOptionNeeds

protected void buildCommandOptionNeeds(com.ibm.staf.service.STAFCommandParser aparser)

Add our new command dependencies to superclass dependencies.

processRequest

protected com.ibm.staf.STAFResult processRequest(com.ibm.staf.STAFResult result,
                                                 java.lang.String machine,
                                                 java.lang.String process,
                                                 int handle,
                                                 com.ibm.staf.service.STAFCommandParseResult parsedData)

Process any of the new commands we have added for this service.

Overrides:

processRequest in class SAFSFileReader

Parameters:

result - the object containing the return code and response string for the request.

machine - the machine initiating the request.

process - the name of the Process initiating the request.

handle - the Handle of the Process initiating the request.

Returns:

the result object after processing the request.

getHELPInfo

protected java.lang.String getHELPInfo(java.lang.String info)

Prepend our HELP text to the superclass HELP.

Overrides:

getHELPInfo in class SAFSFileReader

Parameters:

info - the response string that will be displayed for the HELP command.

Returns:

any text to be prepend the superclass response.

getLISTInfo

protected java.lang.String getLISTInfo()

Overrides the superclass function to return our SAFSTextFile type.

Overrides:

getLISTInfo in class SAFSFileReader

Returns:

the text substring to be inserted with the LIST response for each file listed.

getOPENInfo

protected java.lang.String getOPENInfo(com.ibm.staf.service.STAFCommandParseResult parsedData,
                                       java.lang.String info)

Append our string response to the OPEN file request.

Overrides:

getOPENInfo in class SAFSFileReader

Parameters:

parsedData - the parsed request to interrogate for OPEN option parameter values.

info - the status string that will be displayed for the OPEN command.

Returns:

any text to be added to the OPEN response.

getQUERYInfo

protected java.lang.String getQUERYInfo(SAFSFile textfile,
                                        com.ibm.staf.service.STAFCommandParseResult parsedData,
                                        java.lang.String info)

Handle the new QUERY options we have added for this service.

Overrides:

getQUERYInfo in class SAFSFileReader

Parameters:

textfile - the instance of the SAFSFile object to play with.

parsedData - the parsed request to interrogate for QUERY option parameter values.

info - the status string that will be displayed for the QUERY STATUS command.

Returns:

the text to be displayed by the QUERY STATUS command.

openFile

protected SAFSFile openFile(java.lang.String machine,
                            java.lang.String process,
                            int handle,
                            java.lang.String fileid,
                            java.io.File file,
                            com.ibm.staf.service.STAFCommandParseResult parsedData)

Overrides the superclass function to instantiate SAFSTextFiles instead.

Overrides:

openFile in class SAFSFileReader

Parameters:

machine - the machine initiating the request to open the file.

process - the name of the Process initiating the request to open the file.

handle - the Handle of the Process initiating the request to open the file.

fileid - the unique fileid to be assigned the file. fileids should be uniquely identifiable among all Handles for a given Process.

file - the File object used to open the file.

parsedData - the parsed result containing the OPEN command and any of the user-supplied options that may be needed when opening the file or setting options in the file handler.

Returns:

the instance of the SAFSFile object that has been created.