org.safs.tools.drivers

Class STAFProcessContainerDriver

java.lang.Object

org.safs.tools.drivers.AbstractDriver

org.safs.tools.drivers.STAFProcessContainerDriver

All Implemented Interfaces:

DriverInterface, PathInterface, Versionable

public class STAFProcessContainerDriver
extends AbstractDriver

An implementation of AbstractDriver for use by STAFProcessContainer.

This class is intended to be used by STAFProcessContainer, but may be useful as a generic "driver" that can initialize and then shutdown tools needed by a SAFS-like Driver that is NOT necessarily running tests.

Sample Usage:

STAFProcessContainerDriver driver = new STAFProcessContainerDriver();
...
driver.initializeDriver();
...do stuff...
driver.shutdownDriver();

Command-line Options and Configuration File Options are linked below.

The default name of configuration files is "SAFSTID.INI". There is a hierarchy of configuration files that will be sought based on command-line parameters provided. This hierarchy is summarized in the Configuration File Options doc linked below and detailed below:

1. -Dsafs.project.config=c:\SAFSProject\ProcessContainer.INI
   command-line specified PROJECT config file
   a uniquely named config file, other than "SAFSTID.INI", containing config information intended to override settings in the default PROJECT config file located in the PROJECT ROOT directory.

2. default PROJECT config file
   "SAFSTID.INI" located in the PROJECT ROOT directory. The PROJECT ROOT would normally be provided as a command-line parameter. It may instead be provided in the previous specified UNIQUE config file. This file will normally contain settings specific to an entire project and these override any similar settings in the DRIVER config files.

3. command-line specified DRIVER config file
   Rarely used. A uniquely named config file, other than "SAFSTID.INI", intended to override settings in any SAFSTID.INI file located in the DRIVER ROOT directory.

4. default DRIVER config file
   SAFSTID.INI located in the DRIVER ROOT directory. The DRIVER ROOT would normally be provided in a previous config file or as a command-line parameter. This config file will contain the bulk of the configuration information that is specific to the driver and independent of any project or test being executed.

In general, you want to provide the bare minimum of command-line parameters and place all remaining info in one or more configuration files. The total of all command-line parameters and config file information must enable the driver to locate valid driver and project root directories, project subdirectories, and all other items necessary to find and configure tools. See the #initializeDriver() link below for all the neat things the driver will do during initialization!

An example invocation, providing the bare minimum command-line parameters:

java -Dsafs.project.config=c:\SAFSProject\ProcessContainer.INI SomeProcessContainerImplementation

This then expects ProcessContainer.INI to contain the information concerning which engines to run, and where the PROJECT ROOT and maybe the DRIVER ROOT directories are located. The remaining configuration information can reside in SAFSTID.INI files located in these directories.

Sample ProcessContainer.INI in c:\SAFSProject:

 [SAFS_PROJECT]
 ProjectRoot="C:\safsproject"

 [SAFS_ENGINES]
 First=org.safs.tools.engines.SAFSSELENIUM

 [SAFS_SELENIUM]
 AUTOLAUNCH=TRUE;
 

Sample SAFSTID.INI in c:\SAFSProject used by 2default:

 [SAFS_DRIVER]
 DriverRoot="C:\safs"

 [SAFS_MAPS]
 AUTOLAUNCH=TRUE

 [SAFS_INPUT]
 AUTOLAUNCH=TRUE

 [SAFS_VARS]
 AUTOLAUNCH=TRUE

 [SAFS_LOGS]
 AUTOLAUNCH=TRUE
 

And that is enough for the driver to configure the environment.

Of course, more of the configuration parameters necessary for desired engines will have to be in those configuration files once the engines actually become available.

See Also:

initializeDriver(), Command-Line Options, Configuration File Options

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_STAF_PROCESS_CONTAINER_DRIVER "STAFProcessContainerDriver"
protected java.lang.String	driverConfigPath
protected java.util.Hashtable	engineObjects Stores ALL instanced EngineInterface objects in classname=engine format.
protected java.util.Vector	enginePreference Stores only active 'preferred' engine class names in preferred order.
protected java.util.Vector	engines Stores ALL instanced EngineInterface objects in instanced order.
protected ConfigureLocatorInterface	locator
protected java.lang.String	projectConfigPath

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

