org.safs.staf.service
Class SAFSAppMapService

java.lang.Object
  extended by org.safs.staf.service.SAFSAppMapService
All Implemented Interfaces:
com.ibm.staf.service.STAFServiceInterfaceLevel1

public class SAFSAppMapService
extends java.lang.Object
implements com.ibm.staf.service.STAFServiceInterfaceLevel1

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:

  1. look for ITEM in SECTION as provided
  2. not found? look for ITEM in the "default" SECTION
  3. not found? look for ITEM in empty, unnamed section

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

1.0 Service Registration

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

2.0 Commands

2.1 OPEN

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".

2.2 SAFSVARS

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.

2.3 DEFAULTMAP

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".

2.4 DEFAULTMAPSECTION

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.

2.5 GETITEM

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

2.6 CLEARCACHE

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

2.7 CLOSE

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.

2.8 QUERY

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.

2.9 DISABLECHAIN

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

2.10 ENABLECHAIN

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

2.11 DISABLERESOLVE

The DISABLERESOLVE command will prevent the service from resolving embedded DDVariable references in AppMap entries.

Syntax:

DISABLERESOLVE

2.12 ENABLERESOLVE

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

2.13 LIST

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

Syntax:

LIST

2.14 HANDLEID

Returns the HANDLE associated with the SAFSAppMapService.

Syntax:

HANDLEID

2.15 HELP

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

See Also:
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

SAM_SERVICE_REQUEST_ARGS_MAX

public int SAM_SERVICE_REQUEST_ARGS_MAX

SAM_SERVICE_INIT_ARGS_MAX

public int SAM_SERVICE_INIT_ARGS_MAX

SAM_SERVICE_OPTION_DIR

public static final java.lang.String SAM_SERVICE_OPTION_DIR
See Also:
Constant Field Values

SAM_SERVICE_OPTION_EXT

public static final java.lang.String SAM_SERVICE_OPTION_EXT
See Also:
Constant Field Values

SAM_SERVICE_OPTION_SAFSVARS

public static final java.lang.String SAM_SERVICE_OPTION_SAFSVARS
See Also:
Constant Field Values

SAM_SERVICE_PROCESS_NAME

public static final java.lang.String SAM_SERVICE_PROCESS_NAME
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_HANDLEID

public static final java.lang.String SAM_SERVICE_REQUEST_HANDLEID
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_OPEN

public static final java.lang.String SAM_SERVICE_REQUEST_OPEN
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_GETITEM

public static final java.lang.String SAM_SERVICE_REQUEST_GETITEM
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_CLEARCACHE

public static final java.lang.String SAM_SERVICE_REQUEST_CLEARCACHE
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_DISABLECHAIN

public static final java.lang.String SAM_SERVICE_REQUEST_DISABLECHAIN
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_ENABLECHAIN

public static final java.lang.String SAM_SERVICE_REQUEST_ENABLECHAIN
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_DISABLERESOLVE

public static final java.lang.String SAM_SERVICE_REQUEST_DISABLERESOLVE
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_ENABLERESOLVE

public static final java.lang.String SAM_SERVICE_REQUEST_ENABLERESOLVE
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_LIST

public static final java.lang.String SAM_SERVICE_REQUEST_LIST
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_QUERY

public static final java.lang.String SAM_SERVICE_REQUEST_QUERY
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_HELP

public static final java.lang.String SAM_SERVICE_REQUEST_HELP
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_CLOSE

public static final java.lang.String SAM_SERVICE_REQUEST_CLOSE
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_DEFAULTMAP

public static final java.lang.String SAM_SERVICE_REQUEST_DEFAULTMAP
See Also:
Constant Field Values

SAM_SERVICE_REQUEST_DEFAULTMAPSECTION

public static final java.lang.String SAM_SERVICE_REQUEST_DEFAULTMAPSECTION
See Also:
Constant Field Values

SAM_SERVICE_PARM_FILE

public static final java.lang.String SAM_SERVICE_PARM_FILE
See Also:
Constant Field Values

SAM_SERVICE_PARM_STORED

public static final java.lang.String SAM_SERVICE_PARM_STORED
See Also:
Constant Field Values

