public class SAFSFileReader
extends java.lang.Object
implements com.ibm.staf.service.STAFServiceInterfaceLevel1
This SAFSFileReader class is our base class for external STAF File reading services.
This service creates and maintains collections of SAFSFile objects. These represent open files.
The intention is to provide shared file services for opening files and sharing the file contents across the system. For example, one process can open the file, and then any number of other processes can read the contents.
The SAFSFileReader provides basic implementations for 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/SAFSFileReader [PARMS <Parameters>] Other examples: SERVICE ADD SERVICE FileReader LIBRARY JSTAF EXECUTE org/safs/staf/service/SAFSFileReader SERVICE ADD SERVICE StepReader LIBRARY JSTAF EXECUTE org/safs/staf/service/SAFSFileReader PARMS DIR c:\repo\Datapool EXT ".sdd" SERVICE ADD SERVICE BenchReader LIBRARY JSTAF EXECUTE org/safs/staf/service/SAFSFileReader PARMS DIR "c:\new repo\Datapool\Bench"
1.1 Valid Parameters when registering a SAFSFileReader 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 > /
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.
The READL command simply returns the next line of text from the file.
No special processing or handling happens on the text. If we have reached
the end of file, the request returns ":EOF:".
Syntax:
[ HANDLE < Handle > | NAME < Process > ] ID < FileID > READL
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 CLOSE command closes and releases resources for the file.
Syntax:
[ HANDLE < Handle > | NAME < Process > ] ID < FileID > CLOSE
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 QUERY command returns requested information about an open file.
Syntax:
[ HANDLE < Handle > | NAME < Process > ] ID < FileID > QUERY < STATUS | FILENAME | FULLPATH | LASTERROR >
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.3.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 at EOF is still open. However, this basic reader does not support moving the file pointer backwards. So, essentially, the object is not useful at this point.
2.3.5 FILENAME is the short filename of the file without any path information. Due to the OPEN parameters DIR and EXT, the filename of the file may be different than any relative path information that was provided to the OPEN command.
2.3.6 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.3.7 LASTERROR is not yet implemented.
The LIST command returns info on each open file for the service.
Syntax:
[ HANDLE < Handle > | NAME < Process > ] LIST
2.4.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.4.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 SAFSFileReader 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 |
---|---|
protected static java.lang.String |
c
a single colon
|
protected java.lang.String |
dir |
protected java.lang.String |
ext |
protected boolean |
file_extension_available |
protected com.ibm.staf.service.STAFCommandParser |
parser |
protected static java.lang.String |
r
a single newline
|
protected boolean |
relative_path_allowed |
protected static java.lang.String |
s
a single space
|
protected static java.util.ResourceBundle |
safsfilereader_resources |
protected java.lang.String |
servicename |
protected java.lang.String |
serviceparams |
static java.lang.String |
SFR_RBKEY_ERROR_NOT_INTEGER |
static java.lang.String |
SFR_RBKEY_NOT_IMPLEMENTED |
static java.lang.String |
SFR_RBKEY_OPEN_FILES |
static java.lang.String |
SFR_RBKEY_REQUIRED |
static java.lang.String |
SFR_RBKEY_SYNC_ERROR |
static java.lang.String |
SFR_RBKEY_UCPATH |
static java.lang.String |
SFR_SERVICE_FILE_STATE_CLOSED |
static java.lang.String |
SFR_SERVICE_FILE_STATE_EOF |
static java.lang.String |
SFR_SERVICE_FILE_STATE_ERROR |
static java.lang.String |
SFR_SERVICE_FILE_STATE_OPEN |
protected int |
SFR_SERVICE_INIT_PARMS_MAX
The maximum number of options/parameters we expect a service initialization request to receive.
|
static java.lang.String |
SFR_SERVICE_OPTION_DIR |
static java.lang.String |
SFR_SERVICE_OPTION_EXT |
static java.lang.String |
SFR_SERVICE_PARM_FILE |
static java.lang.String |
SFR_SERVICE_PARM_FILENAME |
static java.lang.String |
SFR_SERVICE_PARM_FULLPATH |
static java.lang.String |
SFR_SERVICE_PARM_HANDLE |
static java.lang.String |
SFR_SERVICE_PARM_ID |
static java.lang.String |
SFR_SERVICE_PARM_LASTERROR |
static java.lang.String |
SFR_SERVICE_PARM_NAME |
static java.lang.String |
SFR_SERVICE_PARM_STATUS |
protected int |
SFR_SERVICE_REQUEST_ARGS_MAX
The maximum number of options/parameters we expect a running service to receive in a request.
|
static java.lang.String |
SFR_SERVICE_REQUEST_CLOSE |
static java.lang.String |
SFR_SERVICE_REQUEST_HELP |
static java.lang.String |
SFR_SERVICE_REQUEST_LIST |
static java.lang.String |
SFR_SERVICE_REQUEST_OPEN |
static java.lang.String |
SFR_SERVICE_REQUEST_QUERY |
static java.lang.String |
SFR_SERVICE_REQUEST_READL |
static java.lang.String |
SFR_SERVICE_SAFSFILE_BUNDLE_NAME
The fully qualified name of the localizable ResourceBundle for this class.
|
protected java.lang.String |
SFR_SERVICE_SAFSFILE_LISTINFO
The text substring identifying the file type in each file LIST response.
|
Constructor and Description |
---|
SAFSFileReader()
The constructor used by the SAFSFileReader.
|
Modifier and Type | Method and Description |
---|---|
com.ibm.staf.STAFResult |
acceptRequest(java.lang.String machine,
java.lang.String process,
int handle,
java.lang.String request) |
protected void |
addBaseCommandOptionGroups(com.ibm.staf.service.STAFCommandParser aparser) |
protected void |
addBaseCommandOptionNeeds(com.ibm.staf.service.STAFCommandParser aparser) |
protected void |
addBaseCommandOptions(com.ibm.staf.service.STAFCommandParser aparser) |
protected void |
addBaseServiceInitOptions(com.ibm.staf.service.STAFCommandParser registrar) |
protected void |
addCommandOptionGroups(com.ibm.staf.service.STAFCommandParser aparser)
Add command option groups as needed.
|
protected void |
addCommandOptionNeeds(com.ibm.staf.service.STAFCommandParser aparser)
Add command option "requirements.
|
protected void |
addCommandOptions(com.ibm.staf.service.STAFCommandParser aparser)
Add your own command options in the STAFCommandParser.
|
protected void |
addServiceInitOptions(com.ibm.staf.service.STAFCommandParser registrar)
Add your initialization options for your service.
|
protected void |
buildBaseCommandList(com.ibm.staf.service.STAFCommandParser aparser) |
protected void |
buildBaseQueryCommandList(com.ibm.staf.service.STAFCommandParser aparser) |
protected java.lang.String |
buildCommandList(java.lang.String requestoptions)
Add your primary command options to the list of mutually exclusive commands.
|
protected java.lang.String |
buildHELPInfo() |
protected java.lang.String |
buildQueryCommandList(java.lang.String queryoptions)
Like primary commands, the QUERY command has a list of mutually
exclusive options.
|
protected java.lang.String |
getHELPInfo(java.lang.String info)
Add your HELP text response here.
|
protected java.lang.String |
getLISTInfo()
Override this function and return your version of SFR_SERVICE_SAFSFILE_LISTINFO.
|
protected java.lang.String |
getOPENInfo(com.ibm.staf.service.STAFCommandParseResult parsedData,
java.lang.String info)
Handle any added OPEN options here.
|
protected SAFSFile |
getParsedDataTextFile(com.ibm.staf.STAFResult result,
int handle,
java.lang.String fileid,
com.ibm.staf.service.STAFCommandParseResult parsedData) |
protected java.lang.String |
getQUERYInfo(SAFSFile textfile,
com.ibm.staf.service.STAFCommandParseResult parsedData,
java.lang.String info)
Handle any added QUERY options here.
|
protected java.lang.String |
getSTATUSInfo(SAFSFile textfile,
java.lang.String info)
Provide STATUS information for the QUERY STATUS command.
|
int |
init(java.lang.String name,
java.lang.String params) |
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)
A subclass must override this function to instantiate its own file type.
|
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 parseData)
A subclass must override this function to handle requests not
handled by the superclass.
|
protected void |
removeParsedDataTextFile(com.ibm.staf.STAFResult result,
java.lang.String myprocess,
int handle,
java.lang.String fileid,
com.ibm.staf.service.STAFCommandParseResult parsedData) |
protected int |
shutdown()
perform final termination cleanup operations for your service.
|
int |
term() |
java.lang.String |
text(java.lang.String resourcekey)
Retrieves potentially localized text from the resource bundle
Localized subclasses should provide a similar function or override this function.
|
protected int |
validateBaseServiceParseResult(com.ibm.staf.service.STAFCommandParseResult parsedData) |
protected int |
validateServiceParseResult(com.ibm.staf.service.STAFCommandParseResult parsedData)
Use to validate the Service initialization string after a request
for initialization has beenr received.
|
protected java.lang.String SFR_SERVICE_SAFSFILE_LISTINFO
public static final java.lang.String SFR_SERVICE_SAFSFILE_BUNDLE_NAME
protected int SFR_SERVICE_INIT_PARMS_MAX
protected int SFR_SERVICE_REQUEST_ARGS_MAX
protected static java.util.ResourceBundle safsfilereader_resources
public static final java.lang.String SFR_RBKEY_NOT_IMPLEMENTED
public static final java.lang.String SFR_RBKEY_OPEN_FILES
public static final java.lang.String SFR_RBKEY_UCPATH
public static final java.lang.String SFR_RBKEY_SYNC_ERROR
public static final java.lang.String SFR_RBKEY_REQUIRED
public static final java.lang.String SFR_RBKEY_ERROR_NOT_INTEGER
public static final java.lang.String SFR_SERVICE_OPTION_DIR
public static final java.lang.String SFR_SERVICE_OPTION_EXT
public static final java.lang.String SFR_SERVICE_REQUEST_OPEN
public static final java.lang.String SFR_SERVICE_REQUEST_READL
public static final java.lang.String SFR_SERVICE_REQUEST_QUERY
public static final java.lang.String SFR_SERVICE_REQUEST_CLOSE
public static final java.lang.String SFR_SERVICE_REQUEST_LIST
public static final java.lang.String SFR_SERVICE_REQUEST_HELP
public static final java.lang.String SFR_SERVICE_PARM_HANDLE
public static final java.lang.String SFR_SERVICE_PARM_NAME
public static final java.lang.String SFR_SERVICE_PARM_ID
public static final java.lang.String SFR_SERVICE_PARM_FILE
public static final java.lang.String SFR_SERVICE_PARM_STATUS
public static final java.lang.String SFR_SERVICE_PARM_FILENAME
public static final java.lang.String SFR_SERVICE_PARM_FULLPATH
public static final java.lang.String SFR_SERVICE_PARM_LASTERROR
public static final java.lang.String SFR_SERVICE_FILE_STATE_OPEN
public static final java.lang.String SFR_SERVICE_FILE_STATE_CLOSED
public static final java.lang.String SFR_SERVICE_FILE_STATE_EOF
public static final java.lang.String SFR_SERVICE_FILE_STATE_ERROR
protected com.ibm.staf.service.STAFCommandParser parser
protected java.lang.String servicename
protected java.lang.String serviceparams
protected boolean relative_path_allowed
protected boolean file_extension_available
protected java.lang.String dir
protected java.lang.String ext
protected static java.lang.String c
protected static java.lang.String s
protected static java.lang.String r
public SAFSFileReader()
super();
This constructor will initialize the STAFCommandParser that will be used for all requests sent to the service.
public java.lang.String text(java.lang.String resourcekey)
text = super.text(resourceKey);
resourceKey
- the key name of the message to retrieve.
protected void addCommandOptions(com.ibm.staf.service.STAFCommandParser aparser)
aparser.addOption(A_COMMAND_CONSTANT, 1, STAFCommandParser.VALUENOTALLOWED);
aparser.addOption(A_COMMAND_CONSTANT, 2, STAFCommandParser.VALUEALLOWED);
aparser.addOption(A_COMMAND_OPTION, 1, STAFCommandParser.VALUEREQUIRED);
aparser.addOption(A_COMMAND_OPTION, 9, STAFCommandParser.VALUEALLOWED);
super.addCommandOptions( aparser );
aparser
- the instance of the parser that will handle requests.protected java.lang.String buildCommandList(java.lang.String requestoptions)
requestoptions += s+ COMMAND1 +s+ COMMAND2 +s+ COMMAND3 +s;
return super.buildCommandList( requestoptions );
requestoptions
- the space-delimited list of commandsprotected void addCommandOptionGroups(com.ibm.staf.service.STAFCommandParser aparser)
options = THIS_ONE +s+ THAT_ONE +s+ ANOTHER_ONE;
aparser.addOptionGroups( options, 0,1 );
super.addCommandOptionGroups( aparser );
The example shows 3 options, only one may be specified at a time, none are required.
aparser
- the parser instance that will process incoming requests.protected void addCommandOptionNeeds(com.ibm.staf.service.STAFCommandParser aparser)
aparser.addOptionNeeds( OPEN_COMMAND, FILE_OPTION );
aparser.addOptionNeeds( OPEN_COMMAND, ID_OPTION );
super.addCommandOptionNeeds( aparser );
The example shows that the OPEN command needs a FILE specified, and an ID specified.
aparser
- the parser instance that will process incoming requests.protected java.lang.String buildQueryCommandList(java.lang.String queryoptions)
queryoptions += s+ STATUS +s+ FILENAME +s+ FULLPATH +s;
return super.buildQueryCommandList( queryoptions );
queryoptions
- the space-delimited list of optionsprotected void addServiceInitOptions(com.ibm.staf.service.STAFCommandParser registrar)
The format of the call is the OPTION string, the maximum times it can appear in a single request, and whether it is standalone, or whether an associated option value is required, or optional.
aparser.addOption(A_SERCICE_OPTION, 3, STAFCommandParser.VALUENOTALLOWED);
aparser.addOption(A_SERVICE_OPTION, 1, STAFCommandParser.VALUEREQUIRED);
super.addServiceInitOptions( registrar );
registrar
- the parser handling the service init request.protected int validateServiceParseResult(com.ibm.staf.service.STAFCommandParseResult parsedData)
This is where you check to see which options exist in the request, and act upon them. Make sure you also forward the validation request up the food chain so the superclasses can validate their service init options, too.
return super.validateServiceParseResult( parsedData );
parsedData
- the result object after parsing was performedprotected java.lang.String getSTATUSInfo(SAFSFile textfile, java.lang.String info)
return super.getSTATUSInfo( textfile, info );
textfile
- the instance of the SAFSFile object to play with.
info
- the status string that will be displayed for the
QUERY STATUS command.
protected java.lang.String getQUERYInfo(SAFSFile textfile, com.ibm.staf.service.STAFCommandParseResult parsedData, java.lang.String info)
return super.getQUERYInfo( textfile, parsedData, info );
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 java.lang.String getLISTInfo()
protected java.lang.String getOPENInfo(com.ibm.staf.service.STAFCommandParseResult parsedData, java.lang.String info)
return super.getOPENInfo( parsedData, info );
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 getHELPInfo(java.lang.String info)
info += MY_LONG_INVOLVED_FORMATTED_HELP_TEXT;
return super.getHELPInfo( info );
info
- the response string that will be displayed for the
HELP 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)
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.
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 parseData)
return super.processRequest(result, machine, process, handle, parsedData);
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.
parsedData
- the parsed result containing the command and the
user-supplied options provided.
protected int shutdown()
return super.shutdown();
protected final java.lang.String buildHELPInfo()
protected final void addBaseCommandOptions(com.ibm.staf.service.STAFCommandParser aparser)
protected final void addBaseServiceInitOptions(com.ibm.staf.service.STAFCommandParser registrar)
protected final int validateBaseServiceParseResult(com.ibm.staf.service.STAFCommandParseResult parsedData)
protected final void buildBaseCommandList(com.ibm.staf.service.STAFCommandParser aparser)
protected final void addBaseCommandOptionGroups(com.ibm.staf.service.STAFCommandParser aparser)
protected final void buildBaseQueryCommandList(com.ibm.staf.service.STAFCommandParser aparser)
protected final void addBaseCommandOptionNeeds(com.ibm.staf.service.STAFCommandParser aparser)
public final int init(java.lang.String name, java.lang.String params)
init
in interface com.ibm.staf.service.STAFServiceInterfaceLevel1
public final com.ibm.staf.STAFResult acceptRequest(java.lang.String machine, java.lang.String process, int handle, java.lang.String request)
acceptRequest
in interface com.ibm.staf.service.STAFServiceInterfaceLevel1
protected final void removeParsedDataTextFile(com.ibm.staf.STAFResult result, java.lang.String myprocess, int handle, java.lang.String fileid, com.ibm.staf.service.STAFCommandParseResult parsedData)
protected final SAFSFile getParsedDataTextFile(com.ibm.staf.STAFResult result, int handle, java.lang.String fileid, com.ibm.staf.service.STAFCommandParseResult parsedData)
public final int term()
term
in interface com.ibm.staf.service.STAFServiceInterfaceLevel1
Copyright © SAS Institute. All Rights Reserved.