autoitcomponent, benchSource, configInfo, core, counterInfo, counts, cycleflowcontrol, cycleLinkedFac, cycleLogMode, cycleLogName, cycleSeparator, cycleSuffix, datapoolSource, debug, description, difSource, driverName, driverRootDir, embeddedEngines, exitCycle, exitSuite, expressionsOn, input, ipcommands, logLevel, logs, logsSource, maps, millisBetweenRecords, orderable, perTableFlowControl, productName, projectRootDir, safsDataServiceID, statuscounts, stepflowcontrol, stepLinkedFac, stepLogMode, stepLogName, stepSeparator, stepSuffix, suiteflowcontrol, suiteLinkedFac, suiteLogMode, suiteLogName, suiteSeparator, suiteSuffix, testLevel, testName, testSource, tidcommands, tidcomponent, vars, verifySource, version

Fields inherited from interface org.safs.tools.drivers.DriverInterface

DRIVER_CONTROL_POF_VAR, DRIVER_CONTROL_POW_VAR, DRIVER_CONTROL_VAR

Constructor Summary

Constructors

Constructor and Description
STAFProcessContainerDriver() Default Constructor used by STAFProcessContainer.
STAFProcessContainerDriver(java.lang.String drivername)

Method Summary

Modifier and Type	Method and Description
protected void	addConfigureInterfaceSource(ConfigureInterface source) Initialize or append a ConfigureInterface to existing ones in the search order.
void	clearEnginePreferences()
void	endEnginePreference(java.lang.String key)
protected ConfigureLocatorInterface	getConfigureLocator(java.lang.String locatorInfo) Locate a ConfigureLocatorInterface given the locatorInfo, presumably provided from command-line options.
protected EngineInterface	getEngineInterface(java.lang.String itemName) Locate an EngineInterface given the engine priority string as defined in the documented Configuration File standard for SAFS_ENGINES.
java.util.ListIterator	getEnginePreferences()
java.util.ListIterator	getEngines()
protected java.lang.String	getFullEngineClass(java.lang.String key) used internally to find the validity of an engine name
protected GenericToolsInterface	getGenericInterface(java.lang.String configSection, java.lang.String defaultInterface) Attempts to dynamically create a newInstance of a GenericToolsInterface object.
EngineInterface	getPreferredEngine(java.lang.String key)
protected int	getPreferredEngineIndex(java.lang.String key) used internally to find the index of an engine marked as "preferred"
boolean	hasEnginePreferences()
void	initializeDriver() Bootstrap a newly instanced driver.
protected void	initializePresetVariables() Initialize any preset variables such as known project directories, etc.
protected void	initializeRuntimeEngines() Instantiate and initialize any EngineInterface classes (up to 10)listed in the SAFS_ENGINE section of the Configuration Source.
protected void	initializeRuntimeInterface() Initialize all the Driver/Engine interfaces as specified by the config files or driver defaults.
protected void	insertConfigureInterfaceSource(ConfigureInterface source) Initialize or insert a ConfigureInterface at the start of the search order.
boolean	isPreferredEngine(EngineInterface engine)
boolean	isPreferredEngine(java.lang.String key)
protected StatusInterface	processTest() We do nothing here but return a newly initialized (empty) StatusInfo object.
void	shutdownDriver() Calls: shutdownRuntimeEngines() shutdownRuntimeInterface()
protected void	shutdownRuntimeEngines() shutdown any engines started with initializeRuntimeEngines()
protected void	shutdownRuntimeInterface() shutdown GenericToolsInterfaces started with initializeRuntimeInterfaces()
void	startEnginePreference(java.lang.String key)

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

addEmbeddedEngine, addStatusCounts, collectEngines, collectFramework, collectHistory, collectMachine, collectUser, connectSAFSDataService, disconnectSAFSDataService, getAutoItComponentSupport, getBenchDir, getConfigureInterface, getCoreInterface, getCountersInterface, getCycleLogMode, getCycleLogName, getCycleSeparator, getCycleSuffix, getDatapoolDir, getDebugInterface, getDescription, getDifDir, getDriverName, getDriverRootDir, getEmbeddedEngines, getFlowControlInterface, getInputInterface, getIPDriverCommands, getLogLevel, getLogsDir, getLogsInterface, getMapsInterface, getMillisBetweenRecords, getParameterValue, getProductName, getProjectDirectoryInfo, getProjectRootDir, getRootDirectoryInfo, getRootVerifyDir, getStatusInterface, getStepLogMode, getStepLogName, getStepSeparator, getStepSuffix, getSuiteLogMode, getSuiteLogName, getSuiteSeparator, getSuiteSuffix, getTestDir, getTestLevel, getTestName, getTIDDriverCommands, getTIDGUIlessComponentSupport, getVarsInterface, getVersion, incrementGeneralStatus, incrementTestStatus, isExitCycle, isExitSuite, isExpressionsEnabled, isModifiedConfig, isModifiedRoot, isPerTableFlowControl, logMessage, phoneHome, phoneHome, processEmbeddedVariable, resetModifiedProperties, setBenchDir, setDatapoolDir, setDescription, setDifDir, setExitCycle, setExitSuite, setExpressionsEnabled, setLogsDir, setMillisBetweenRecords, setPerTableFlowControl, setProductName, setProjectRootDir, setRootVerifyDir, setTestDir, setVersion, validateRootConfigureParameters

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_STAF_PROCESS_CONTAINER_DRIVER

