org.safs
Class STAFHelper

java.lang.Object
  org.safs.STAFHelper

Direct Known Subclasses:

SingletonSTAFHelper

public class STAFHelper
extends java.lang.Object

Purpose: a wrapper class for the STAFHandle, includes some common functionality used many places associated with the SAFSVARS and SAFSMAPS

Since:

JUN 24, 2003
JUN 24, 2003 (DBauman) Original Release
JUN 26, 2003 (CANAGL) Added getInitializedHelper and some constants.
JUN 30, 2003 (BAUMAN) Separated out Singleton code to SingletonSTAFHelper.
JUN 30, 2003 (CANAGL) Added additional convenience constructor and made the function lentag... public.
AUG 11, 2003 (DBAUMAN) added a Pause component function (delay too); adding debug statements in order to figure out how to add recog. strings to the appmap for custom components.
AUG 19, 2003 (DBAUMAN) getAppMapNames added so that we can set the test record's appmapname with the current loaded appmap.
SEP 05, 2003 (DBAUMAN) changed the wait so that RobotJ never times out (it must be instructed to stop).
SEP 12, 2003 (CANAGL) Added SAFSLOGS service data.
NOV 09, 2003 (CANAGL) Adding support for multiple different engine hooks.
NOV 10, 2003 (CANAGL) Capture process/hook name used to create an instance.
APR 06, 2004 (CANAGL) Corrected problems with SAFSLOGS service not being recognized.
JUN 07, 2004 (CANAGL) Added isServiceAvailable to compliment isToolAvailable.
JUN 17, 2004 (CANAGL) Added SAFSINPUT as a predefined tool.
JUN 28, 2004 (CANAGL) Added postNextTestEvent to compliment getNextTestEvent.
Added set\getSAFSTestRecordData.
OCT 31, 2004 (CANAGL) Catch infinite loop in sendQueueMessage.
DEC 07, 2004 (CANAGL) Fixed setHookTestResult and added Results event timeout.
APR 22, 2005 (CANAGL) Enhanced ordering of initialize.
MAY 11, 2005 (CANAGL) Added missing SEM Event "Shutdown" in resetHookEvents.
JUL 25, 2005 (CANAGL) Changed Results event timeout from 3 seconds to 12 seconds.
JUL 27, 2005 (CANAGL) Added submit2WithVar for STAF submits writing results to SAFSVARS.
NOV 15, 2005 (bolawl) Added support for new TRD statusinfo field (RJL).
AUG 04, 2006 (canagl) setVariable and getAppMapItem modified to accept legal null or empty values.
MAY 18, 2009 (JunwuMa) Adding support for STAF3.
JUN 12, 2009 (JunwuMa) Added methods to centralize staf.submit and staf.sbumit2 calls into this class. Added method submit2ForFormatUnchangedService() for using only to call the unchangeable format services. Lower the accessibility of submit() and submit2() from public to protected.
JUN 15, 2009 (CANAGL) Fixed QUEUE message service STAFExceptions with STAF V3.
JUN 16, 2009 (LeiWang) Modify method sendQueueMessage(): If STAFException occur, try again.
JUL 28, 2009 (CANAGL) Added some waits\checks for shutdown operations.

Field Summary