SAM_SERVICE_PARM_MAPPED

public static final java.lang.String SAM_SERVICE_PARM_MAPPED
See Also:
Constant Field Values

SAM_SERVICE_PARM_SECTION

public static final java.lang.String SAM_SERVICE_PARM_SECTION
See Also:
Constant Field Values

SAM_SERVICE_PARM_ITEM

public static final java.lang.String SAM_SERVICE_PARM_ITEM
See Also:
Constant Field Values

SAM_SERVICE_PARM_ISDYNAMIC

public static final java.lang.String SAM_SERVICE_PARM_ISDYNAMIC
See Also:
Constant Field Values

SAM_SERVICE_TAGGED_PREFIX

public static final java.lang.String SAM_SERVICE_TAGGED_PREFIX
See Also:
Constant Field Values

SAM_SERVICE_PARM_MODE

public static final java.lang.String SAM_SERVICE_PARM_MODE
See Also:
Constant Field Values

SAM_SERVICE_PARM_SECTIONS

public static final java.lang.String SAM_SERVICE_PARM_SECTIONS
See Also:
Constant Field Values

SAM_SERVICE_PARM_ITEMS

public static final java.lang.String SAM_SERVICE_PARM_ITEMS
See Also:
Constant Field Values

SAM_SERVICE_PARM_FILENAME

public static final java.lang.String SAM_SERVICE_PARM_FILENAME
See Also:
Constant Field Values

SAM_SERVICE_PARM_FULLPATH

public static final java.lang.String SAM_SERVICE_PARM_FULLPATH
See Also:
Constant Field Values

SAM_DDV_PREFIX

public static final java.lang.String SAM_DDV_PREFIX
See Also:
Constant Field Values

SAM_RESOLVE_PREFIX

public static final java.lang.String SAM_RESOLVE_PREFIX
See Also:
Constant Field Values

SAM_RESOLVE_SUFFIX

public static final java.lang.String SAM_RESOLVE_SUFFIX
See Also:
Constant Field Values

SAM_CURRENTWINDOW_ITEM

public static final java.lang.String SAM_CURRENTWINDOW_ITEM
See Also:
Constant Field Values

SAM_DDV_PREFIX_LEN

public static final int SAM_DDV_PREFIX_LEN
See Also:
Constant Field Values

SAM_DEFAULT_EXT

public static final java.lang.String SAM_DEFAULT_EXT
See Also:
Constant Field Values

appmaps

protected java.util.Hashtable appmaps

chain

protected java.util.LinkedList chain

chain_enabled

protected boolean chain_enabled

honor_chain

protected boolean honor_chain

chain_index

protected int chain_index

request_get_item

protected boolean request_get_item

resolve_enabled

protected boolean resolve_enabled

parser

protected com.ibm.staf.service.STAFCommandParser parser

defaultdir

protected java.lang.String defaultdir

defaultext

protected java.lang.String defaultext

defaultmap

protected java.lang.String defaultmap

servicevars

protected java.lang.String servicevars

servicename

protected java.lang.String servicename

serviceparms

protected java.lang.String serviceparms

root_path_available

protected boolean root_path_available

file_ext_available

protected boolean file_ext_available

service_vars_available

protected boolean service_vars_available

clients

protected static int clients

client

protected static com.ibm.staf.STAFHandle client
Constructor Detail

SAFSAppMapService

public SAFSAppMapService()
Initialize the class, primarily, the parser used to parse service requests.

Method Detail

getHELPInfo

protected java.lang.String getHELPInfo()
our HELP text


init

public final int init(java.lang.String name,
                      java.lang.String params)
Handle initializing this instance of the service for STAF

Specified by:
init in interface com.ibm.staf.service.STAFServiceInterfaceLevel1

acceptRequest

public final com.ibm.staf.STAFResult acceptRequest(java.lang.String machine,
                                                   java.lang.String process,
                                                   int handle,
                                                   java.lang.String request)
Handle service request from STAF

Specified by:
acceptRequest in interface com.ibm.staf.service.STAFServiceInterfaceLevel1

term

public final int term()
Handle the request to shutdown the service from STAF

Specified by:
term in interface com.ibm.staf.service.STAFServiceInterfaceLevel1