public static final java.lang.String DEFAULT_STAF_PROCESS_CONTAINER_DRIVER

"STAFProcessContainerDriver"

See Also:

Constant Field Values

locator

protected ConfigureLocatorInterface locator

engines

protected java.util.Vector engines

Stores ALL instanced EngineInterface objects in instanced order.

enginePreference

protected java.util.Vector enginePreference

Stores only active 'preferred' engine class names in preferred order.

engineObjects

protected java.util.Hashtable engineObjects

Stores ALL instanced EngineInterface objects in classname=engine format.

driverConfigPath

protected java.lang.String driverConfigPath

projectConfigPath

protected java.lang.String projectConfigPath

Constructor Detail

STAFProcessContainerDriver

public STAFProcessContainerDriver()

Default Constructor used by STAFProcessContainer.

Once instantiated, the user must still call initializeDriver() to commence complete initialization of the driver and configured tools for use.

Once the user is finished with all driver functionality and tools the user must call shutdownDriver() to shutdown all configured tools and the driver itself.

Sample Usage:

STAFProcessContainerDriver driver = new STAFProcessContainerDriver();
...
driver.initializeDriver();
...do stuff...
driver.shutdownDriver();

STAFProcessContainerDriver

public STAFProcessContainerDriver(java.lang.String drivername)

Method Detail

getEngines

public java.util.ListIterator getEngines()

See Also:

DriverInterface.getEngines()

getEnginePreferences

public java.util.ListIterator getEnginePreferences()

See Also:

DriverInterface.getEnginePreferences()

getPreferredEngineIndex

protected int getPreferredEngineIndex(java.lang.String key)

used internally to find the index of an engine marked as "preferred"

getFullEngineClass

protected java.lang.String getFullEngineClass(java.lang.String key)
                                       throws java.lang.IllegalArgumentException

used internally to find the validity of an engine name

Throws:

java.lang.IllegalArgumentException

getPreferredEngine

public EngineInterface getPreferredEngine(java.lang.String key)
                                   throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

See Also:

DriverInterface.getPreferredEngine(String)

hasEnginePreferences

public boolean hasEnginePreferences()

See Also:

DriverInterface.hasEnginePreferences()

startEnginePreference

public void startEnginePreference(java.lang.String key)
                           throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

See Also:

DriverInterface.startEnginePreference(String)

endEnginePreference

public void endEnginePreference(java.lang.String key)
                         throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

See Also:

DriverInterface.endEnginePreference(String)

clearEnginePreferences

public void clearEnginePreferences()

See Also:

DriverInterface.clearEnginePreferences()

isPreferredEngine

public boolean isPreferredEngine(java.lang.String key)
                          throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

See Also:

DriverInterface.isPreferredEngine(String)

isPreferredEngine

public boolean isPreferredEngine(EngineInterface engine)
                          throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

See Also:

DriverInterface.isPreferredEngine(EngineInterface)

getEngineInterface

protected EngineInterface getEngineInterface(java.lang.String itemName)

Locate an EngineInterface given the engine priority string as defined in the documented Configuration File standard for SAFS_ENGINES. (Ex: "First", "Second", etc.)

Returns:

an EngineInterface or null if not found or instantiated.

getConfigureLocator

protected ConfigureLocatorInterface getConfigureLocator(java.lang.String locatorInfo)

Locate a ConfigureLocatorInterface given the locatorInfo, presumably provided from command-line options.

Overrides:

getConfigureLocator in class AbstractDriver

Throws:

java.lang.IllegalArgumentException - if appropriate locator class cannot be instantiated.

addConfigureInterfaceSource

protected void addConfigureInterfaceSource(ConfigureInterface source)

Initialize or append a ConfigureInterface to existing ones in the search order.

Overrides:

addConfigureInterfaceSource in class AbstractDriver

insertConfigureInterfaceSource

protected void insertConfigureInterfaceSource(ConfigureInterface source)