protected static java.lang.reflect.Field	getQueueMessageField
static java.lang.String	LOCAL_MACHINE the normal "local" machine setting used by STAF
static java.lang.String	ROBOTJ_EVENT_DISPATCH "SAFS/RobotJDispatch"
static java.lang.String	ROBOTJ_EVENT_DONE "SAFS/RobotJDone"
static java.lang.String	ROBOTJ_EVENT_READY "SAFS/RobotJReady"
static java.lang.String	ROBOTJ_EVENT_RESULTS "SAFS/RobotJResults"
static java.lang.String	ROBOTJ_EVENT_RUNNING "SAFS/RobotJRunning"
static java.lang.String	ROBOTJ_EVENT_SHUTDOWN "SAFS/RobotJShutdown"
static java.lang.String	ROBOTJ_EVENT_START "SAFS/RobotJStart"
static java.lang.String	SAFS_ABBOT_PROCESS "SAFS/Abbot"
static java.lang.String	SAFS_ABBOT_PROCESS_ID "SAFS/AbbotID"
static java.lang.String	SAFS_APPMAP_SERVICE "SAFSMAPS"
static java.lang.String	SAFS_CLASSIC_PROCESS "SAFS/RobotClassic"
static java.lang.String	SAFS_CLASSIC_PROCESS_ID "SAFS/RobotClassicID"
static java.lang.String	SAFS_CYCLE_TRD "SAFS/CYCLE/" trd root
static java.lang.String	SAFS_EVENT_DISPATCH "Dispatch"
static java.lang.String	SAFS_EVENT_DONE "Done"
static java.lang.String	SAFS_EVENT_READY "Ready"
static java.lang.String	SAFS_EVENT_RESULTS "Results"
static java.lang.String	SAFS_EVENT_RUNNING "Running"
static java.lang.String	SAFS_EVENT_SHUTDOWN "Shutdown"
static java.lang.String	SAFS_EVENT_START "Start"
static java.lang.String	SAFS_GENERIC_PROCESS "SAFS/Process"
static java.lang.String	SAFS_GENERIC_PROCESS_ID "SAFS/ProcessID"
static java.lang.String	SAFS_HOOK_TRD "SAFS/HOOK/" trd root
static java.lang.String	SAFS_HOOK_TRD_MUTEX "SAFS/Hook/TRD", Mutex for ALL applications and processes wishing to use SAFS/Hook/TRD data
static java.lang.String	SAFS_INPUT_PROCESS "SAFSInputService"
static java.lang.String	SAFS_INPUT_SERVICE "SAFSINPUT"
static java.lang.String	SAFS_LOGGING_SERVICE "SAFSLOGS"
static java.lang.String	SAFS_LOGGINGLOG_SERVICE
static java.lang.String	SAFS_ROBOTJ_PROCESS "SAFS/RobotJ"
static java.lang.String	SAFS_ROBOTJ_PROCESS_ID "SAFS/RobotJID"
static java.lang.String	SAFS_SAFSLOGS_PROCESS "STAF/Service/SAFSLOGS"
static java.lang.String	SAFS_SAFSMAPS_PROCESS "SAFSAppMapService"
static java.lang.String	SAFS_SAFSVARS_PROCESS "SAFSVariableService"
static java.lang.String	SAFS_STEP_TRD "SAFS/STEP/" trd root
static java.lang.String	SAFS_SUITE_TRD "SAFS/SUITE/" trd root
static java.lang.String	SAFS_VAR_APPMAPNAME ".../appmapname"
static java.lang.String	SAFS_VAR_BENCHDIRECTORY 7 initial preset variables
static java.lang.String	SAFS_VAR_DATAPOOLDIRECTORY
static java.lang.String	SAFS_VAR_DIFDIRECTORY
static java.lang.String	SAFS_VAR_FAC ".../fac"
static java.lang.String	SAFS_VAR_FILENAME ".../filename"
static java.lang.String	SAFS_VAR_INPUTRECORD ".../inputrecord"
static java.lang.String	SAFS_VAR_LINENUMBER ".../linenumber"
static java.lang.String	SAFS_VAR_LOGSDIRECTORY
static java.lang.String	SAFS_VAR_PROJECTDIRECTORY
static java.lang.String	SAFS_VAR_ROOTVERIFYDIRECTORY
static java.lang.String	SAFS_VAR_RUNTIMEREPOSITORY
static java.lang.String	SAFS_VAR_SEPARATOR ".../separator"
static java.lang.String	SAFS_VAR_STATUSCODE ".../statuscode"
static java.lang.String	SAFS_VAR_STATUSINFO ".../statusinfo"
static java.lang.String	SAFS_VAR_SYSTEMUSERID
static java.lang.String	SAFS_VAR_TESTDIRECTORY
static java.lang.String	SAFS_VAR_TESTLEVEL ".../testlevel"
static java.lang.String	SAFS_VARIABLE_SERVICE "SAFSVARS"
static java.lang.String	STAF_DELAY_SERVICE
static java.lang.String	STAF_GLOBALVARS_VERSION
static java.lang.String	STAF_SERVICELOADER_V2 "STAF/Service/STAF/ServiceLoader"
static java.lang.String	STAF_SERVICELOADER_V3 "STAF/Service/STAFServiceLoader"
protected static java.lang.Class	STAFQueueMessageClass

Constructor Summary

STAFHelper()

Purpose: constructor, must be 'initialized' by the user.

STAFHelper(java.lang.String processName)

Purpose: constructor that also initializes with the given processName.

Method Summary

