public class SAFSTextFileReader extends SAFSFileReader implements com.ibm.staf.service.STAFServiceInterfaceLevel1
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The HELP command returns syntax information for the TextFileReader service.
Syntax:
HELP
Software Automation Framework Support (SAFS) https://safsdev.github.io/
Software Testing Automation Framework (STAF) http://staf.sourceforge.net
Modifier and Type | Field and Description |
---|---|
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.
|
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 and Description |
---|
SAFSTextFileReader()
Default constructor MUST call the superclass constructor.
|
Modifier and Type | Method and Description |
---|---|
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.
|
acceptRequest, addBaseCommandOptionGroups, addBaseCommandOptionNeeds, addBaseCommandOptions, addBaseServiceInitOptions, addCommandOptionGroups, addCommandOptionNeeds, addServiceInitOptions, buildBaseCommandList, buildBaseQueryCommandList, buildHELPInfo, getParsedDataTextFile, getSTATUSInfo, init, removeParsedDataTextFile, shutdown, term, text, validateBaseServiceParseResult, validateServiceParseResult
protected java.lang.String SFR_SERVICE_SAFSFILE_LISTINFO
protected int SFR_SERVICE_PARM_COMMENT_MAX
protected int SFR_SERVICE_REQUEST_ARGS_MAX
public static final java.lang.String SFR_SERVICE_REQUEST_NEXT
public static final java.lang.String SFR_SERVICE_REQUEST_PEEK
public static final java.lang.String SFR_SERVICE_REQUEST_MARK
public static final java.lang.String SFR_SERVICE_REQUEST_RESET
public static final java.lang.String SFR_SERVICE_REQUEST_BEGIN
public static final java.lang.String SFR_SERVICE_PARM_COMMENT
public static final java.lang.String SFR_SERVICE_PARM_TRIMLEADING
public static final java.lang.String SFR_SERVICE_PARM_TRIMTRAILING
public static final java.lang.String SFR_SERVICE_PARM_TRIMWHITESPACE
public static final java.lang.String SFR_SERVICE_PARM_SKIPBLANKLINES
public static final java.lang.String SFR_SERVICE_PARM_NOLINENUMBERS
public static final java.lang.String SFR_SERVICE_PARM_LINEPOINTER
public static final java.lang.String SFR_SERVICE_PARM_MARKPOINTER
public SAFSTextFileReader()
protected void addCommandOptions(com.ibm.staf.service.STAFCommandParser aparser)
addCommandOptions
in class SAFSFileReader
aparser
- the instance of the parser that will handle requests.protected java.lang.String buildCommandList(java.lang.String requestoptions)
buildCommandList
in class SAFSFileReader
requestoptions
- the space-delimited list of commandsprotected java.lang.String buildQueryCommandList(java.lang.String queryoptions)
buildQueryCommandList
in class SAFSFileReader
queryoptions
- the space-delimited list of optionsprotected void buildCommandOptionNeeds(com.ibm.staf.service.STAFCommandParser aparser)
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)
processRequest
in class SAFSFileReader
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.
protected java.lang.String getHELPInfo(java.lang.String info)
getHELPInfo
in class SAFSFileReader
info
- the response string that will be displayed for the
HELP command.
protected java.lang.String getLISTInfo()
getLISTInfo
in class SAFSFileReader
protected java.lang.String getOPENInfo(com.ibm.staf.service.STAFCommandParseResult parsedData, java.lang.String info)
getOPENInfo
in class SAFSFileReader
parsedData
- the parsed request to interrogate for OPEN option
parameter values.
info
- the status string that will be displayed for the
OPEN command.
protected java.lang.String getQUERYInfo(SAFSFile textfile, com.ibm.staf.service.STAFCommandParseResult parsedData, java.lang.String info)
getQUERYInfo
in class SAFSFileReader
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.
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)
openFile
in class SAFSFileReader
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.
Copyright © SAS Institute. All Rights Reserved.