org.safs.staf.service.SAFSAppMapService
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public class SAFSAppMapService
Copyright 2003 SAS Institute GNU General Public License (GPL) http://www.opensource.org/licenses/gpl-license.php
This SAFSAppMapService class is an external STAF service run by the JSTAF Service Proxy.
The intention is to provide global read-only services for using SAFSAppMapFile files.
These files are, essentially, standard text-based Windows INI format files with
Name=Value entries that can be grouped into named sections or blocks.
It is important to note that in a true SAFS environment, AppMap services are nearly always tightly integrated with one or more SAFS Variable services. This is because we allow the retrieval of Variable values to "look thru" to AppMap "constants". And we allow the AppMap to provide dynamic values via Variables for items that are otherwise normally static.
The AppMapService adds additional lookup capabilities to the simple DEFAULTMAPSECTION capabilities of the underlying SAFSAppMapFile. The lookup tries the following:
The AppMapService typically looks for values in the 'default' AppMap. This is typically the last AppMap that was OPENed. This service will also now lookup values in what is called the AppMap 'chain'. This chain is simply a Last-In-First-Out (LIFO) buffer of open AppMaps. As an AppMap is OPENed it is placed at the top of the search chain. AppMaps already in the chain are moved down the chain and searched in a LIFO order. This allows a primary AppMap to be OPENed that might contain many default and shared values while subsequently opened AppMaps might have overriding entries, entries that build upon the defaults, or contain locale-specific entries for things like NLS testing.
The AppMap service will allow dynamic values to be specified in the AppMap file. This is done by providing the special SAM_DDV_PREFIX value in place of a fixed literal string.
;these two items have no section identifier
;they are part of an initial, unnamed section
AnItem = A normal static value
NewItem = Another static value
[ASection]
AnItem = A normal static value
Item2 = _DDV:
Item3 = _DDV:AVariableName
The syntax for Item2 specifies that the value should be satisfied by the Variable service retrieving the value of variable "Item2".
The syntax for Item3 specifies that the value should be satisfied by the Variable service retrieving the value of variable "AVariableName".
The AppMap service also allows variable references to be embedded in AppMap entries. This is done by tightly wrapping DDVariable references in curly braces {^varName} anywhere in the value portion of the AppMap entry. There should be no spaces anywhere between the curly braces or the variable will be considered literal text and will not be resolved.
;these two items have no section identifier
;they are part of an initial, unnamed section
AnItem = A normal static value
NewItem = Another static value
[ASection]
AnItem = A normal static value
Item2 = Type=Component;Text={^text}
Item3 = Type=Window;Caption={^caption};\;Type=CheckBox;Text={^text}
The syntax for Item2 specifies that the value of the DDVariable ^text should be retrieved and embedded in the value provided for Item2.
The syntax for Item3 specifies that the value of the DDVariables ^caption and ^text should be retrieved and embedded in the value provided for Item3.
The SAFSAppMapService service provides the following commands:
| OPEN | Open an AppMap |
| SAFSVARS | Get/Set the associated SAFSVARS service name |
| DEFAULTMAP | Get/Set the the ID of the "default" AppMap |
| DEFAULTMAPSECTION | Get/Set the "default" lookup Section within an AppMap |
| GETITEM | Get an AppMap item |
| CLEARCACHE | Clear all cached items in all open App Maps |
| DISABLECHAIN | Disable the chaining of AppMaps when seeking entries |
| ENABLECHAIN | Enable the chaining of AppMaps when seeking entries (default) |
| DISABLERESOLVE | Disable the resolving of embedded DDVariables |
| ENABLERESOLVE | Enable the resolving of embedded DDVariables (default) |
| QUERY | Get other information from an AppMap |
| CLOSE | Close and release resources on an AppMap |
| LIST | List information for all open AppMaps |
| HANDLEID | Return the handle used by this service |
| HELP | Display this help information |
Each instance of the service must be registered via the STAF Service service.
Examples showing comandline registration:
STAF LOCAL SERVICE ADD SERVICE <servicename> LIBRARY JSTAF /
EXECUTE org/safs/staf/service/SAFSAppMapService [PARMS <Parameters>]
SERVICE ADD SERVICE sharedmaps LIBRARY JSTAF EXECUTE org/safs/staf/service/SAFSAppMapService /
SERVICE ADD SERVICE othermaps LIBRARY JSTAF EXECUTE org/safs/staf/service/SAFSAppMapService /
PARMS DIR "c:\repo\Datapool" EXT ".dat" SAFSVARS "ddvariables"
By default, the service expects a "SAFSVARS" SAFSVariableService to handle Variable calls.
1.1 Valid Parameters when registering the 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 do not use system PATH information. The OPEN request expects a
full filename path, or a path relative to this DIR option.
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.
EX: <PARMS> DIR "c:\testrepo\Datapool"
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. By default, the service expects a
default extension of ".map"
EX: <PARMS> EXT ".dat"
1.1.3 SAFSVARS <servicename>
If provided, the SAFSVARS parameter specifies the name of the service that will provide
SAFS Variables to this AppMap service. By default, the service automatically expects
a "SAFSVARS" SAFSVariableService to handle requests.
EX: <PARMS> SAFSVARS "ddvariables"
1.1.4 DISABLECHAIN
The DISABLECHAIN parameter instructs the service to forego the default operation of
searching all open AppMaps when seeking a requested entry.
EX: <PARMS> DISABLECHAIN
1.1.5 DISABLERESOLVE
The DISABLERESOLVE parameter instructs the service to forego the default operation of
resolving DDVariable references embedded in AppMap entries.
EX: <PARMS> DISABLERESOLVE
The OPEN command attempts to open a file for read operations. The AppMap will be added to the top of the list of AppMaps to be searched on subsequent requests for AppMap entries.
Syntax:
OPEN <AppMapID> FILE <Filename> [STORED | MAPPED] [DEFAULTMAP]
2.1.1 AppMapID is a unique ID for this AppMap instance.
2.1.2 FILE is the filename of the AppMap to load.
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 STORED read the app map entirely into memory.
2.1.4 MAPPED use memory mapped file handling and DO NOT load the entire file
into memory. This is for efficiencies when handling very large files.
(This is not yet implemented.)
2.1.5 DEFAULTMAP instructs the service to set this AppMap as the "default" AppMap. By default, the first map opened by the service is automatically set as "default".
The SAFSVARS command is used to read or set the current SAFSVARS setting for the service.
Syntax:
SAFSVARS <no parameter > :returns the current setting, if any
SAFSVARS <servicename> :sets the name of the SAFSVARS service for the AppMap service
to use.
2.2.1 servicename sets the name of the SAFSVARS service to use.
By default, the service expects the "SAFSVARS" service to handle variable resolution.
The DEFAULTMAP command is used to read or set the "default" AppMap setting for the service. By default, the first AppMap opened will be set as "default".
Syntax:
DEFAULTMAP <no parameter > :returns the current setting, if any
DEFAULTMAP <AppMapID> :sets the provided AppMapID as the new "default" AppMap.
2.3.1 AppMapID is the unique ID of the AppMap to set as "default".
The DEFAULTMAPSECTION command is used to read or set the "default" Section with an AppMap.
Syntax:
Note, any time the optional AppMapID is not provided, the current "default" AppMap is assumed. By default, the "ApplicationConstants" section is set as "default" if it exists when the Map is opened.
DEFAULTMAPSECTION [<AppMapID>] returns the current setting.
DEFAULTMAPSECTION [<AppMapID>] SECTION [<section>] sets the provided <section> as
the new "default" Section for the AppMap. An empty value for SECTION sets the unnamed
initial Section in the AppMap as "default".
2.4.1 AppMapID is the ID of the AppMap to reference. If not provided, the "default" AppMap will be used.
2.4.2 SECTION if not provided, the request will be a read operation returning
the current setting. If SECTION is provided, the request sets the the AppMap's "default"
section.
The GETITEM command requests an item stored in an AppMap. The AppMap does NOT have to have been previously opened. However, a call to GETITEM on an unopened AppMap will cause the search to limit its scope to the specified AppMap--the default behavior of searching all open AppMaps will not be honored. In addition, specifying an unopened AppMap will prevent that AppMap from being added to the chain of searchable AppMaps during the current request.
Syntax:
GETITEM [<AppMapID>] [ SECTION [<section> | "DEFAULTMAPSECTION"] ] ITEM <item [ISDYNAMIC]>
2.5.1 AppMapID is the ID of the AppMap to use for lookup. If not provided, the "default" AppMap will be used.
2.5.2 SECTION is the section in the AppMap to use for lookup. If not passed,
then the first, unnamed AppMap section will be used. If you want to reference the
DEFAULTMAPSECTION for the map, the value passed to SECTION should be "DEFAULTMAPSECTION",
including quotes.
2.5.3 ITEM is the name of the item within the section to return.
2.5.4 ISDYNAMIC optional parameter stating whether we should check if the recognition is dynamic
The CLEARCACHE command will clear all cached items in all open AppMaps and cause each stored AppMap to be refreshed. This is generally necessary to reload any changed AppMap without taking down the service.
Syntax:
CLEARCACHE
The CLOSE command closes and releases resources for the AppMap.
Syntax:
CLOSE [ < AppMapID > ]
2.7.1 AppMapID is the ID of the AppMap to close. If not provided, the "default" AppMap will be closed.
The QUERY command returns requested information about an open file.
Syntax:
QUERY [ < AppMapID > ] <MODE | SECTIONS |
ITEMS [ [<section> | "DEFAULTMAPSECTION"] ] | DEFAULTMAPSECTION |
FILENAME | FULLPATH >
2.8.1 AppMapID is the ID of the AppMap to query. If not provided, the DEFAULT AppMap will be used.
2.8.2 MODE returns the STORED or MAPPED memory mode of the AppMap.
2.8.3 SECTIONS returns the list of sections in the AppMap.
2.8.4 ITEMS returns the list of items in a section. If not provided, the items in the
first, unnamed section of the AppMap will be returned. If you want to reference the
DEFAULTMAPSECTION for the map, the value passed to ITEMS should be "DEFAULTMAPSECTION",
including quotes.
2.8.5 DEFAULTMAPSECTION returns the setting for the "default" AppMap section.
2.8.6 FILENAME is the filename to the file without any path information.
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.
The DISABLECHAIN command will prevent the service from searching all open AppMaps when seeking a requested entry. Only the specified AppMap or the DEFAULTMAP will be searched.
Syntax:
DISABLECHAIN
The ENABLECHAIN command will (re)enable the service to search all open AppMaps when seeking a requested entry. This is the default search mode for this feature.
Syntax:
ENABLECHAIN
The DISABLERESOLVE command will prevent the service from resolving embedded DDVariable references in AppMap entries.
Syntax:
DISABLERESOLVE
The ENABLERESOLVE command will (re)enable the service to resolve embedded DDVariable references in AppMap entries. This is the default mode for this feature.
Syntax:
ENABLERESOLVE
The LIST command returns info on each open AppMap for the service.
Syntax:
LIST
Returns the HANDLE associated with the SAFSAppMapService.
Syntax:
HANDLEID
The HELP command returns this syntax information for service requests.
Syntax:
HELP
Software Automation Framework Support (SAFS) http://safsdev.sourceforge.net
Software Testing Automation Framework (STAF) http://staf.sourceforge.net
SAFSAppMapFile| Field Summary | |
|---|---|
protected java.util.Hashtable |
appmaps
|
protected java.util.LinkedList |
chain
|
protected boolean |
chain_enabled
|
protected int |
chain_index
|
protected static com.ibm.staf.STAFHandle |
client
|
protected static int |
clients
|
protected java.lang.String |
defaultdir
|
protected java.lang.String |
defaultext
|
protected java.lang.String |
defaultmap
|
protected boolean |
file_ext_available
|
protected boolean |
honor_chain
|
protected com.ibm.staf.service.STAFCommandParser |
parser
|
protected boolean |
request_get_item
|
protected boolean |
resolve_enabled
|
protected boolean |
root_path_available
|
static java.lang.String |
SAM_CURRENTWINDOW_ITEM
|
static java.lang.String |
SAM_DDV_PREFIX
|
static int |
SAM_DDV_PREFIX_LEN
|
static java.lang.String |
SAM_DEFAULT_EXT
|
static java.lang.String |
SAM_RESOLVE_PREFIX
|
static java.lang.String |
SAM_RESOLVE_SUFFIX
|
int |
SAM_SERVICE_INIT_ARGS_MAX
|
static java.lang.String |
SAM_SERVICE_OPTION_DIR
|
static java.lang.String |
SAM_SERVICE_OPTION_EXT
|
static java.lang.String |
SAM_SERVICE_OPTION_SAFSVARS
|
static java.lang.String |
SAM_SERVICE_PARM_FILE
|
static java.lang.String |
SAM_SERVICE_PARM_FILENAME
|
static java.lang.String |
SAM_SERVICE_PARM_FULLPATH
|
static java.lang.String |
SAM_SERVICE_PARM_ISDYNAMIC
|
static java.lang.String |
SAM_SERVICE_PARM_ITEM
|
static java.lang.String |
SAM_SERVICE_PARM_ITEMS
|
static java.lang.String |
SAM_SERVICE_PARM_MAPPED
|
static java.lang.String |
SAM_SERVICE_PARM_MODE
|
static java.lang.String |
SAM_SERVICE_PARM_SECTION
|
static java.lang.String |
SAM_SERVICE_PARM_SECTIONS
|
static java.lang.String |
SAM_SERVICE_PARM_STORED
|
static java.lang.String |
SAM_SERVICE_PROCESS_NAME
|
int |
SAM_SERVICE_REQUEST_ARGS_MAX
|
static java.lang.String |
SAM_SERVICE_REQUEST_CLEARCACHE
|
static java.lang.String |
SAM_SERVICE_REQUEST_CLOSE
|
static java.lang.String |
SAM_SERVICE_REQUEST_DEFAULTMAP
|
static java.lang.String |
SAM_SERVICE_REQUEST_DEFAULTMAPSECTION
|
static java.lang.String |
SAM_SERVICE_REQUEST_DISABLECHAIN
|
static java.lang.String |
SAM_SERVICE_REQUEST_DISABLERESOLVE
|
static java.lang.String |
SAM_SERVICE_REQUEST_ENABLECHAIN
|
static java.lang.String |
SAM_SERVICE_REQUEST_ENABLERESOLVE
|
static java.lang.String |
SAM_SERVICE_REQUEST_GETITEM
|
static java.lang.String |
SAM_SERVICE_REQUEST_HANDLEID
|
static java.lang.String |
SAM_SERVICE_REQUEST_HELP
|
static java.lang.String |
SAM_SERVICE_REQUEST_LIST
|
static java.lang.String |
SAM_SERVICE_REQUEST_OPEN
|
static java.lang.String |
SAM_SERVICE_REQUEST_QUERY
|
static java.lang.String |
SAM_SERVICE_TAGGED_PREFIX
|
protected boolean |
service_vars_available
|
protected java.lang.String |
servicename
|
protected java.lang.String |
serviceparms
|
protected java.lang.String |
servicevars
|
| Constructor Summary | |
|---|---|
SAFSAppMapService()
Initialize the class, primarily, the parser used to parse service requests. |
|
| Method Summary | |
|---|---|
com.ibm.staf.STAFResult |
acceptRequest(java.lang.String machine,
java.lang.String process,
int handle,
java.lang.String request)
Handle service request from STAF |
protected java.lang.String |
getHELPInfo()
our HELP text |
int |
init(java.lang.String name,
java.lang.String params)
Handle initializing this instance of the service for STAF |
int |
term()
Handle the request to shutdown the service from STAF |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public int SAM_SERVICE_REQUEST_ARGS_MAX
public int SAM_SERVICE_INIT_ARGS_MAX
public static final java.lang.String SAM_SERVICE_OPTION_DIR
public static final java.lang.String SAM_SERVICE_OPTION_EXT
public static final java.lang.String SAM_SERVICE_OPTION_SAFSVARS
public static final java.lang.String SAM_SERVICE_PROCESS_NAME
public static final java.lang.String SAM_SERVICE_REQUEST_HANDLEID
public static final java.lang.String SAM_SERVICE_REQUEST_OPEN
public static final java.lang.String SAM_SERVICE_REQUEST_GETITEM
public static final java.lang.String SAM_SERVICE_REQUEST_CLEARCACHE
public static final java.lang.String SAM_SERVICE_REQUEST_DISABLECHAIN
public static final java.lang.String SAM_SERVICE_REQUEST_ENABLECHAIN
public static final java.lang.String SAM_SERVICE_REQUEST_DISABLERESOLVE
public static final java.lang.String SAM_SERVICE_REQUEST_ENABLERESOLVE
public static final java.lang.String SAM_SERVICE_REQUEST_LIST
public static final java.lang.String SAM_SERVICE_REQUEST_QUERY
public static final java.lang.String SAM_SERVICE_REQUEST_HELP
public static final java.lang.String SAM_SERVICE_REQUEST_CLOSE
public static final java.lang.String SAM_SERVICE_REQUEST_DEFAULTMAP
public static final java.lang.String SAM_SERVICE_REQUEST_DEFAULTMAPSECTION
public static final java.lang.String SAM_SERVICE_PARM_FILE
public static final java.lang.String SAM_SERVICE_PARM_STORED
public static final java.lang.String SAM_SERVICE_PARM_MAPPED
public static final java.lang.String SAM_SERVICE_PARM_SECTION
public static final java.lang.String SAM_SERVICE_PARM_ITEM
public static final java.lang.String SAM_SERVICE_PARM_ISDYNAMIC
public static final java.lang.String SAM_SERVICE_TAGGED_PREFIX
public static final java.lang.String SAM_SERVICE_PARM_MODE
public static final java.lang.String SAM_SERVICE_PARM_SECTIONS
public static final java.lang.String SAM_SERVICE_PARM_ITEMS
public static final java.lang.String SAM_SERVICE_PARM_FILENAME
public static final java.lang.String SAM_SERVICE_PARM_FULLPATH
public static final java.lang.String SAM_DDV_PREFIX
public static final java.lang.String SAM_RESOLVE_PREFIX
public static final java.lang.String SAM_RESOLVE_SUFFIX
public static final java.lang.String SAM_CURRENTWINDOW_ITEM
public static final int SAM_DDV_PREFIX_LEN
public static final java.lang.String SAM_DEFAULT_EXT
protected java.util.Hashtable appmaps
protected java.util.LinkedList chain
protected boolean chain_enabled
protected boolean honor_chain
protected int chain_index
protected boolean request_get_item
protected boolean resolve_enabled
protected com.ibm.staf.service.STAFCommandParser parser
protected java.lang.String defaultdir
protected java.lang.String defaultext
protected java.lang.String defaultmap
protected java.lang.String servicevars
protected java.lang.String servicename
protected java.lang.String serviceparms
protected boolean root_path_available
protected boolean file_ext_available
protected boolean service_vars_available
protected static int clients
protected static com.ibm.staf.STAFHandle client
| Constructor Detail |
|---|
public SAFSAppMapService()
| Method Detail |
|---|
protected java.lang.String getHELPInfo()
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.STAFServiceInterfaceLevel1public final int term()
term in interface com.ibm.staf.service.STAFServiceInterfaceLevel1
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||