org.safs.staf.service.var

Class AbstractSAFSVariableService

java.lang.Object

org.safs.staf.service.var.AbstractSAFSVariableService

All Implemented Interfaces:

SimpleVarsInterface

Direct Known Subclasses:

EmbeddedVariableService, SAFSVariableService, SAFSVariableService3

public abstract class AbstractSAFSVariableService
extends java.lang.Object
implements SimpleVarsInterface

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

This SAFSVariablesService class is an external STAF service run by the JSTAF Service Proxy.
This acts as a SAFS-aware wrapper for the STAF Variables service.

In a true SAFS environment, Variables (DDVariables) are nearly always tightly integrated with the centralized AppMap service. 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.

Thus, in a single request for a variable or AppMap value, the search can ping back and forth between Variable and AppMap services until the request is satisfied or we have exhausted the search chain.

Another important issue is that SAFS variables use a different syntax for identifying variables:

• STAF Variable Syntax: {MyVariable}
• SAFS Variable Syntax: ^MyVariable

Lastly(?), the RESOLVE command will have to process the EXPRESSIONS supported by SAFS.

Oh, additionally, SAFS variable names are not case-sensitive.

The SAFSVariablesService service provides the following commands:

SAFSMAPS	Get/Set the associated AppMap service name
HANDLEID	Return the handle used by this service
SET	Set a variable value
GET	Get a variable value
LIST	Retrieves the list of all variables/values
RESET	Reset and clear all storage--delete everything.
RESOLVE	Resolve variables and expressions in a string.
DELETE	Delete a variable
COUNT	Return the count of variables currently stored
HELP	Get HELP on command syntax.

1.0 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/SAFSVariablesService [PARMS <Parameters>]

 SERVICE ADD SERVICE safsvars LIBRARY JSTAF EXECUTE org/safs/staf/service/SAFSVariablesService /
                              PARMS SAFSMAPS "altMapService"
 

By default, the service expects a default "SAFSMAPS" SAFSAppMapService to handle AppMap calls.

1.1 Valid Parameters when registering the service:

1.1.1 SAFSMAPS <servicename>
The SAFSMAPS parameter specifies the name of the service that will provide SAFS AppMap services to this Variables service. If not provided, the Variables service expects a "SAFSMAPS" service to handle requests.

EX: <PARMS> SAFSMAPS "altMapService"

2.0 Commands

2.1 SAFSMAPS

Get or Set the name of the SAFSMAPS service handling AppMap requests for variable resolution.

Syntax:

SAFSMAPS <no parameter> - returns the current SAFSMAPS setting.
SAFSMAPS <servicename> - sets an alternate AppMap service.

2.1.1 <servicename> is the name of an alternate SAFSAppMapService to associate for variables resolution. By default, thes "SAFSMAPS" service is used.

2.2 HANDLEID

Returns the HANDLE associated with the SAFSVariableService.

Syntax:

HANDLEID

2.3 SET

Sets the value of a SAFS variable.

Syntax:

SET <name> VALUE <value>

2.3.1 <name> the name of the variable to "set"

2.3.2 <value> the value to assign the variable

2.4 GET

Returns the value of a SAFS variable.

Syntax:

GET <name>

2.4.1 <<name> the name of the variable to resolve

2.5 DELETE

Delete a variable from storage.

Syntax:

DELETE <name>

2.5.1 <name> the name of the variable to delete

2.6 LIST

The LIST command returns the name and value of each variable known to the service.
This could include STAF VAR variables not necessarily seen in SAFSVARS.

Syntax:

LIST [V2]

2.6.1 V2 - an optional flag used to return the list in original STAF V2 format instead of newer STAF V3 marshaled data format. The V3 format is returned by default when using STAF V3.

2.7 COUNT

The COUNT command returns the count of variables currently stored.

Syntax:

COUNT

2.8 RESET

When implemented, this will reset (DELETE) all stored variables

Syntax:

RESET

2.9 RESOLVE

