org.safs.tools.drivers

Class EmbeddedHookDriver

java.lang.Object

org.safs.JavaHook

org.safs.tools.drivers.EmbeddedHookDriver

All Implemented Interfaces:

HookConfig

Direct Known Subclasses:

EmbeddedDCHookDriver, EmbeddedSeleniumHookDriver

public class EmbeddedHookDriver
extends JavaHook

Allows custom JSAFS test development and execution inside a Java-based SAFS Engine. Java-based SAFS Engines would need to implement an engine-specific subclass of this EmbeddedHookDriver using a EmbeddedHookSTAFHelper to take advantage of this feature.

Usage is expected to be:

 EmbeddedHookDriverSubclass hook = new EmbeddedHookDriverSubclass("UniqueName");
 hook.run();
 ..do stuff
 hook.shutdown();
 

It is important to note that the JVM arg -Dsafs.project.config is now optional. It is also possible to use -Dtestdesigner.project.config, or nothing. If neither is provided, the engine will look for a "test.ini" file in the startup working directory and also initially assume that might also be the Project Root directory.

Author:

Carl Nagle

Field Summary

Fields

Modifier and Type	Field and Description
(package private) EmbeddedHookDriver	hook
static java.lang.String	HOOK_DRIVER_NAME
(package private) java.lang.Thread	hookThread
(package private) JSAFSDriver	jsafs
static java.lang.String	SAFS_PROJECT_CONFIG "safs.project.config" System Property identifying the path to an alternate project configuration file (other than safstid.ini in the default project configuration location. JVM command line: -Dsafs.project.config=string|path
static java.lang.String	TEST_INI_DEFAULT "test.ini" Default project's Configuration filename.
static java.lang.String	TESTDESIGNER_PROJECT_CONFIG "testdesigner.project.config" System Property identifying the path to an alternate project configuration file (other than safstid.ini in the default project configuration location. This property has a higher priority than SAFS_PROJECT_CONFIG, if both of them are specified, then its value will be used. JVM command line: -Dtestdesigner.project.config=string|path

Fields inherited from class org.safs.JavaHook

data, DEBUG_MESSAGE, errorText, FAILED_MESSAGE, FAILED_OK_MESSAGE, GENERIC_ERROR, GENERIC_MESSAGE, helper, hookconfig, log, PASSED_MESSAGE, PAUSE_EXECUTION, PAUSE_SWITCH_OFF, PAUSE_SWITCH_ON, process_name, processor, REQUEST_PROCEED_TESTING, REQUEST_USER_STOPPED_SCRIPT_REQUEST, RUNNING_EXECUTION, semaphore_name, SHUTDOWN_RECORD, STAF_ERROR, STEP_EXECUTION, STEP_RETRY_EXECUTION, STEPPING_EXECUTION, STEPPING_RETRY_EXECUTION, trd_name, utils, WARNING_MESSAGE, WARNING_OK_MESSAGE

Constructor Summary

Constructors

Constructor and Description
EmbeddedHookDriver() Instantiates a default instance with a default "EmbeddedHookDriver" engine name.
EmbeddedHookDriver(java.lang.String engineName) Instantiate an instance using the provided engineName.
EmbeddedHookDriver(java.lang.String engineName, LogUtilities log) Instantiate an instance using the provided engineName and LogUtilities Calls initialize()

Method Summary

Modifier and Type	Method and Description
protected boolean	allowSystemExit() Evaluate if the runtime hook should exit with System.exit(0).
protected ConfigureInterface	config() return the Configure object so that subclass can get data from configuration files.
protected long	evaluateRuntimeException(java.lang.RuntimeException ex) Evaluate if the runtime hook should shutdown or continue.
protected Processor	getEngineDriverCommandProcessor() Subclasses should instantiate an engine-specific DriverCommands Processor here.
protected Processor	getEngineEngineCommandProcessor() Subclasses should instantiate an engine-specific EngineCommandProcessor Processor here, if any.
protected Processor	getEngineTestStepProcessor() Subclasses should instantiate an engine-specific TestStepProcessor Processor here, if any.
DDGUIUtilities	getGUIUtilities() Subclasses should override this method to retrieve/create the DDGUIUtilities instance needed by the specific engine subclass.
LogUtilities	getLogUtilities() Use this method to retrieve/create the current/default LogUtilities instance.
ProcessRequest	getRequestProcessor() This method to retrieve/create the current/default ProcessRequest instance.
TestRecordHelper	getTRDData() Retrieve the TestRecordHelper used by the subclass. This will almost always be overridden by an engine-specific subclass.
protected void	initConfigPaths() Override the superclass's method, try to use the existing Configuration of the embedded driver.
protected void	initialize() Called automatically by the 3 Constructors.
JSAFSDriver	jsafs() Return the embedded JSAFSDriver (for advanced users).
void	run() Called to initialize the EmbeddedDriver and make it ready for use.
void	setHelper(java.lang.Object processhelper) Set our STAFHelper to be the one provided.
protected void	setProcessName(java.lang.String process_name) Override superclass to delay STAFHelper initialization.
boolean	shutdown() Perform final engine hook shutdown activities AND shutdown the internal JSAFSDriver.
void	start() Insert this SAFS Engine hook into the STAF system.

Methods inherited from class org.safs.JavaHook

checkConfiguration, driverShutdownRequest, getHelper, getProcessName, getSemaphoreName, getTRDName, hook_shutdown, instantiateHookConfig, setGUIUtilities, setLogUtilities, setRequestProcessor, setSemaphoreName, setTRDData, setTRDName

Methods inherited from class java.lang.Object

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

Field Detail

SAFS_PROJECT_CONFIG

public static final java.lang.String SAFS_PROJECT_CONFIG

"safs.project.config"
System Property identifying the path to an alternate project configuration file (other than safstid.ini in the default project configuration location.
JVM command line: -Dsafs.project.config=string|path

See Also:

Constant Field Values

TESTDESIGNER_PROJECT_CONFIG

public static final java.lang.String TESTDESIGNER_PROJECT_CONFIG

"testdesigner.project.config"
System Property identifying the path to an alternate project configuration file (other than safstid.ini in the default project configuration location.
This property has a higher priority than SAFS_PROJECT_CONFIG, if both of them are specified, then its value will be used.
JVM command line: -Dtestdesigner.project.config=string|path

See Also:

Constant Field Values

TEST_INI_DEFAULT

public static final java.lang.String TEST_INI_DEFAULT

"test.ini"
Default project's Configuration filename.

See Also:

Constant Field Values

jsafs

JSAFSDriver jsafs

hook

EmbeddedHookDriver hook

HOOK_DRIVER_NAME

public static final java.lang.String HOOK_DRIVER_NAME

See Also:

Constant Field Values

hookThread

java.lang.Thread hookThread

Constructor Detail

EmbeddedHookDriver

public EmbeddedHookDriver()

Instantiates a default instance with a default "EmbeddedHookDriver" engine name. Calls initialize()

See Also:

JavaHook.JavaHook(String), initialize()

EmbeddedHookDriver

public EmbeddedHookDriver(java.lang.String engineName)

Instantiate an instance using the provided engineName. Calls initialize()

Parameters:

engineName - process_name to use for the driver/engine STAF connection.

See Also:

JavaHook.JavaHook(String), initialize()

EmbeddedHookDriver

public EmbeddedHookDriver(java.lang.String engineName,
                          LogUtilities log)

Instantiate an instance using the provided engineName and LogUtilities Calls initialize()

Parameters:

engineName - process_name to use for the driver/engine STAF connection.

LogUtilities - to use.

See Also:

JavaHook.JavaHook(String, LogUtilities), initialize()

Method Detail

initialize

protected void initialize()

Called automatically by the 3 Constructors. Subclasses may wish to override or extend this initialization.

sets the local hook field to the current hook driver instance and creates the internal JSAFSDriver instance.

See Also:

setHelper(Object)

jsafs

public JSAFSDriver jsafs()

Return the embedded JSAFSDriver (for advanced users).

Returns:

JSAFSDriver -- can be null if not yet initialized.

config

protected ConfigureInterface config()

return the Configure object so that subclass can get data from configuration files.

Returns:

ConfigureInterface -- the Configure object

getTRDData

public TestRecordHelper getTRDData()

Retrieve the TestRecordHelper used by the subclass.
This will almost always be overridden by an engine-specific subclass.

If no TestRecordHelper has been set (data == null), then the implementation is expected to instantiate and return a TestRecordHelper instance appropriate for the engine.

A newly instantiated TestRecordHelper should have critical helpers set:

• data.setSTAFHelper(getHelper());
• data.setDDGUtils(getGUIUtilities());

Specified by:

getTRDData in class JavaHook

getGUIUtilities

public DDGUIUtilities getGUIUtilities()

Subclasses should override this method to retrieve/create the DDGUIUtilities instance needed by the specific engine subclass.

A newly instantiated DDGUIUtilities should have critical helpers set:

• utils.setSTAFHelper(getHelper());
• utils.setTestRecordData(getTRDData());

Note that the call to getTRDData() may force the instantiation of the default TestRecordHelper if one has not already been set.

Specified by:

getGUIUtilities in class JavaHook

Returns:

DDGUIUtilities which should be an instanceof org.safs.DDGUIUtilities subclass. This default superclass implementation instantiates a DCGUIUtilities object that cannot act on GUI components.

See Also:

JavaHook.getHelper(), getTRDData(), DCGUIUtilities

getLogUtilities

public LogUtilities getLogUtilities()

Use this method to retrieve/create the current/default LogUtilities instance. If the LogUtilities has not been set this routine will instance a new org.safs.LogUtilities.

Specified by:

getLogUtilities in class JavaHook

Returns:

LogUtilities which should be an instanceof org.safs.LogUtilities.

See Also:

JavaHook.getLogUtilities(), org.safs.LogUtilities

getEngineDriverCommandProcessor

protected Processor getEngineDriverCommandProcessor()

Subclasses should instantiate an engine-specific DriverCommands Processor here. Other generic SAFS DriverCommand Processors will get chained to this primary Processor.

Returns:

Engine-specific DriverCommands Processor instance, or null.

getEngineTestStepProcessor

protected Processor getEngineTestStepProcessor()

Subclasses should instantiate an engine-specific TestStepProcessor Processor here, if any. Other generic SAFS Processors, if any, will get chained to this primary Processor.

Returns:

Engine-specific TestStepProcessor Processor instance, or null.

getEngineEngineCommandProcessor

protected Processor getEngineEngineCommandProcessor()

Subclasses should instantiate an engine-specific EngineCommandProcessor Processor here, if any. Other generic SAFS Processors, if any, will get chained to this primary Processor.

Returns:

Engine-specific EngineCommandProcessor Processor instance, or null.

getRequestProcessor

public ProcessRequest getRequestProcessor()

This method to retrieve/create the current/default ProcessRequest instance. The user would not normally call or override this routine as it will be called internally.

If the ProcessRequest has not been set this routine will instance a new org.safs.ProcessRequest and populate it with the LogUtilities via getLogUtilities(), a TestRecordHelper via getTRDData(), and all Processors.

Any newly created ProcessRequest instance will invoke:

getEngineDriverCommandProcessor()
getEngineTestStepProcessor()
getEngineEngineCommandProcessor()

and attempt to initialize all Processors with the getLogUtilities() and getTRDData() calls and then chain all Processors appropriately.

Note that the first call to getTRDData() may force the instantiation of the default TestRecordHelper for the subclass, if one has not already been set.

The first call to getLogUtilities() may also force the instantiation of the default LogUtilities, if one has not already been set.

Specified by:

getRequestProcessor in class JavaHook

Returns:

ProcessRequest which should be an instanceof org.safs.ProcessRequest

See Also:

TestRecordHelper, getTRDData(), getLogUtilities(), org.safs.LogUtilities, getEngineDriverCommandProcessor(), getEngineTestStepProcessor(), getEngineEngineCommandProcessor()

setProcessName

protected void setProcessName(java.lang.String process_name)

Override superclass to delay STAFHelper initialization.

Overrides:

setProcessName in class JavaHook

setHelper

public void setHelper(java.lang.Object processhelper)

Set our STAFHelper to be the one provided. Optionally, the input parameter can be a String which represents the process name for the desired STAFHelper (that may or may not exist).

The user can initialize both the process name and the STAFHelper by calling this routine with a valid process name String or STAFHelper.

If the current instance already has a defined process name, then any process name provided here is ignored and the STAFHelper is initialized with the existing value.

If the user provides a valid STAFHelper; then the process_name will be set to the name used to create the STAFHelper.

NOTE: This will automatically reset the semaphore_name to be the same as the process_name. This is the default mode of operation and should be OK for most applications. However, if the semaphore_name is to be different, then you must also call setSemaphoreName after this call.

Overrides:

setHelper in class JavaHook

Parameters:

processhelper - -- Object: String process name used to create/retrieve a STAFHelper; or an already instanced STAFHelper object.

Throws:

java.lang.NullPointerException - (with message) -- if null is provided.

initConfigPaths

protected void initConfigPaths()

Override the superclass's method, try to use the existing Configuration of the embedded driver. If the existing Configuration is null, then call method of superclass.

Overrides:

initConfigPaths in class JavaHook

See Also:

DriverConstant.PROPERTY_SAFS_CONFIG_PATHS, ConfigureInterface, TestRecordHelper.setConfig(ConfigureInterface), TestRecordHelper.getConfig()

start

public void start()

Description copied from class: JavaHook

Insert this SAFS Engine hook into the STAF system. The hook will then be enabled and ready for test events from any STAF client using the correct Event protocols.

Overrides:

start in class JavaHook

evaluateRuntimeException

protected long evaluateRuntimeException(java.lang.RuntimeException ex)

Evaluate if the runtime hook should shutdown or continue. Currently, we only suggest shutdown on a USER_STOPPED_SCRIPT_REQUEST-- which can be initiated by the SAFS Monitor or the value of the safs_driver_control variable.

Overrides:

evaluateRuntimeException in class JavaHook

run

public void run()

Called to initialize the EmbeddedDriver and make it ready for use. The user is expected to call shutdown() when testing is completed.

Invokes:

See Also:

org.safs.tools.drivers.JSAFSDriver#removeShutdownHook()
, org.safs.tools.drivers.JSAFSDriver#validateRootConfigureParameters(boolean)
, org.safs.tools.drivers.JSAFSDriver#validateLogParameters()
, org.safs.tools.drivers.JSAFSDriver#initializeRuntimeInterface()
, org.safs.tools.drivers.JSAFSDriver#initializePresetVariables()
, org.safs.tools.drivers.JSAFSDriver#initializeMiscConfigInfo()
, org.safs.tools.drivers.JSAFSDriver#initializeRuntimeEngines()
, org.safs.tools.drivers.JSAFSDriver#openTestLogs()
, org.safs.tools.drivers.JSAFSDriver#statuscounter


allowSystemExit

protected boolean allowSystemExit()

Description copied from class: JavaHook

Evaluate if the runtime hook should exit with System.exit(0).

The default implementation will return true allowing the System.exit(0). Subclasses may wish to override this function to prevent the execution of System.exit(0) when this is not appropriate.

Overrides:

allowSystemExit in class JavaHook

shutdown

public boolean shutdown()

Perform final engine hook shutdown activities AND shutdown the internal JSAFSDriver. This should shutdown all SAFS logs and services started by this process.

This default implementation unregisters our STAFProcessHelper if it is not null. Subclasses may wish to provide additional functionality before calling super.shutdown().

Returns:

The default implementation will return true if no errors or exceptions are uncaught.