org.safs.tools.drivers

Class DriverConfiguredSTAFInterfaceClass

java.lang.Object

org.safs.tools.drivers.DriverConfiguredSTAFInterfaceClass

All Implemented Interfaces:

ConfigurableToolsInterface, GenericToolsInterface

Direct Known Subclasses:

GenericEngine, SAFSINPUT, SAFSLOGS, SAFSMAPS, SAFSVARS, STAFLocalServer

public abstract class DriverConfiguredSTAFInterfaceClass
extends java.lang.Object
implements ConfigurableToolsInterface

Provides a generic, incomplete implementation of a ConfigurableToolsInterface that requires or expects a DriverInterface as the object used to access configuration information.

It provides the generic tasks of registering with STAF using the Driver's name as the process name needed by STAF. It does this through the STAFProcessHelpers class so that all associated tools in the process can use the same process name.

Any attempt to launchInterface through this class will also trigger the verification that STAF is running. If it is not, the instance will attempt to launch STAF automatically. Configuration information can be provided via the ConfigureInterface as shown below. Default values will be used if not provided.

 [STAF]
 PATH=Full path to/STAFProc     (or bat, script, etc.)
 CONFIG=Full path to/yourCustom.CFG
 EMBEDSEM=TRUE
 

The provided finalizer will unRegister the instance with the STAFProcessHelpers class to retain proper reference counts in STAFProcessHelpers.

Author:

Carl Nagle JAN 27, 2005 Made STAFProc constant compatible with Linux/Unix, Carl Nagle DEC 14, 2005 Refactored to support STAF shutdown if weStartedSTAF, Carl Nagle AUG 11, 2008 Doubled the time to wait for STAFServiceLoader to come online., LEWANG AUG 23, 2010 Add a field LogUtilities: If we can't initialize an engine with a driver, we need to set this field to keep working the log Message. Add method logMessage(): It will try driver's LogsInterface to log Message; If the driver is null, it will try the LogUtilities to log Message., Carl Nagle NOV 13, 2014 Fixed logMessage to try LogUtilities before Driver to get Console logging.

Field Summary

Fields

Modifier and Type	Field and Description
protected ConfigureInterface	config The ConfigurInterface extracted from the Driver for easy access.
protected static java.lang.String	customStr empty.
protected static GetText	customText GetText instance handling CUSTOM text resources.
protected static java.lang.String	debugStr empty.
protected static GetText	debugText GetText instance handling DEBUG text resources.
protected DriverInterface	driver The DriverInterface used for all configuration information.
static java.lang.String	DRIVER_TEMP_PROCESS "SAFS_DCSIC_PING".
protected static java.lang.String	failedStr "failed".
protected static GetText	failedText GetText instance handling FAILED text resources.
protected static java.lang.String	genericStr empty.
protected static GetText	genericText GetText instance handling GENERIC text resources.
protected long	launchCount Tracking how many launchInterface calls processed.
protected LogUtilities	log This LogUtilities is set for logging message if the DriverInterface can't be initialized.
protected java.lang.String	machine The "where" of our associated STAF service for this instance.
protected static java.lang.String	otherStr empty.
protected static GetText	otherText GetText instance handling ?OTHER? text resources?
protected static java.lang.String	passedStr empty.
protected static GetText	passedText GetText instance handling PASSED text resources.
protected java.lang.String	processName The stored DriverName.
protected boolean	running true if the client was running or successfully launched.
static java.lang.String	SAFS_RESBUN_NAME "SAFSTextResourceBundle"
protected java.lang.String	servicename Storage for STAF service\client name
protected long	shutdownCount Track how many things must be shutdown before we can attempt to shutdown STAF.
protected STAFHelper	staf The STAFHelper retrieved from STAFProcessHelpers during the call to launchInterface.
static java.lang.String	STAFPROC_EXE "STAFProc".
protected static java.lang.String	warningStr "failed".
protected static GetText	warningText GetText instance handling WARNING text resources.
protected boolean	weStartedService Flag to record whether the associated STAF service was started by this instance (true); or if it was found already running (false).
protected static boolean	weStartedSTAF Flag to record whether this JVM (DRIVER) started STAF.

Constructor Summary

Constructors

Constructor and Description
DriverConfiguredSTAFInterfaceClass() Constructor for DriverConfiguredInterfaceClass

Method Summary