This will resolve variable values and SAFS expressions in a multi-field, delimited string (a test record). Returns the input strings in a RC:STRING format. The RC is a numeric STAF return code -- hopefully 0 (Ok). Followed by a colon(:), then the actual processed test record.

Syntax:

RESOLVE <string> [SEPARATOR <char>] [NOEXPRESSIONS]

2.9.1 <string> the string (input record) to process for variables and expressions. Note, if the CARET (^) identifying a DDVariable cannot be sent intact the service will accept the string "_DDV_" in place of each intended CARET character and convert it internally before processing.

2.9.2 SEPARATOR <char> an optional single character to use as the field delimiter when processing the input string or record as separate fields, left to right.

2.9.3 NOEXPRESSIONS an optional value to indicate how the input record will have the variables and expressions processed. By default, Expressions are assumed ON. With NOEXPRESSIONS, the input record is handled in the older Substitute/Extract method: only the setting and getting of individual variable values occurs.

2.10 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

Author:

Carl Nagle JUL 03, 2003 Moved initialization into init, out of constructor., Carl Nagle SEP 26, 2007 Fixed App Map Resolve problem with explicit ApplicationConstants section, Carl Nagle MAR 19, 2009 Fixed problem with quoting of already quoted strings., JunwuMa MAY 12, 2009 Adding support for STAF3. Renamed SAFSVariableService (old class only for STAF2) with AbstractSAFSVariableService and keep common operations in it. Two different versions of the service extend this class for supporting STAF2 and STAF3., Carl Nagle JUN 04, 2009 Synchronizing for Thread Safety., Carl Nagle FEB 04, 2010 Attempt to catch and ignore individual field expression processing errors., Lei Wang APR 05, 2012 Add option "MAPVARLOOP" for command "GET", see Testhelp078350, Carl Nagle JUL 22, 2013 Allow SAFSVARS LIST to return V2 format.

See Also:

SAFSVariableService3 SAFSAppMapService SAFSAppMapService3

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	c
protected HandleInterface	client
protected static java.lang.String	dq
protected static java.lang.String	empty
protected static java.lang.String	eq
protected SafsExpression	exp
protected com.ibm.staf.service.STAFCommandParser	parser
protected static java.lang.String	q
protected static java.lang.String	r
protected static java.lang.String	s
protected boolean	service_maps_available
protected java.lang.String	servicemaps
protected java.lang.String	servicename
protected java.lang.String	serviceparms
static java.lang.String	SVS_CARET
static java.lang.String	SVS_FALSE_CARET
int	SVS_SERVICE_INIT_ARGS_MAX
static java.lang.String	SVS_SERVICE_PARM_MAP_VAR_LOOP Used for SVS_SERVICE_REQUEST_GET Used internally to stop the loop between map service and variable service. "MAPVARLOOP" can have parameter, a delimited string, the items have been processed in map service.
static java.lang.String	SVS_SERVICE_PROCESS_NAME
int	SVS_SERVICE_REQUEST_ARGS_MAX
static java.lang.String	SVS_SERVICE_REQUEST_COUNT
static java.lang.String	SVS_SERVICE_REQUEST_DELETE
static java.lang.String	SVS_SERVICE_REQUEST_GET
static java.lang.String	SVS_SERVICE_REQUEST_HANDLEID
static java.lang.String	SVS_SERVICE_REQUEST_HELP
static java.lang.String	SVS_SERVICE_REQUEST_LIST
static java.lang.String	SVS_SERVICE_REQUEST_NOEXPRESSIONS
static java.lang.String	SVS_SERVICE_REQUEST_RESET
static java.lang.String	SVS_SERVICE_REQUEST_RESOLVE
static java.lang.String	SVS_SERVICE_REQUEST_SAFSMAPS
static java.lang.String	SVS_SERVICE_REQUEST_SEPARATOR
static java.lang.String	SVS_SERVICE_REQUEST_SET
static java.lang.String	SVS_SERVICE_REQUEST_V2
static java.lang.String	SVS_SERVICE_REQUEST_VALUE
protected com.ibm.staf.STAFResult	tempresult Shared by various methods and actually causes thread-safety issues if not properly synchronized when multiple processes are using the active service! Carl Nagle 2009.06.04

