DriverConfiguredSTAFInterfaceClass (SAFS API DOCUMENT)

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., Lei Wang APR 01, 2019 Added getEmbedded64JVMBinPath(), modified configureJSTAFServiceEmbeddedJVMOption(): use 64-bits embedded Java to run JSAFS Service.

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

Constructors
Constructor and Description
`DriverConfiguredSTAFInterfaceClass()` Constructor for DriverConfiguredInterfaceClass

Method Summary

All Methods Instance Methods Concrete Methods
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`	`getEmbedded64JVMBinPath()` See if SAFS has an embedded 64 bits JVM with it.
`java.io.File`	`getEmbeddedJVMBinPath()` See if SAFS has an embedded 32 bits 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 32 bits 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.
  - getEmbedded64JVMBinPath
```
public java.io.File getEmbedded64JVMBinPath()
                                     throws java.io.FileNotFoundException
```
    See if SAFS has an embedded 64 bits 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

Class DriverConfiguredSTAFInterfaceClass

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.safs.tools.GenericToolsInterface

Field Detail

DRIVER_TEMP_PROCESS

STAFPROC_EXE

driver

log

processName

servicename

config

staf

running

weStartedService

weStartedSTAF

machine

launchCount

shutdownCount

SAFS_RESBUN_NAME

genericStr

passedStr

failedStr

warningStr

otherStr

customStr

debugStr

genericText

passedText

failedText

warningText

otherText

customText

debugText

Constructor Detail

DriverConfiguredSTAFInterfaceClass

Method Detail

waitForServiceStartCompletion

setLogUtilities

setLogUtilities

logMessage

standardErrorMessage

extendedGenericMessage

simpleSuccessMessage

simpleGenericSuccessMessage

simpleGenericMessage

getCoreInterface

simpleGenericWarningMessage

simpleSuccessMessage

simpleSuccessUsingMessage

getSTAFHelper

launchInterface

getEmbeddedJVMBinPath

getEmbedded64JVMBinPath

configureJSTAFServiceEmbeddedJVMOption

shutdownService

shutdown

isToolRunning

finalize