org.safs.tools.engines

Class GenericEngine

java.lang.Object

org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass

org.safs.tools.engines.GenericEngine

All Implemented Interfaces:

ConfigurableToolsInterface, EngineInterface, GenericToolsInterface, ITestRecordStackable, RuntimeDataInterface

Direct Known Subclasses:

AutoItComponent, SAFSABBOT, SAFSDRIVERCOMMANDS, SAFSDROID, SAFSIOS, SAFSQTP, SAFSROBOTJ, SAFSSELENIUM, SAFSTC, TIDComponent, TIDDriverCommands, TIDDriverCounterCommands, TIDDriverFlowCommands, TIDDriverLogCommands, TIDDriverRestCommands

public class GenericEngine
extends DriverConfiguredSTAFInterfaceClass
implements EngineInterface, RuntimeDataInterface, ITestRecordStackable

Author:

Carl Nagle DEC 14, 2005 Refactored with DriverConfiguredSTAFInterface superclass, Carl Nagle JUL 28, 2009 Enhanced shutdown operations for stability. LeiWg AUG 23, 2010 Modify method logMessage(): call logMessage of its super class. Lei Wang APR 27, 2012 Modify method shutdownService(): reset all the semaphores of hook. Lei Wang MAY 03, 2012 Modify method shutdownService(): wait for "shutdown" semaphore and reset it. Add method resetShutdownSemaphore(): check the condition before resetting "shutdown" semaphore. Modify method launchInterface(): Try to reset "shutdown" semaphore during of launch engine.
NOV 25, 2014 (Lei Wang) Copy method deduceFile() from org.safs.Processor: so that the same logic will be used to deduce test/bench file name.

Field Summary

Fields

Modifier and Type	Field and Description
protected GenericProcessConsole	console The Console handling IO streams for the engine process.
protected java.lang.Process	process The Java Process running the engine.
protected TestRecordHelper	testRecordData Stores the data on the input record we are to process.
protected ITestRecordStackable	testrecordStackable The ITestRecordStackable used to store 'Test Record' in a FILO.

Fields inherited from class org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass

config, customStr, customText, debugStr, debugText, driver, DRIVER_TEMP_PROCESS, failedStr, failedText, genericStr, genericText, launchCount, log, machine, otherStr, otherText, passedStr, passedText, processName, running, SAFS_RESBUN_NAME, servicename, shutdownCount, staf, STAFPROC_EXE, warningStr, warningText, weStartedService, weStartedSTAF

Fields inherited from interface org.safs.tools.engines.EngineInterface

COMMAND_SHUTDOWN_HOOK

Constructor Summary

Constructors

Constructor and Description
GenericEngine() Constructor for GenericEngine

Method Summary