com.ibm.staf.STAFResult	addService(java.lang.String machine, java.lang.String servicename, java.lang.String classpath, java.lang.String dir, java.lang.String options) add and launch standard SAFS services SAFSINPUT, SAFSMAPS and SAFSLOG
com.ibm.staf.STAFResult	addServiceSAFSVARS(java.lang.String machine, java.lang.String servicename, java.lang.String classpath, java.lang.String mapService, java.lang.String options) add and launch standard SAFS service, SAFSVARS.
boolean	delay(int millisec) Purpose: delay number of milliseconds Side Effects: uses STAF delay service Assumptions: STAF loaded
java.lang.String	getAppMapItem(java.lang.String appMapID, java.lang.String section, java.lang.String item) Purpose: getitem from safsmaps using STAF format used: " getitem "+appMapID+" SECTION "+section+" Item "+item + ""; example: staf local safsmaps getitem "classicc" SECTION "LoginWindow" Item "OKButton" Side Effects: STAF is accessed (safsmaps service) State Read: field 'handle' Assumptions: we are using the SAFSMAPS SERVICE registered in STAF note that currently after each value there are quotes.
java.lang.String	getAppMapItem(java.lang.String appMapID, java.lang.String section, java.lang.String item, boolean isDynamic) Purpose: getitem from safsmaps using STAF, and check if the item has a static recognition string.
java.util.Collection	getAppMapNames() Purpose: get collection of appmap names Assumptions: output of this command: staf local safsmaps list looks like: safsmaps:LIST:2 c:\cycletest\datapool\dealapp.map:C:\CycleTest\Datapool\DealApp.MAP deal:C:\CycleTest\Datapool\DealApp.map
com.ibm.staf.STAFHandle	getHandle() get the handle.
int	getHandleNumber() get the handle's number
java.lang.String	getLogName()
java.lang.String	getMachine() get the current value of 'machine'
java.lang.String	getNextHookTestEvent(java.lang.String process_name, java.lang.String trd_name) Perform the complete engine-side protocol for processinga test record dispatched from a driver.
java.lang.String	getNextTestEvent() getNextTestEvent:
java.lang.String	getProcessName() the String name of the process/hook used at construction
java.lang.String	getQueueMessage(java.lang.String name, java.lang.Integer waitTime) Purpose: get a queue message using STAF
java.util.Collection	getRunningEngineNames() Get collection of running Engine names.
void	getSAFSTestRecordData(java.lang.String trd_root, TestRecordData trd) Get the SAFSVARS Test Record Data into the given trd_root.
java.lang.String	getSTAFEnv(java.lang.String env) getSTAFEnv returns string value or an empty string
int	getSTAFVersion()
static java.lang.String	getSTAFVersionString(com.ibm.staf.STAFHandle handle)
java.lang.String	getVariable(java.lang.String var) Purpose: getVariable: get a variable from safsvars service
void	initialize(java.lang.String hookName) Purpose: creates the STAFHandle
boolean	isInitialized() have we been initialized (initialized, but not unRegistered)
boolean	isSAFSINPUTAvailable() Function isSAFSINPUTAvailable()
boolean	isSAFSLOGSAvailable() Function isSAFSLOGSAvailable()
boolean	isSAFSMAPSAvailable() Function isSAFSMAPSAvailable()
boolean	isSAFSVARSAvailable() Function isSAFSVARSAvailable()
boolean	isServiceAvailable(java.lang.String servicename) Queries the STAF SERVICE service to see if a particular service is currently registered and running.
boolean	isToolAvailable(java.lang.String toolname) Queries the STAF HANDLE service to see if a particular process name is currently registered and running.
java.lang.String	lentagValue(java.lang.String val) Purpose: return the value in STAF lentag format, :len:val
java.lang.String	localPing() localPing to know if STAF has been initailized
com.ibm.staf.STAFResult	localStartProcess(java.lang.String appname, java.lang.String workdir) start local STAF process to execute "STAF local PROCESS START COMMAND ...".
void	postEvent(java.lang.String event) Purpose: post a single staf event (sem service)
int	postNextHookTestEvent(java.lang.String process_name, java.lang.String trd_root, TestRecordData trd) Perform the complete driver-side protocol for dispatching an engine to process a test record.
void	pulseEvent(java.lang.String event) Purpose: pulse a single staf event (sem service)
void	releaseSTAFMutex(java.lang.String mutex) Function STAFreleaseMutex(String mutex)
com.ibm.staf.STAFResult	removeService(java.lang.String machine, java.lang.String service) unload a STAF service
void	resetEvent(java.lang.String event) Purpose: reset a single staf event (sem service)
protected void	resetEvents() Deprecated. This is specific to IBM Rational Functional Tester
void	resetHookEvents(java.lang.String process_name) Reset staf hook events (ready, dispatch, running, results, done, shutdown) for the given process.
boolean	sendQueueMessage(java.lang.String name, java.lang.String message) Purpose: send a queue message using STAF
void	setHookTestResults(java.lang.String process_name) setHookTestResults: makes call to 'setHookTestResultsWTimeout(process_name, 12);'
void	setHookTestResultsWTimeout(java.lang.String process_name, long timeoutseconds) setHookTestResultsWTimeout: makes call to 'postEvent(process_name + Results);' This routines will drive the RESULTS event true.
void	setLocalMachine() reset the machine back to "local"
void	setMachine(java.lang.String machine) set the machine to the specified parameter
void	setSAFSTestRecordData(java.lang.String trd_root, TestRecordData trd) Set the SAFSVARS Test Record Data for the given trd_root.
void	setTestResults() setTestResults: makes call to 'setHookTestResultsWTimeout(SAFS_ROBOTJ_PROCESS, 3);' This is deprecated for older RobotJ handling only.
boolean	setVariable(java.lang.String var, java.lang.String val) Purpose: setup a variable with it's value using STAF safsvars service.
com.ibm.staf.STAFResult	shutDown(java.lang.String machine) shutDown STAF machine, Applies to STAF2.X and STAF3.X
protected java.lang.String	submit(java.lang.String where, java.lang.String name, java.lang.String command) Purpose: passed on to handle.submit
protected com.ibm.staf.STAFResult	submit2(java.lang.String where, java.lang.String name, java.lang.String command) Purpose: passed on to handle.submit2
com.ibm.staf.STAFResult	submit2ForFormatUnchangedService(java.lang.String where, java.lang.String name, java.lang.String command) Purpose: passed on to handle.submit2 Used to call the services with unchangeable format.
com.ibm.staf.STAFResult	submit2WithVar(java.lang.String sysName, java.lang.String srvName, java.lang.String cmdName, java.lang.String varName) Purpose: submit to STAF and record varName.rc and varname.result into variable storage (SAFSVARS).
void	unRegister() unregister, passed along to 'handle'
void	waitEvent(java.lang.String event, long delaySeconds) Purpose: staf event wait
void	waitSTAFMutex(java.lang.String mutex, long delaySeconds) Function STAFwaitMutex(String mutex, long delaySeconds)

Methods inherited from class java.lang.Object

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

Field Detail

STAF_DELAY_SERVICE

public static final java.lang.String STAF_DELAY_SERVICE

See Also:

Constant Field Values

STAF_GLOBALVARS_VERSION

public static final java.lang.String STAF_GLOBALVARS_VERSION

See Also:

Constant Field Values

STAF_SERVICELOADER_V2

public static final java.lang.String STAF_SERVICELOADER_V2

"STAF/Service/STAF/ServiceLoader"

See Also:

Constant Field Values

STAF_SERVICELOADER_V3

public static final java.lang.String STAF_SERVICELOADER_V3

"STAF/Service/STAFServiceLoader"

See Also:

Constant Field Values

SAFS_SAFSVARS_PROCESS

public static final java.lang.String SAFS_SAFSVARS_PROCESS

"SAFSVariableService"

See Also:

Constant Field Values

SAFS_SAFSMAPS_PROCESS

public static final java.lang.String SAFS_SAFSMAPS_PROCESS

"SAFSAppMapService"

See Also:

Constant Field Values

SAFS_INPUT_PROCESS

public static final java.lang.String SAFS_INPUT_PROCESS

"SAFSInputService"

See Also:

Constant Field Values

SAFS_SAFSLOGS_PROCESS

public static final java.lang.String SAFS_SAFSLOGS_PROCESS

"STAF/Service/SAFSLOGS"

See Also:

Constant Field Values

SAFS_GENERIC_PROCESS

public static final java.lang.String SAFS_GENERIC_PROCESS

"SAFS/Process"

See Also:

Constant Field Values

SAFS_GENERIC_PROCESS_ID

public static final java.lang.String SAFS_GENERIC_PROCESS_ID

"SAFS/ProcessID"

See Also:

Constant Field Values

SAFS_ROBOTJ_PROCESS

public static final java.lang.String SAFS_ROBOTJ_PROCESS

"SAFS/RobotJ"

See Also:

Constant Field Values

SAFS_ROBOTJ_PROCESS_ID

public static final java.lang.String SAFS_ROBOTJ_PROCESS_ID

"SAFS/RobotJID"

See Also:

Constant Field Values

SAFS_CLASSIC_PROCESS

public static final java.lang.String SAFS_CLASSIC_PROCESS

"SAFS/RobotClassic"

See Also:

Constant Field Values

SAFS_CLASSIC_PROCESS_ID

public static final java.lang.String SAFS_CLASSIC_PROCESS_ID

"SAFS/RobotClassicID"

See Also:

Constant Field Values

SAFS_ABBOT_PROCESS

public static final java.lang.String SAFS_ABBOT_PROCESS

"SAFS/Abbot"

See Also:

Constant Field Values

SAFS_ABBOT_PROCESS_ID

public static final java.lang.String SAFS_ABBOT_PROCESS_ID

"SAFS/AbbotID"

See Also:

Constant Field Values

SAFS_VARIABLE_SERVICE

public static final java.lang.String SAFS_VARIABLE_SERVICE

"SAFSVARS"

See Also:

Constant Field Values

SAFS_APPMAP_SERVICE

public static final java.lang.String SAFS_APPMAP_SERVICE

"SAFSMAPS"

See Also:

Constant Field Values

SAFS_LOGGING_SERVICE

public static final java.lang.String SAFS_LOGGING_SERVICE

"SAFSLOGS"

See Also:

Constant Field Values

SAFS_LOGGINGLOG_SERVICE

public static final java.lang.String SAFS_LOGGINGLOG_SERVICE

See Also:

Constant Field Values

SAFS_INPUT_SERVICE

public static final java.lang.String SAFS_INPUT_SERVICE

"SAFSINPUT"

See Also:

Constant Field Values

SAFS_HOOK_TRD

public static final java.lang.String SAFS_HOOK_TRD

"SAFS/HOOK/" trd root

See Also:

Constant Field Values

SAFS_CYCLE_TRD

public static final java.lang.String SAFS_CYCLE_TRD

"SAFS/CYCLE/" trd root

See Also:

Constant Field Values

SAFS_SUITE_TRD

public static final java.lang.String SAFS_SUITE_TRD

"SAFS/SUITE/" trd root

See Also:

Constant Field Values

SAFS_STEP_TRD

public static final java.lang.String SAFS_STEP_TRD

"SAFS/STEP/" trd root

See Also:

Constant Field Values

SAFS_VAR_INPUTRECORD

public static final java.lang.String SAFS_VAR_INPUTRECORD

".../inputrecord"

See Also:

Constant Field Values

SAFS_VAR_STATUSCODE

public static final java.lang.String SAFS_VAR_STATUSCODE

".../statuscode"

See Also:

Constant Field Values

SAFS_VAR_STATUSINFO

public static final java.lang.String SAFS_VAR_STATUSINFO

".../statusinfo"

See Also:

Constant Field Values

SAFS_VAR_FILENAME

public static final java.lang.String SAFS_VAR_FILENAME

".../filename"

See Also:

Constant Field Values

SAFS_VAR_LINENUMBER

public static final java.lang.String SAFS_VAR_LINENUMBER

".../linenumber"

See Also:

Constant Field Values

SAFS_VAR_SEPARATOR

public static final java.lang.String SAFS_VAR_SEPARATOR

".../separator"

See Also:

Constant Field Values

SAFS_VAR_FAC

public static final java.lang.String SAFS_VAR_FAC

".../fac"

See Also:

Constant Field Values

SAFS_VAR_TESTLEVEL

public static final java.lang.String SAFS_VAR_TESTLEVEL

".../testlevel"

See Also:

Constant Field Values

SAFS_VAR_APPMAPNAME

public static final java.lang.String SAFS_VAR_APPMAPNAME

".../appmapname"

See Also:

Constant Field Values

SAFS_VAR_BENCHDIRECTORY

public static final java.lang.String SAFS_VAR_BENCHDIRECTORY

7 initial preset variables

See Also:

Constant Field Values

SAFS_VAR_DATAPOOLDIRECTORY

public static final java.lang.String SAFS_VAR_DATAPOOLDIRECTORY

See Also:

Constant Field Values

SAFS_VAR_DIFDIRECTORY

public static final java.lang.String SAFS_VAR_DIFDIRECTORY

See Also:

Constant Field Values

SAFS_VAR_LOGSDIRECTORY

public static final java.lang.String SAFS_VAR_LOGSDIRECTORY

See Also:

Constant Field Values

SAFS_VAR_PROJECTDIRECTORY

public static final java.lang.String SAFS_VAR_PROJECTDIRECTORY

See Also:

Constant Field Values

SAFS_VAR_TESTDIRECTORY

public static final java.lang.String SAFS_VAR_TESTDIRECTORY

See Also:

Constant Field Values

SAFS_VAR_SYSTEMUSERID

public static final java.lang.String SAFS_VAR_SYSTEMUSERID

See Also:

Constant Field Values

SAFS_VAR_ROOTVERIFYDIRECTORY

public static final java.lang.String SAFS_VAR_ROOTVERIFYDIRECTORY

See Also:

Constant Field Values

SAFS_VAR_RUNTIMEREPOSITORY

public static final java.lang.String SAFS_VAR_RUNTIMEREPOSITORY

See Also:

Constant Field Values