Modifier and Type	Method and Description
java.lang.String	configureJSTAFServiceEmbeddedJVMOption(java.lang.String options) Configure SAFS Services to use the embedded 32-bit JVM if:
protected void	extendedGenericMessage(TestRecordData testRecordData, java.lang.String note, java.lang.String detail) Log an extended GENERIC_MESSAGE including filename, linenumber, and detail.
protected void	finalize() finalize if we are ever destroyed without the JVM shutting down.
CoreInterface	getCoreInterface() Retrieve the instance of the CoreInterface used to communicate with the framework.
java.io.File	getEmbeddedJVMBinPath() See if SAFS has an embedded JVM with it.
void	getSTAFHelper() Get our STAFProcessHelper.
boolean	isToolRunning() TRUE if the underlying tool is running.
void	launchInterface(java.lang.Object configInfo) Generic extraction of Driver, Config, and STAFHelper objects.
void	logMessage(UniqueStringMessageInfo info) This method will use try to use the LogUtilities to log message first.
void	setLogUtilities(LogUtilities log) If the driver can't be set, the log must be set for logging messages.
void	setLogUtilities(LogUtilities log, boolean copyLogClass) This method is used to setup the LogUtilities and OPTIONALLY setup to copyLogClass.
void	shutdown() Each concrete subclass may override to provide their own specific interface shutdown.
protected void	shutdownService(java.lang.String aname) Provides a default shutdown implementation for services.
protected void	simpleGenericMessage(TestRecordData testRecordData, java.lang.String note, java.lang.String detail) Log a simple GENERIC_MESSAGE with optional detail. "your note" "your detail" note and detail should already be localized and will be sent unmodified.
protected void	simpleGenericSuccessMessage(TestRecordData testRecordData, java.lang.String note, java.lang.String detail) Log a simple GENERIC_MESSAGE with detail.
protected void	simpleGenericWarningMessage(TestRecordData testRecordData, java.lang.String note) Log a simple WARNING_MESSAGE with standard detail. "your note" "[command] warning in table [filename] at line [linenumber]." note should already be localized. The routine will create the standard warning details.
protected void	simpleSuccessMessage(TestRecordData testRecordData, java.lang.String note, java.lang.String detail) Log a simple PASSED_MESSAGE with detail.
protected void	simpleSuccessMessage(TestRecordData testRecordData, java.lang.String item, java.lang.String action, java.lang.String detail) Log a simple PASSED_MESSAGE with detail.
protected void	simpleSuccessUsingMessage(TestRecordData testRecordData, java.lang.String note, java.lang.String item, java.lang.String detail) Log a simple PASSED_MESSAGE with detail.
protected void	standardErrorMessage(TestRecordData testRecordData, java.lang.String problem, java.lang.String detail) Log a standard command FAILED_MESSAGE with detail.
protected void	waitForServiceStartCompletion(int seconds)

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

reset

Field Detail

DRIVER_TEMP_PROCESS

public static final java.lang.String DRIVER_TEMP_PROCESS

"SAFS_DCSIC_PING". Used when we PING STAF to make sure it is running.

See Also:

Constant Field Values

STAFPROC_EXE

public static final java.lang.String STAFPROC_EXE

"STAFProc". Default executable path to STAF. This should be multi-platform compatible.

See Also:

Constant Field Values

driver

protected DriverInterface driver

The DriverInterface used for all configuration information.

log

protected LogUtilities log

This LogUtilities is set for logging message if the DriverInterface can't be initialized.

processName

protected java.lang.String processName

The stored DriverName. Primarily saved to unRegister with STAF even if the Driver has been destroyed.

servicename

protected java.lang.String servicename

Storage for STAF service\client name

config

protected ConfigureInterface config

The ConfigurInterface extracted from the Driver for easy access.

staf

protected STAFHelper staf

The STAFHelper retrieved from STAFProcessHelpers during the call to launchInterface.

running

protected boolean running

true if the client was running or successfully launched.

weStartedService

protected boolean weStartedService

Flag to record whether the associated STAF service was started by this instance (true); or if it was found already running (false).

weStartedSTAF

protected static boolean weStartedSTAF

Flag to record whether this JVM (DRIVER) started STAF. If we started STAF, we then may be allowed to shut it down.

machine

protected java.lang.String machine

The "where" of our associated STAF service for this instance. By default, the are on the "local" machine.

launchCount

protected long launchCount

Tracking how many launchInterface calls processed.

shutdownCount

protected long shutdownCount

Track how many things must be shutdown before we can attempt to shutdown STAF. We will only attempt to shutdown STAF if weStartedSTAF= true

SAFS_RESBUN_NAME

public static final java.lang.String SAFS_RESBUN_NAME

"SAFSTextResourceBundle"

See Also:

Constant Field Values

genericStr

protected static final java.lang.String genericStr