Constructor Summary

Constructors

Constructor and Description
AbstractSAFSVariableService() Initialize the class, primarily, the parser used to parse service requests.

Method Summary

Modifier and Type	Method and Description
protected com.ibm.staf.STAFResult	deleteStoredVariable(java.lang.String deleteCmd) Made to be overridden by subclasses, if any.
protected com.ibm.staf.STAFResult	doAcceptRequest(java.lang.String request) Handle service request from STAF
protected int	doInit(HandleInterface client, java.lang.String name, java.lang.String params) Handle initializing this instance of the service for STAF
protected java.lang.String	getHELPInfo() our HELP text
protected com.ibm.staf.STAFResult	getStoredValue(java.lang.String getCmd) Made to be overridden by subclasses, if any.
java.lang.String	getValue(java.lang.String varname) Get the value of a named variable.
protected com.ibm.staf.STAFResult	handleCount()
protected com.ibm.staf.STAFResult	handleList(com.ibm.staf.service.STAFCommandParseResult parsedData)
protected com.ibm.staf.STAFResult	handleReset()
protected com.ibm.staf.STAFResult	setStoredValue(java.lang.String setCmd) Made to be overridden by subclasses, if any.
java.lang.String	setValue(java.lang.String varname, java.lang.String varvalue) tempresult must be externally synchronized by caller!
protected java.lang.String	smartQuoteField(java.lang.String field) Only quote the field if it is not already quoted.
protected java.lang.String	stafDeleteCommand(java.lang.String varname)
protected java.lang.String	stafGetCommmd(java.lang.String varname)
protected java.lang.String	stafListCommand()
protected java.lang.String	stafSetCommmd(java.lang.String assignExp)

Methods inherited from class java.lang.Object

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

Field Detail

SVS_SERVICE_REQUEST_ARGS_MAX

public int SVS_SERVICE_REQUEST_ARGS_MAX

SVS_SERVICE_INIT_ARGS_MAX

public int SVS_SERVICE_INIT_ARGS_MAX

SVS_SERVICE_PROCESS_NAME

public static final java.lang.String SVS_SERVICE_PROCESS_NAME

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_SAFSMAPS

public static final java.lang.String SVS_SERVICE_REQUEST_SAFSMAPS

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_HANDLEID

public static final java.lang.String SVS_SERVICE_REQUEST_HANDLEID

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_COUNT

public static final java.lang.String SVS_SERVICE_REQUEST_COUNT

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_GET

public static final java.lang.String SVS_SERVICE_REQUEST_GET

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_SET

public static final java.lang.String SVS_SERVICE_REQUEST_SET

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_VALUE

public static final java.lang.String SVS_SERVICE_REQUEST_VALUE

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_LIST

public static final java.lang.String SVS_SERVICE_REQUEST_LIST

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_RESET

public static final java.lang.String SVS_SERVICE_REQUEST_RESET

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_RESOLVE

public static final java.lang.String SVS_SERVICE_REQUEST_RESOLVE

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_SEPARATOR

public static final java.lang.String SVS_SERVICE_REQUEST_SEPARATOR

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_NOEXPRESSIONS

public static final java.lang.String SVS_SERVICE_REQUEST_NOEXPRESSIONS

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_DELETE

public static final java.lang.String SVS_SERVICE_REQUEST_DELETE

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_HELP

public static final java.lang.String SVS_SERVICE_REQUEST_HELP

See Also:

Constant Field Values

SVS_SERVICE_REQUEST_V2

public static final java.lang.String SVS_SERVICE_REQUEST_V2

See Also:

Constant Field Values

SVS_SERVICE_PARM_MAP_VAR_LOOP

public static final java.lang.String SVS_SERVICE_PARM_MAP_VAR_LOOP

Used for SVS_SERVICE_REQUEST_GET
Used internally to stop the loop between map service and variable service.
"MAPVARLOOP" can have parameter, a delimited string, the items have been processed
in map service. The delimiter is
Example:
MAPVARLOOP item1_SEP:item2_SEP:item3

See Also:

getValue(String, boolean, String), Constant Field Values

SVS_CARET

public static final java.lang.String SVS_CARET

See Also:

Constant Field Values

SVS_FALSE_CARET

public static final java.lang.String SVS_FALSE_CARET

See Also:

Constant Field Values

parser

protected com.ibm.staf.service.STAFCommandParser parser

servicemaps

protected java.lang.String servicemaps

servicename

protected java.lang.String servicename

serviceparms

protected java.lang.String serviceparms

service_maps_available

protected boolean service_maps_available

client

protected HandleInterface client

empty

protected static java.lang.String empty

c

protected static java.lang.String c

s

protected static java.lang.String s

r

protected static java.lang.String r

eq

protected static java.lang.String eq

q

protected static java.lang.String q

dq

protected static java.lang.String dq

exp

protected SafsExpression exp

tempresult

protected com.ibm.staf.STAFResult tempresult

Shared by various methods and actually causes thread-safety issues if not properly synchronized when multiple processes are using the active service! Carl Nagle 2009.06.04

Constructor Detail

AbstractSAFSVariableService

public AbstractSAFSVariableService()

Initialize the class, primarily, the parser used to parse service requests.

Method Detail

getHELPInfo

protected java.lang.String getHELPInfo()

our HELP text

doInit

protected int doInit(HandleInterface client,
                     java.lang.String name,
                     java.lang.String params)

Handle initializing this instance of the service for STAF

doAcceptRequest

protected com.ibm.staf.STAFResult doAcceptRequest(java.lang.String request)

Handle service request from STAF

deleteStoredVariable

protected com.ibm.staf.STAFResult deleteStoredVariable(java.lang.String deleteCmd)

Made to be overridden by subclasses, if any.

Parameters:

deleteCmd -

Returns:

STAFResult

getStoredValue

protected com.ibm.staf.STAFResult getStoredValue(java.lang.String getCmd)

Made to be overridden by subclasses, if any.

Parameters:

getCmd -

Returns:

STAFResult

setStoredValue

protected com.ibm.staf.STAFResult setStoredValue(java.lang.String setCmd)

Made to be overridden by subclasses, if any.

Parameters:

setCmd -

Returns:

STAFResult

getValue

public final java.lang.String getValue(java.lang.String varname)

Description copied from interface: SimpleVarsInterface

Get the value of a named variable.

Specified by:

getValue in interface SimpleVarsInterface

Returns:

the current value of the variable, or an empty string.

See Also:

SimpleVarsInterface.getValue(String), #getValue(String, boolean)

setValue

public java.lang.String setValue(java.lang.String varname,
                                 java.lang.String varvalue)

tempresult must be externally synchronized by caller!

Specified by:

setValue in interface SimpleVarsInterface

Returns:

the value as retrieved from the variable after it was set.

See Also:

SimpleVarsInterface.setValue(String, String)

stafGetCommmd

protected java.lang.String stafGetCommmd(java.lang.String varname)

stafSetCommmd

protected java.lang.String stafSetCommmd(java.lang.String assignExp)

stafDeleteCommand

protected java.lang.String stafDeleteCommand(java.lang.String varname)

stafListCommand

protected java.lang.String stafListCommand()

handleCount

protected com.ibm.staf.STAFResult handleCount()

handleReset

protected com.ibm.staf.STAFResult handleReset()

handleList

protected com.ibm.staf.STAFResult handleList(com.ibm.staf.service.STAFCommandParseResult parsedData)

smartQuoteField

protected java.lang.String smartQuoteField(java.lang.String field)

Only quote the field if it is not already quoted.

Parameters:

field - to quote, if necessary

Returns:

quoted field, or field unmodified.