Modifier and Type	Method and Description
protected java.io.File	deduceBenchFile(java.lang.String filename) Deduce the absolute full path bench file name.
protected java.io.File	deduceProjectFile(java.lang.String filename) Deduce the absolute full path to a project-relative file.
protected java.io.File	deduceTestFile(java.lang.String filename) Deduce the absolute full path test file name.
java.lang.String	getAppMapItem(java.lang.String appMapId, java.lang.String sectionName, java.lang.String itemName) Retrieve the resolved value of an item stored in the App Map chain (SAFSMAPS).
java.lang.String	getEngineName() Retrieve the name of the Engine.
java.lang.String	getVariable(java.lang.String var) Retrieve the current runtime value of the global variable (SAFSVARS).
boolean	isToolRunning() Verifies a STAF tool matching our engine name is running.
void	launchInterface(java.lang.Object configInfo) Typically expects a DriverInterface object for initialization.
protected void	logMessage(java.lang.String msg, java.lang.String msgdescription, int msgtype) Convenience routine for building the appropriate MessageInfo and logging a message to our active log.
protected java.lang.String	makeQuotedPath(java.lang.String path, boolean isFile) Wraps valid file path in double-quotes if necessary.
protected java.lang.String	makeQuotedString(java.lang.String text) Wraps the privided text in double-quotes *if* the text contains a space.
TestRecordData	popTestRecord() Retrieve the Test-Record from the the Stack after the execution of a keyword.
protected void	postShutdownServiceDelay() Called internally by shutdownService(String).
long	processRecord(TestRecordHelper testRecordData) Initiate the event-driven protocol to send the test record to the engine.
void	pushTestRecord(TestRecordData trd) Push the current 'test record' into the Stack before the execution of a keyword.
void	reset() Reset or clear any cached information in the underlying tool or service.
protected boolean	resetShutdownSemaphore() This method is intended to reset the "shutdown" semaphore post hook when it stops.
protected java.lang.String	saveTestRecordScreenToTestDirectory(TestRecordData testRecordData) Normally called on failure to execute an IBT command.
protected long	setTRDStatus(TestRecordHelper trd, long status) Sets TRD statuscode to the provided status and returns the same.
boolean	setVariable(java.lang.String var, java.lang.String val) Set a new runtime value of a global variable (SAFSVARS).
protected void	shutdownService(java.lang.String aname) Shutdown the Engine.
protected void	waitHookShutdownAndReset(int timeoutInSeconds) Called internally by shutdownService(String).

Methods inherited from class org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass

configureJSTAFServiceEmbeddedJVMOption, extendedGenericMessage, finalize, getCoreInterface, getEmbeddedJVMBinPath, getSTAFHelper, logMessage, setLogUtilities, setLogUtilities, shutdown, simpleGenericMessage, simpleGenericSuccessMessage, simpleGenericWarningMessage, simpleSuccessMessage, simpleSuccessMessage, simpleSuccessUsingMessage, standardErrorMessage, waitForServiceStartCompletion

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.safs.tools.GenericToolsInterface

getCoreInterface, shutdown

Field Detail

process

protected java.lang.Process process

The Java Process running the engine.

console

protected GenericProcessConsole console

The Console handling IO streams for the engine process.

testRecordData

protected TestRecordHelper testRecordData

Stores the data on the input record we are to process.

testrecordStackable

protected ITestRecordStackable testrecordStackable

The ITestRecordStackable used to store 'Test Record' in a FILO.

Constructor Detail

GenericEngine

public GenericEngine()

Constructor for GenericEngine

Method Detail

logMessage

protected void logMessage(java.lang.String msg,
                          java.lang.String msgdescription,
                          int msgtype)

Convenience routine for building the appropriate MessageInfo and logging a message to our active log. Consult the AbstractLogFacility for valid msgtype values.

See Also:

AbstractLogFacility

getEngineName

public java.lang.String getEngineName()

Description copied from interface: EngineInterface

Retrieve the name of the Engine. For example, SAFS/DriverCommands. For STAF engines, this would be the engine's process name in STAF.

Specified by:

getEngineName in interface EngineInterface

See Also:

EngineInterface.getEngineName()

processRecord

public long processRecord(TestRecordHelper testRecordData)

Initiate the event-driven protocol to send the test record to the engine. All official engines conform to this protocol. So this function rarely needs to be overridden..

Specified by:

processRecord in interface EngineInterface

Returns:

the status code resulting from the processing.

• 4 -- SCRIPT NOT EXECUTED. "I did not process this record."
• -1 -- NO SCRIPT FAILURE. "I processed the record successfully."
• -2 -- SCRIPT WARNING. "I processed the record, issued warning(s)."
• 0 -- SCRIPT FAILURE. "I processed the record, issued failure(s)."
• 2 -- IO FAILURE. "I process the record, issued IO failure(s)."
• 8 -- EXIT TABLE. "I processed the record, exit current table."
• 16 -- IGNORE STATUS. "I processed the record, ignore code and continue."

See Also:

EngineInterface#processRecord()

launchInterface

public void launchInterface(java.lang.Object configInfo)

Typically expects a DriverInterface object for initialization. Subclasses should indicate if an alternative type of object is required. This method will try to reset the "shutdown" semaphore remained by last hook shutdown.

Specified by:

launchInterface in interface ConfigurableToolsInterface

Overrides:

launchInterface in class DriverConfiguredSTAFInterfaceClass

Parameters:

configInfo - can be whatever the final implementation needs it to be. This might be a String with configuration information, the name of a class, or an instance of some object used to provide configuration assets.

See Also:

DriverConfiguredSTAFInterfaceClass.launchInterface(Object), DriverInterface

isToolRunning

public boolean isToolRunning()

Verifies a STAF tool matching our engine name is running.

Specified by:

isToolRunning in interface GenericToolsInterface

Overrides:

isToolRunning in class DriverConfiguredSTAFInterfaceClass

See Also:

GenericToolsInterface.isToolRunning()

makeQuotedString

protected java.lang.String makeQuotedString(java.lang.String text)

Wraps the privided text in double-quotes *if* the text contains a space.

Returns:

provided text item unmodified if null or no spaces found. New string wrapped in quotes if space(s) found.

makeQuotedPath

protected java.lang.String makeQuotedPath(java.lang.String path,
                                          boolean isFile)

Wraps valid file path in double-quotes if necessary.

Parameters:

path - to file or directory. Can be relative to the project root directory.

isFile - true if the path should be a file, instead of a directory.

Returns:

valid path quoted ONLY if it contains a space and was found to be a valid file or dir in the file system. Otherwise, we return null.

setTRDStatus

protected long setTRDStatus(TestRecordHelper trd,
                            long status)

Sets TRD statuscode to the provided status and returns the same. This is a convenience routine to do both in a single call.

return setTRDStatus(trd, status);

reset

public void reset()

Description copied from interface: GenericToolsInterface

Reset or clear any cached information in the underlying tool or service. The implementation should be able to recognize if the underlying tool or service is not actually running. If the tool is not running, then this should exit gracefully without adversely affecting anything.

Specified by:

reset in interface GenericToolsInterface

See Also:

GenericToolsInterface.reset()

saveTestRecordScreenToTestDirectory

protected java.lang.String saveTestRecordScreenToTestDirectory(TestRecordData testRecordData)

Normally called on failure to execute an IBT command. Gets the current IBT screen snapshot and saves it to file in the Datapool\Test directory. Saves it with testRecordData filename and linenumber info with a timestamp. Note: the output file format is normally JPG. However, if ImageUtils.debug is set to true then the image format will be BMP.

Parameters:

the - testRecordData containing the test FileID and test LineNumber for unique image naming.

Returns:

full filepath to saved snapshot

shutdownService

protected void shutdownService(java.lang.String aname)

Shutdown the Engine.

All official engines conform to the "SHUTDOWN_HOOK" TestRecordData method to initiate shutdown. So, this function rarely needs to be overridden.

Following the confirmation that the service or engine is no longer 'running', this implementation will call postShutdownServiceDelay() which is intended to allow subclasses to delay final shutdown of the process by an arbitrary length of time while internal shutdown activities are completed.

This implementation then resets "running" to false.

Unregistering staf and nulling superclass objects occurs in the finalize() method of the superclass.

Overrides:

shutdownService in class DriverConfiguredSTAFInterfaceClass

Parameters:

aname - is not used directly in this implementation.

See Also:

DriverConfiguredSTAFInterfaceClass.shutdownService(String)

waitHookShutdownAndReset

protected void waitHookShutdownAndReset(int timeoutInSeconds)

Called internally by shutdownService(String).

This method is intended to wait for the "shutdown" semaphore post by hook when it stops, then try to reset the "shutdown" semaphore. If we don't reset the "shutdown" semaphore, the driver may see this semaphore and consider that the hook is shutdown and return to try other engine/hook. This method can only try its best to reset "shutdown" semaphore, but this is not guaranteed.

Parameters:

timeoutInSeconds, - int, the timeout in seconds to wait for the "shutdown" semaphore

resetShutdownSemaphore

protected boolean resetShutdownSemaphore()

This method is intended to reset the "shutdown" semaphore post hook when it stops. Before we reset the "shutdown" semaphore, we should test the condition for resetting. The condition is that only "shutdown" is "posted", the others are "reset".

postShutdownServiceDelay

protected void postShutdownServiceDelay()

Called internally by shutdownService(String).

This method is intended to allow subclasses to delay final shutdown of the process by an arbitrary length of time while internal shutdown activities are completed.

This default implementation provides no delay and immediately returns.

setVariable

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

Description copied from interface: RuntimeDataInterface

Set a new runtime value of a global variable (SAFSVARS).

Specified by:

setVariable in interface RuntimeDataInterface

Parameters:

var - -- Variable names are NOT case-sensitive.

val - -- value to set. Can be an empty string.

Returns:

value of the variable after it has been set. can be null if the set was not successful or some other error occurred.

Throws:

SAFSException

getVariable

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

Description copied from interface: RuntimeDataInterface

Retrieve the current runtime value of the global variable (SAFSVARS).

Specified by:

getVariable in interface RuntimeDataInterface

Parameters:

var - -- Variable names are NOT case-sensitive.

Returns:

String value which can be a zero-length value. null if no such item was found or some type of error occurred during execution.

Throws:

SAFSException

deduceTestFile

protected java.io.File deduceTestFile(java.lang.String filename)
                               throws SAFSException

Deduce the absolute full path test file name.

Parameters:

filename, - String, the test file name.

Returns:

String, the absolute full path test file name.

Throws:

SAFSException

See Also:

#deduceFile(String, int)}

deduceBenchFile

protected java.io.File deduceBenchFile(java.lang.String filename)
                                throws SAFSException

Deduce the absolute full path bench file name.

Parameters:

filename, - String, the bench file name.

Returns:

String, the absolute full path bench file name.

Throws:

SAFSException

See Also:

#deduceFile(String, int)}

deduceProjectFile

protected java.io.File deduceProjectFile(java.lang.String filename)
                                  throws SAFSException

Deduce the absolute full path to a project-relative file.

Parameters:

filename, - String, the test file name. The path is ALWAYS considered relative to the project root directory regardless of the absence or presence of File.separators unless the file is already an absolute path.

Returns:

File, the absolute full path bench file.

Throws:

SAFSException

See Also:

#deduceFile(String, int)}

getAppMapItem

public java.lang.String getAppMapItem(java.lang.String appMapId,
                                      java.lang.String sectionName,
                                      java.lang.String itemName)
                               throws SAFSException

Description copied from interface: RuntimeDataInterface

Retrieve the resolved value of an item stored in the App Map chain (SAFSMAPS).

Specified by:

getAppMapItem in interface RuntimeDataInterface

Parameters:

appMapId - -- can be null to get from the "default/current" app map.

sectionName - -- section names are NOT case-sensitive.

itemName - -- item names are NOT case-sensitive.

Returns:

String value which can be a zero-length value. null if no such item was found or some type of error occurred during execution.

Throws:

SAFSException

pushTestRecord

public void pushTestRecord(TestRecordData trd)

Push the current 'test record' into the Stack before the execution of a keyword. This should be called after the 'test record' is properly set.

Specified by:

pushTestRecord in interface ITestRecordStackable

Parameters:

trd - TestRecordData, the test record to push into a stack

See Also:

popTestRecord()

popTestRecord

public TestRecordData popTestRecord()

Retrieve the Test-Record from the the Stack after the execution of a keyword.

After execution of a keyword, pop the test record from Stack and return is as the result. Replace the class field 'Test Record' by that popped from the stack if they are not same.

Specified by:

popTestRecord in interface ITestRecordStackable

Returns:

TestRecordData, the 'Test Record' on top of the stack

See Also:

#pushTestRecord()