empty. Forces use of default SAFSTextResourceBundle.

See Also:

Constant Field Values

passedStr

protected static final java.lang.String passedStr

empty. Forces use of default SAFSTextResourceBundle.

See Also:

Constant Field Values

failedStr

protected static final java.lang.String failedStr

"failed". Forces use of failedSAFSTextResourceBundle.

See Also:

Constant Field Values

warningStr

protected static final java.lang.String warningStr

"failed". Forces use of failedSAFSTextResourceBundle.

See Also:

Constant Field Values

otherStr

protected static final java.lang.String otherStr

empty. Forces use of default SAFSTextResourceBundle.

See Also:

Constant Field Values

customStr

protected static final java.lang.String customStr

empty. Forces use of default SAFSTextResourceBundle.

See Also:

Constant Field Values

debugStr

protected static final java.lang.String debugStr

empty. Forces use of default SAFSTextResourceBundle.

See Also:

Constant Field Values

genericText

protected static GetText genericText

GetText instance handling GENERIC text resources.

passedText

protected static GetText passedText

GetText instance handling PASSED text resources.

failedText

protected static GetText failedText

GetText instance handling FAILED text resources.

warningText

protected static GetText warningText

GetText instance handling WARNING text resources.

otherText

protected static GetText otherText

GetText instance handling ?OTHER? text resources?

customText

protected static GetText customText

GetText instance handling CUSTOM text resources.

debugText

protected static GetText debugText

GetText instance handling DEBUG text resources.

Constructor Detail

DriverConfiguredSTAFInterfaceClass

public DriverConfiguredSTAFInterfaceClass()

Constructor for DriverConfiguredInterfaceClass

Method Detail

waitForServiceStartCompletion

protected void waitForServiceStartCompletion(int seconds)
                                      throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

setLogUtilities

public void setLogUtilities(LogUtilities log)

If the driver can't be set, the log must be set for logging messages. This method is used for setup the LogUtilities. In the org.safs.rational.DCDriverCommand (a Processor), we create a new engine org.safs.tools.engines.TIDDriverCommand, but we don't have the driver to initialize a new engine, so we just set the LogUtilizes to keep the log working.

Parameters:

log -

setLogUtilities

public void setLogUtilities(LogUtilities log,
                            boolean copyLogClass)

This method is used to setup the LogUtilities and OPTIONALLY setup to copyLogClass.

Parameters:

log -

copyLogClass - set to true to copy everything to the debug log (Log.class)

logMessage

public void logMessage(UniqueStringMessageInfo info)

This method will use try to use the LogUtilities to log message first. If not present, the LogsInterface of a driver to log message will be tried.

Parameters:

info -

standardErrorMessage

protected void standardErrorMessage(TestRecordData testRecordData,
                                    java.lang.String problem,
                                    java.lang.String detail)

Log a standard command FAILED_MESSAGE with detail. Detail can be null.
"your problem failed in table filename at line linenumber."
"detail here"

Expects testRecordData to already have filename and lineNumber.

extendedGenericMessage

protected void extendedGenericMessage(TestRecordData testRecordData,
                                      java.lang.String note,
                                      java.lang.String detail)

Log an extended GENERIC_MESSAGE including filename, linenumber, and detail. Detail can be null
"note in table filename at line linenumber."
"detail here"

Expects testRecordData to already have filename and lineNumber.

simpleSuccessMessage

protected void simpleSuccessMessage(TestRecordData testRecordData,
                                    java.lang.String note,
                                    java.lang.String detail)

Log a simple PASSED_MESSAGE with detail. Detail can be null.
"note successful."
"detail here"

Expects testRecordData to already have filename and lineNumber.

simpleGenericSuccessMessage

protected void simpleGenericSuccessMessage(TestRecordData testRecordData,
                                           java.lang.String note,
                                           java.lang.String detail)

Log a simple GENERIC_MESSAGE with detail. Detail can be null.
"note successful."
"detail here"
Detail should already be localized, if present.

simpleGenericMessage

protected void simpleGenericMessage(TestRecordData testRecordData,
                                    java.lang.String note,
                                    java.lang.String detail)

Log a simple GENERIC_MESSAGE with optional detail.
"your note"
"your detail"
note and detail should already be localized and will be sent unmodified.

getCoreInterface

public CoreInterface getCoreInterface()
                               throws java.lang.IllegalStateException

Description copied from interface: GenericToolsInterface

Retrieve the instance of the CoreInterface used to communicate with the framework.

Specified by:

getCoreInterface in interface GenericToolsInterface

Returns:

CoreInterface instance.