SAFS_HOOK_TRD_MUTEX

public static final java.lang.String SAFS_HOOK_TRD_MUTEX

"SAFS/Hook/TRD", Mutex for ALL applications and processes wishing to use SAFS/Hook/TRD data

See Also:

Constant Field Values

ROBOTJ_EVENT_START

public static final java.lang.String ROBOTJ_EVENT_START

"SAFS/RobotJStart"

See Also:

Constant Field Values

ROBOTJ_EVENT_READY

public static final java.lang.String ROBOTJ_EVENT_READY

"SAFS/RobotJReady"

See Also:

Constant Field Values

ROBOTJ_EVENT_DISPATCH

public static final java.lang.String ROBOTJ_EVENT_DISPATCH

"SAFS/RobotJDispatch"

See Also:

Constant Field Values

ROBOTJ_EVENT_RUNNING

public static final java.lang.String ROBOTJ_EVENT_RUNNING

"SAFS/RobotJRunning"

See Also:

Constant Field Values

ROBOTJ_EVENT_RESULTS

public static final java.lang.String ROBOTJ_EVENT_RESULTS

"SAFS/RobotJResults"

See Also:

Constant Field Values

ROBOTJ_EVENT_DONE

public static final java.lang.String ROBOTJ_EVENT_DONE

"SAFS/RobotJDone"

See Also:

Constant Field Values

ROBOTJ_EVENT_SHUTDOWN

public static final java.lang.String ROBOTJ_EVENT_SHUTDOWN

"SAFS/RobotJShutdown"

See Also:

Constant Field Values

SAFS_EVENT_START

public static final java.lang.String SAFS_EVENT_START

"Start"

See Also:

Constant Field Values

SAFS_EVENT_READY

public static final java.lang.String SAFS_EVENT_READY

"Ready"

See Also:

Constant Field Values

SAFS_EVENT_DISPATCH

public static final java.lang.String SAFS_EVENT_DISPATCH

"Dispatch"

See Also:

Constant Field Values

SAFS_EVENT_RUNNING

public static final java.lang.String SAFS_EVENT_RUNNING

"Running"

See Also:

Constant Field Values

SAFS_EVENT_RESULTS

public static final java.lang.String SAFS_EVENT_RESULTS

"Results"

See Also:

Constant Field Values

SAFS_EVENT_DONE

public static final java.lang.String SAFS_EVENT_DONE

"Done"

See Also:

Constant Field Values

SAFS_EVENT_SHUTDOWN

public static final java.lang.String SAFS_EVENT_SHUTDOWN

"Shutdown"

See Also:

Constant Field Values

LOCAL_MACHINE

public static final java.lang.String LOCAL_MACHINE

the normal "local" machine setting used by STAF

See Also:

Constant Field Values

STAFQueueMessageClass

protected static java.lang.Class STAFQueueMessageClass

getQueueMessageField

protected static java.lang.reflect.Field getQueueMessageField

Constructor Detail

STAFHelper

public STAFHelper()

Purpose: constructor, must be 'initialized' by the user.

STAFHelper

public STAFHelper(java.lang.String processName)
           throws SAFSSTAFRegistrationException

Purpose: constructor that also initializes with the given processName.

Throws:

SAFSSTAFRegistrationException

Method Detail

getProcessName

public java.lang.String getProcessName()

the String name of the process/hook used at construction

getHandle

public com.ibm.staf.STAFHandle getHandle()

get the handle. hopefull this won't be needed if all of the methods here do the work

getHandleNumber

public int getHandleNumber()

get the handle's number

getMachine

public java.lang.String getMachine()

get the current value of 'machine'

setMachine

public void setMachine(java.lang.String machine)

set the machine to the specified parameter

setLocalMachine

public void setLocalMachine()

reset the machine back to "local"

initialize

public void initialize(java.lang.String hookName)
                throws SAFSSTAFRegistrationException

Purpose: creates the STAFHandle

Parameters:

hookName, - String

Throws:

SAFSSTAFRegistrationException - (wraps the message from STAFException)

isInitialized

public boolean isInitialized()

have we been initialized (initialized, but not unRegistered)

unRegister

public void unRegister()
                throws SAFSException

unregister, passed along to 'handle'

Throws:

SAFSException

submit2ForFormatUnchangedService

public com.ibm.staf.STAFResult submit2ForFormatUnchangedService(java.lang.String where,
                                                                java.lang.String name,
                                                                java.lang.String command)

Purpose: passed on to handle.submit2 Used to call the services with unchangeable format. Usually for SAFSVARS, SAFSMAP, SAFSINPUT and SAFSLOG.

Parameters:

where, - String

name, - String

command, - String

Returns:

STAFResult

submit2

protected com.ibm.staf.STAFResult submit2(java.lang.String where,
                                          java.lang.String name,
                                          java.lang.String command)

Purpose: passed on to handle.submit2

Parameters:

where, - String

name, - String

command, - String

Returns:

STAFResult

submit2WithVar

public com.ibm.staf.STAFResult submit2WithVar(java.lang.String sysName,
                                              java.lang.String srvName,
                                              java.lang.String cmdName,
                                              java.lang.String varName)
                                       throws com.ibm.staf.STAFException,
                                              SAFSException

Purpose: submit to STAF and record varName.rc and varname.result into variable storage (SAFSVARS). If an error occurs when trying to write the varName values STAFResult will return with result.rc=47 and result.result=varName. Otherwise we return the STAFResult from the STAF call itself.

Parameters:

sysName, - String

srvName, - String

cmdName, - String

varName, - String

Returns:

STAFResult

Throws:

com.ibm.staf.STAFException

SAFSException

submit

protected java.lang.String submit(java.lang.String where,
                                  java.lang.String name,
                                  java.lang.String command)
                           throws com.ibm.staf.STAFException

Purpose: passed on to handle.submit

Parameters:

where, - String

name, - String

command, - String

Returns:

String

Throws:

com.ibm.staf.STAFException

lentagValue

public java.lang.String lentagValue(java.lang.String val)

Purpose: return the value in STAF lentag format, :len:val

Parameters:

val, - String

Returns:

:val.length():val

getAppMapNames

public java.util.Collection getAppMapNames()
                                    throws SAFSException

Purpose: get collection of appmap names
Assumptions: output of this command:
staf local safsmaps list
looks like:
safsmaps:LIST:2
c:\cycletest\datapool\dealapp.map:C:\CycleTest\Datapool\DealApp.MAP
deal:C:\CycleTest\Datapool\DealApp.map

Returns:

Collection

Throws:

SAFSException

getRunningEngineNames

public java.util.Collection getRunningEngineNames()
                                           throws SAFSException

Get collection of running Engine names. We parse the STAF command: staf local SEM list EVENT
We deduce the number of unique <engine>Ready or <engine>Running events. We return the collection of unique engine names.

Returns:

Collection (Vector) of String engine names( ex: SAFS/RobotJ, SAFS/SELENIUM, etc..)

Throws:

SAFSException

getLogName

public java.lang.String getLogName()
                            throws SAFSException

Throws:

SAFSException

getVariable

public java.lang.String getVariable(java.lang.String var)
                             throws SAFSException

Purpose: getVariable: get a variable from safsvars service

Parameters:

var, - String, name of variable to get value for

Returns:

the value in the VAR

Throws:

SAFSException, - if not ok

SAFSException

setVariable

public boolean setVariable(java.lang.String var,
                           java.lang.String val)
                    throws SAFSException

Purpose: setup a variable with it's value using STAF safsvars service.
format used:
" SET " + lentagValue(var) + " VALUE " + lentagValue(val);
example: SET :19:STAF/hook/variable1 VALUE :31:This is the value for variable1
Side Effects: STAF is modified (safsvars service)
State Read: fields 'handle'
Assumptions: we are using the SAFSVARS SERVICE registered in STAF
note that currently after the VALUE there are quotes around the 'val'

Parameters:

var, - String name of variable

val, - String value of variable (can be null or empty)

Returns:

true if successful, false if not

Throws:

SAFSException - if var is invalid

delay

public boolean delay(int millisec)

Purpose: delay number of milliseconds
Side Effects: uses STAF delay service
Assumptions: STAF loaded

Parameters:

millisec, - int

Returns:

true if successful, false if not

getQueueMessage

public java.lang.String getQueueMessage(java.lang.String name,
                                        java.lang.Integer waitTime)
                                 throws SAFSException

Purpose: get a queue message using STAF

Parameters:

name, - String , the string name of the queue, if null then omit name part from command

waitTime, - Integer, milliseconds to wait, if null, then omit from the get command; indefinate wait

Returns:

String, the returned message

Throws:

SAFSException, - if timeout or error

SAFSException

sendQueueMessage

public boolean sendQueueMessage(java.lang.String name,
                                java.lang.String message)

Purpose: send a queue message using STAF

Parameters:

name, - String , the string name of the queue

message, - String, the message to send, it will be length tagged.

Returns:

boolean, true if successful, false if not

pulseEvent

public void pulseEvent(java.lang.String event)
                throws SAFSException

Purpose: pulse a single staf event (sem service)

Parameters:

event, - String

Throws:

SAFSException - if staf has a problem

postEvent

public void postEvent(java.lang.String event)
               throws SAFSException

Purpose: post a single staf event (sem service)

Parameters:

event, - String

Throws:

SAFSException - if staf has a problem

resetEvent

public void resetEvent(java.lang.String event)
                throws SAFSException

Purpose: reset a single staf event (sem service)

Parameters:

event, - String

Throws:

SAFSException - if staf has a problem

resetEvents

protected void resetEvents()
                    throws SAFSException

Deprecated. This is specific to IBM Rational Functional Tester

calls resetHookEvents(SAFS_ROBOTJ_PROCESS);

Throws:

SAFSException - if staf has a problem

resetHookEvents

public void resetHookEvents(java.lang.String process_name)
                     throws SAFSException

Reset staf hook events (ready, dispatch, running, results, done, shutdown) for the given process. If we are resetting events for a shutdown the engine should POST the Shutdown *after* this reset.

Throws:

SAFSException - if staf has a problem

waitEvent

public void waitEvent(java.lang.String event,
                      long delaySeconds)
               throws SAFSException

Purpose: staf event wait

Parameters:

event, - String

delaySeconds, - long, if < 0, then no param used for wait

Throws:

SAFSException - if staf has a problem

getNextTestEvent

public java.lang.String getNextTestEvent()
                                  throws SAFSException

getNextTestEvent:

Returns:

getNextHookTestEvent(SAFS_ROBOTJ_PROCESS, SAFS_HOOK_TRD);

Throws:

SAFSException - if staf has a problem

getNextHookTestEvent

public java.lang.String getNextHookTestEvent(java.lang.String process_name,
                                             java.lang.String trd_name)
                                      throws SAFSException

Perform the complete engine-side protocol for processinga test record dispatched from a driver.

getNextHookTestEvent:
waitEvent "Dispatch";
resetEvent "Ready";
if(result.rc != 0) throw SAFSException;
result = postEvent "Running"
return getVariable(INPUTRECORD);

Parameters:

process_name - -- the STAF-registered name of the engine involved.

trd_name - -- the TestRecordData SAFSVARS storage root, normally "SAFS/HOOK/".

Returns:

String, the variable INPUTRECORD

Throws:

SAFSException - if staf has a problem

postNextHookTestEvent

public int postNextHookTestEvent(java.lang.String process_name,
                                 java.lang.String trd_root,
                                 TestRecordData trd)
                          throws SAFSException

Perform the complete driver-side protocol for dispatching an engine to process a test record.

postNextHookTestEvent:
wait for process_name "Ready"
acquire SAFSVARS trd_root Mutex
set SAFSVARS test record data
"Dispatch" to specified process_name
waitFor "Results" event
retrieve the results from SAFSVARS test record data
pulse the "Done" event
release the SAFSVARS trd_root Mutex
if(result.rc != 0) throw SAFSException;

Parameters:

process_name - -- the STAF-registered name of the engine to dispatch.

trd_root - -- the TestRecordData SAFSVARS storage root, normally "SAFS/HOOK/".

trd - -- the TestRecordData to place into SAFSVARS for execution by the engine.

Returns:

the statuscode from the call

Throws:

SAFSException - if staf has a problem

setSAFSTestRecordData

public void setSAFSTestRecordData(java.lang.String trd_root,
                                  TestRecordData trd)
                           throws SAFSException

Set the SAFSVARS Test Record Data for the given trd_root. The most common trd_root is "SAFS/HOOK/", which is used by all official drivers and engines. The routine does not deal with the TRD Mutex for the trd_root provided. It assumes the caller is handling the mutex.

Sets the following record data:
• inputrecord
• separator
• filename
• linenumber
• testlevel
• appmapname
• fac
• statuscode
• statusinfo

Throws:

SAFSException

getSAFSTestRecordData

public void getSAFSTestRecordData(java.lang.String trd_root,
                                  TestRecordData trd)
                           throws SAFSException

Get the SAFSVARS Test Record Data into the given trd_root. The most common trd_root is "SAFS/HOOK/", which is used by all official drivers and engines. The routine does not deal with the TRD Mutex for the trd_root provided. It assumes the caller is handling the mutex.

Gets the following record data:
• inputrecord
• separator
• filename
• linenumber
• testlevel
• appmapname
• fac
• statuscode
• statusinfo

Throws:

SAFSException

setTestResults

public void setTestResults()
                    throws SAFSException

setTestResults: makes call to 'setHookTestResultsWTimeout(SAFS_ROBOTJ_PROCESS, 3);' This is deprecated for older RobotJ handling only.

Throws:

SAFSException - if staf has a problem

setHookTestResults

public void setHookTestResults(java.lang.String process_name)
                        throws SAFSException

setHookTestResults: makes call to 'setHookTestResultsWTimeout(process_name, 12);'

Throws:

SAFSException - if staf has a problem

setHookTestResultsWTimeout

public void setHookTestResultsWTimeout(java.lang.String process_name,
                                       long timeoutseconds)
                                throws SAFSException

setHookTestResultsWTimeout: makes call to 'postEvent(process_name + Results);' This routines will drive the RESULTS event true. This routine waits for the corresponding DONE event from the calling driver for up to timeoutseconds before timing out. Timing out allows us to continue in the event of a Driver that has been shutdown.

Throws:

SAFSException - if staf has a problem

getAppMapItem

public java.lang.String getAppMapItem(java.lang.String appMapID,
                                      java.lang.String section,
                                      java.lang.String item)

Purpose: getitem from safsmaps using STAF
format used:
" getitem "+appMapID+" SECTION "+section+" Item "+item + "";
example: staf local safsmaps getitem "classicc" SECTION "LoginWindow" Item "OKButton"
Side Effects: STAF is accessed (safsmaps service)
State Read: field 'handle'
Assumptions: we are using the SAFSMAPS SERVICE registered in STAF
note that currently after each value there are quotes.

Parameters:

appMapID, - String (can be null or empty)

section, - String (can be null or empty)

item, - String

Returns:

itemvalue, null if exception is encountered meaning item not found

getAppMapItem

public java.lang.String getAppMapItem(java.lang.String appMapID,
                                      java.lang.String section,
                                      java.lang.String item,
                                      boolean isDynamic)

Purpose: getitem from safsmaps using STAF, and check if the item has a static recognition string.
format used:
" getitem "+appMapID+" SECTION "+section+" Item "+item + "";
example: staf local safsmaps getitem "classicc" SECTION "LoginWindow" Item "OKButton"
Side Effects: STAF is accessed (safsmaps service)
State Read: field 'handle'
Assumptions: we are using the SAFSMAPS SERVICE registered in STAF
note that currently after each value there are quotes.

Parameters:

appMapID, - String (can be null or empty)

section, - String (can be null or empty)

item, - String

isDynamic, - boolean

Returns:

itemvalue, null if exception is encountered meaning item not found

isToolAvailable

public boolean isToolAvailable(java.lang.String toolname)

Queries the STAF HANDLE service to see if a particular process name is currently registered and running. For example, the SAFSVARS service process name is "SAFSVariableService".

The routine will do a QUERY ALL on the HANDLE service and then evaluate if the requested tool appears anywhere in the returned list of named processes.

Note, because we do a substring search, we can match on just the most significant portion of the process name.

Parameters:

toolname - The name of the process of interest. Check your documentation to find the name normally registered by the tool of interest. This can be just a substring of the full tool name.

Returns:

true or false

Since:

JUN 19, 2003
History:

JUN 19, 2003 (DBauman) Original Release
JUN 26, 2003 (DBauman) ported to java
APR 04, 2004 (CANAGL) Enabled matching on substring of tool name. and made the function public.
APR 06, 2004 (CANAGL) Ignore Case on toolname matches.

isServiceAvailable

public boolean isServiceAvailable(java.lang.String servicename)

Queries the STAF SERVICE service to see if a particular service is currently registered and running. For example, the SAFSVARS service is "SAFSVARS".

The routine will do a "LIST" on the SERVICE service and then evaluate if the requested service appears anywhere in the returned list of services.

Note, because we do a substring search, we can match on just the most significant portion of the service name.

Parameters:

servicename - unique substring of the service of interest. Check your documentation to find the name normally registered by the service of interest. This can be just a substring of the full service name.

Returns:

true or false

Since:

JUN 07, 2004
History:

JUN 07, 2004 (CANAGL) Original Release

isSAFSVARSAvailable

public boolean isSAFSVARSAvailable()

Function isSAFSVARSAvailable()

DESCRIPTION: Queries to see if the "SAFSVARS" service is currently running.

Returns:

true or false
Orig Author: Carl Nagle
Orig Date: JUN 19, 2003
History:

JUN 19, 2003 Original Release
JUN 26, 2003 dbauman: ported to java
JUN 07, 2004 CANAGL: mod to use isServiceAvailable

isSAFSMAPSAvailable

public boolean isSAFSMAPSAvailable()

Function isSAFSMAPSAvailable()

DESCRIPTION:

Queries to see if the "SAFSMAPS" service is running.

PARAMETERS:

(none)

RETURNS:

true or false

Orig Author: Carl Nagle
Orig Date: JUN 19, 2003
History:

JUN 19, 2003 Original Release
JUN 26, 2003 dbauman: ported to java
JUN 07, 2004 CANAGL: mod to use isServiceAvailable

isSAFSLOGSAvailable

public boolean isSAFSLOGSAvailable()

Function isSAFSLOGSAvailable()

DESCRIPTION: Queries to see if the "SAFSLOGSLog" service is running. This service is launched and used by "SAFSLOGS" durings its initialization.

Returns:

true or false
Orig Author: Carl Nagle
Orig Date: SEP 12, 2003
History:

SEP 12, 2003 Original Release
JUN 07, 2004 CANAGL: mod to use isServiceAvailable

isSAFSINPUTAvailable

public boolean isSAFSINPUTAvailable()

Function isSAFSINPUTAvailable()

DESCRIPTION:

Queries to see if the "SAFSINPUT" service is running.

PARAMETERS:

(none)

RETURNS:

true or false

Orig Author: Carl Nagle
Orig Date: JUN 17, 2004
History:

JUN 17, 2004 Original Release

waitSTAFMutex

public void waitSTAFMutex(java.lang.String mutex,
                          long delaySeconds)
                   throws SAFSException

Function STAFwaitMutex(String mutex, long delaySeconds)

DESCRIPTION: WAIT for a single STAF SEMaphore MUTEX

Parameters:

mutex - the name of the mutex

delaySeconds - the number of seconds to wait ( < 0 = wait indefinitely)

Throws:

SAFSException - if STAFException is caught
Orig Author: Carl Nagle
Orig Date: JUN 19, 2003
History:

JUN 19, 2003 Original Release
JUN 26, 2003 dbauman: ported to java

releaseSTAFMutex

public void releaseSTAFMutex(java.lang.String mutex)
                      throws SAFSException

Function STAFreleaseMutex(String mutex)

DESCRIPTION: RELEASE a single STAF SEMaphore MUTEX

Parameters:

mutex - the name of the mutex

Throws:

SAFSException - if STAFException is caught
Orig Author: Carl Nagle
Orig Date: JUN 19, 2003
History:

JUN 19, 2003 Original Release
JUN 26, 2003 dbauman: ported to java

getSTAFVersion

public int getSTAFVersion()

Returns:

the version number of STAF. E.g. return 2 for STAF2.6.11; 0 means no STAF loaded.

getSTAFVersionString

public static java.lang.String getSTAFVersionString(com.ibm.staf.STAFHandle handle)

Returns:

The staf version string, such as 3.3.3

getSTAFEnv

public java.lang.String getSTAFEnv(java.lang.String env)

getSTAFEnv returns string value or an empty string

localPing

public java.lang.String localPing()
                           throws com.ibm.staf.STAFException

localPing to know if STAF has been initailized

Returns:

String if ok. "PONG" returned in STAF2.x and STAF3.3.3

Throws:

com.ibm.staf.STAFException

shutDown

public com.ibm.staf.STAFResult shutDown(java.lang.String machine)

shutDown STAF machine, Applies to STAF2.X and STAF3.X

Returns:

STAFResult

localStartProcess

public com.ibm.staf.STAFResult localStartProcess(java.lang.String appname,
                                                 java.lang.String workdir)
                                          throws java.io.IOException

start local STAF process to execute "STAF local PROCESS START COMMAND ...". Applies to STAF2.X and STAF3.X.

Parameters:

appname -

workdir -

Returns:

STAFResult

Throws:

java.io.IOException

addService

public com.ibm.staf.STAFResult addService(java.lang.String machine,
                                          java.lang.String servicename,
                                          java.lang.String classpath,
                                          java.lang.String dir,
                                          java.lang.String options)

add and launch standard SAFS services SAFSINPUT, SAFSMAPS and SAFSLOG

Parameters:

machine -

servicename, - one of three services SAFSINPUT, SAFSMAPS and SAFSLOG.

classpath -

dir -

options -

Returns:

STAFResult

addServiceSAFSVARS

public com.ibm.staf.STAFResult addServiceSAFSVARS(java.lang.String machine,
                                                  java.lang.String servicename,
                                                  java.lang.String classpath,
                                                  java.lang.String mapService,
                                                  java.lang.String options)

add and launch standard SAFS service, SAFSVARS.

Parameters:

machine -

servicename, - SAFSVARS or user-defined service that follows the rule of SAFSVARS.

classpath -

mapService -

options -

Returns:

removeService

public com.ibm.staf.STAFResult removeService(java.lang.String machine,
                                             java.lang.String service)

unload a STAF service

Parameters:

machine, - STAF machine name

service, - service name