Initialize or insert a ConfigureInterface at the start of the search order.

getGenericInterface

protected GenericToolsInterface getGenericInterface(java.lang.String configSection,
                                                    java.lang.String defaultInterface)
                                             throws java.lang.ClassNotFoundException,
                                                    java.lang.IllegalAccessException,
                                                    java.lang.InstantiationException

Attempts to dynamically create a newInstance of a GenericToolsInterface object. The process first tries to locate the fully qualified name of the Class through the ConfigureInterface using the provided configSection name and the value of "Item" in that config section. Example below shows a config file containing a section called "ToolHelper":

[ToolHelper]
Item="My.Generic.Tools.Interface.Helper"

If no such section exists in config, or no "Item" value is found, then the routine will attempt to instantiate the defaultInterface provided.

Parameters:

String - configSection -- Named section of configuration file(s) potentially containing the Name=Value pair of Item=My.Full.Classname.

String - defaultInterface -- fully qualified classname of class to instantiate if no config file information is found.

Throws:

java.lang.ClassNotFoundException, - java.lang.IllegalAccessException, java.lang.InstantiationException

java.lang.ClassNotFoundException

java.lang.IllegalAccessException

java.lang.InstantiationException

See Also:

Class.forName(String)

initializeRuntimeInterface

protected void initializeRuntimeInterface()

Initialize all the Driver/Engine interfaces as specified by the config files or driver defaults. This driver passes itself (a DriverInterface) to all Configurable tools it instances.

Calls:
• input.launchInterface(this)
• maps.launchInterface(this)
• vars.launchInterface(this)
• logs.launchInterface(this)
• counts.launchInterface(this)

Throws:

java.lang.IllegalArgumentException - if problems arise during initialization.

initializeRuntimeEngines

protected void initializeRuntimeEngines()

Instantiate and initialize any EngineInterface classes (up to 10)listed in the SAFS_ENGINE section of the Configuration Source.

Also instantiates internal tools.engines.TIDDriverCommands in-process support.

This driver passes itself--a DriverInterface object--to each instanced engine.

See Also:

org.safs.tools.engines.TIDDriverCommands(DriverInterface)

initializePresetVariables

protected void initializePresetVariables()

Initialize any preset variables such as known project directories, etc.

Known preset variables are:

• "SAFSPROJECTDIRECTORY" -- Root project directory: "C:\MyProject"
• "SAFSDATAPOOLDIRECTORY" -- Project Datapool directory: "C:\MyProject\Datapool"
• "SAFSBENCHDIRECTORY" -- Project Bench directory: "C:\MyProject\Datapool\Bench"
• "SAFSTESTDIRECTORY" -- Project Test\Actual directory: "C:\MyProject\Datapool\Test"
• "SAFSDIFDIRECTORY" -- Project Dif directory: "C:\MyProject\Datapool\Dif"
• "SAFSLOGSDIRECTORY" -- Project Logs directory: "C:\MyProject\Datapool\Logs"
• "SAFSSYSTEMUSERID" -- UserID of the person\account logged onto the system.

shutdownRuntimeEngines

protected void shutdownRuntimeEngines()

shutdown any engines started with initializeRuntimeEngines()

shutdownRuntimeInterface

protected void shutdownRuntimeInterface()

shutdown GenericToolsInterfaces started with initializeRuntimeInterfaces()

Calls:
• input.shutdown()
• vars.shutdown()
• maps.shutdown()
• counts.shutdown()
• logs.shutdown()

processTest

protected StatusInterface processTest()

We do nothing here but return a newly initialized (empty) StatusInfo object. Required to extend AbstractDriver.

Specified by:

processTest in class AbstractDriver

See Also:

AbstractDriver.processTest(), org.safs.tools.status.StatusInfo()

initializeDriver

public void initializeDriver()

Bootstrap a newly instanced driver. The routine calls all the other routines to prepare the driver and configure tools.

This routine must be overridden by subclasses if they wish to change default start-to-finish execution flow.

The model for overall driver operation is that any command-line arguments or configuration file arguments that prevent normal execution will generate an IllegalArgumentException. Those IllegalArgumentExceptions are caught here and sent to stderr output and then rethrown. Any Exception will invoke shutdownDriver(). We immediately return from this function.

Calls:
• #validateRootConfigureParameters()
• initializeRuntimeInterface()
• initializeRuntimeEngines()

Throws:

java.lang.IllegalArgumentException

See Also:

shutdownDriver()

shutdownDriver

public void shutdownDriver()

Calls:
• shutdownRuntimeEngines()
• shutdownRuntimeInterface()