Throws:

java.lang.IllegalStateException - if the CoreInterface is null, has not been initialized yet, or is otherwise invalid.

simpleGenericWarningMessage

protected void simpleGenericWarningMessage(TestRecordData testRecordData,
                                           java.lang.String note)

Log a simple WARNING_MESSAGE with standard detail.
"your note"
"[command] warning in table [filename] at line [linenumber]." note should already be localized.
The routine will create the standard warning details. Expects testRecordData to already have command, filename, and lineNumber.

simpleSuccessMessage

protected void simpleSuccessMessage(TestRecordData testRecordData,
                                    java.lang.String item,
                                    java.lang.String action,
                                    java.lang.String detail)

Log a simple PASSED_MESSAGE with detail. Detail can be null.
"item action successful."
"detail here"

Expects testRecordData to already have filename and lineNumber.

simpleSuccessUsingMessage

protected void simpleSuccessUsingMessage(TestRecordData testRecordData,
                                         java.lang.String note,
                                         java.lang.String item,
                                         java.lang.String detail)

Log a simple PASSED_MESSAGE with detail. Detail can be null.
"note successful using item."
"detail here"

Expects testRecordData to already have filename and lineNumber.

getSTAFHelper

public void getSTAFHelper()

Get our STAFProcessHelper. Launch STAF if it is not running. Will give us our STAFHelper object once everything is running. Tries to create a connection to STAF. If not running, we will attempt to launch STAF with a simple execution of STAFProc.exe and set the static weStartedSTAF flag to TRUE.

If necessary, or desirable, the configuration source can specify the full path to an executable, and the path to any alternate configuration file desired. STAFProc will use its default configuration file if no other is specified.

 [STAF]
 PATH=Full path to/STAFProc.EXE (or shell, bat, script, etc.)
 CONFIG=Full path to/yourCustom.CFG
 

Throws:

java.lang.IllegalArgumentException - if we are unable to return TRUE.

launchInterface

public void launchInterface(java.lang.Object configInfo)

Generic extraction of Driver, Config, and STAFHelper objects. Each concrete subclass must override to provide their own specific interface initialization, but they must call this routine before proceeding with their own launch activities using:

super.launchInterface(configInfo);

popuplates the driver, processName, config, and staf fields with valid objects. These items are properly unregistered/destroyed in the finalize() method.

Specified by:

launchInterface in interface ConfigurableToolsInterface

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:

ConfigurableToolsInterface.launchInterface(Object)

getEmbeddedJVMBinPath

public java.io.File getEmbeddedJVMBinPath()
                                   throws java.io.FileNotFoundException

See if SAFS has an embedded JVM with it.

Returns:

the File object pointing to a valid JVM\bin directory.

Throws:

java.io.FileNotFoundException - if we could not locate an embedded JVM Path.

configureJSTAFServiceEmbeddedJVMOption

public java.lang.String configureJSTAFServiceEmbeddedJVMOption(java.lang.String options)

Configure SAFS Services to use the embedded 32-bit JVM if:

• the shared JSTAF JVM is not already running.
• existing configuration OPTION does not explicitly set a different JVM.
• SAFS has an embedded JRE (\SAFS\jre\bin\java) exists.

Parameters:

options - already retrieved from config files

Returns:

options with new JVM= param added, or options unmodified.

shutdownService

protected void shutdownService(java.lang.String aname)

Provides a default shutdown implementation for services. Subclasses that are not services should override this method to provide the correct shutdown behavior.

Parameters:

aname - Generally the servicename or client name used in STAF. Default values passed in are usually the same as the servicename field.

shutdown

public void shutdown()

Each concrete subclass may override to provide their own specific interface shutdown.

This implementation checks to see if weStartedService=true. If so, it will attempt to shutdown the servicename through STAF.

This implementation will also see if weStartedSTAF=true. If so, then it will attempt to decrement shutdownCount. If shutdownCount reaches 0 then it will attempt to shutdown STAF.

Specified by:

shutdown in interface GenericToolsInterface

See Also:

GenericToolsInterface#shutdown()

isToolRunning

public boolean isToolRunning()

Description copied from interface: GenericToolsInterface

TRUE if the underlying tool is running. Typically called AFTER initialization attempts have been made.

Specified by:

isToolRunning in interface GenericToolsInterface

See Also:

GenericToolsInterface#isToolRunning()

finalize

protected void finalize()
                 throws java.lang.Throwable

finalize if we are ever destroyed without the JVM shutting down. Most importantly, this unRegisters us through STAFProcessHelpers and reduces the STAFHelpers instance count appropriately.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable