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

Direct Known Subclasses:

SAFSABBOT, SAFSDRIVERCOMMANDS, SAFSDROID, SAFSIOS, SAFSJREX, SAFSQTP, SAFSROBOTCLASSIC, SAFSROBOTJ, SAFSSELENIUM, SAFSTC, TIDComponent, TIDDriverCommands, TIDDriverCounterCommands, TIDDriverFlowCommands, TIDDriverLogCommands

public class GenericEngine
extends DriverConfiguredSTAFInterfaceClass
implements EngineInterface

Field Summary

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.

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

GenericEngine()
Constructor for GenericEngine

Method Summary

java.lang.String	getEngineName() Retrieve the name of the Engine.
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.
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	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.
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

extendedGenericMessage, finalize, getSTAFHelper, logMessage, setLogUtilities, shutdown, simpleGenericMessage, simpleGenericSuccessMessage, simpleGenericWarningMessage, simpleSuccessMessage, simpleSuccessMessage, simpleSuccessUsingMessage, standardErrorMessage

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

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.

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.