JavaHook (SAFS API DOCUMENT)

java.lang.Object
- org.safs.JavaHook

All Implemented Interfaces:

HookConfig

Direct Known Subclasses:

DCJavaHook, EmbeddedHookDriver, IJavaHook, JavaSocketsHook, SeleniumHook, SeleniumJavaHook
```
public abstract class JavaHook
extends java.lang.Object
implements HookConfig
```
Generic Java Hook for tool-independent SAFS Engines. This abstract class provides the implementation for the initialization and event handling of all Java-based SAFS Engines that will be controlled via our STAF protocols.
If the engine is being launched manually or via a batch file or script then the following Java System property should be set on the Java command line:
testpath is the file path to the test configuration INI file,
projectpath is the file path to the project configuration INI file,
driverpath is the file path to the SAFS driver configuration INI file.
Concrete subclasses will have to provide their specific flavors of subclasses for:
- DDGUIUtilities
- LogUtilities
- TestRecordHelper
Concrete subclasses need to consider overriding the following methods if they need to alter the default behavior:
- evaluateRuntimeException
- allowSystemExit
Since:

NOV 09, 2003

Author:

Carl Nagle, SAS Institute

Field Summary

Fields
Modifier and Type	Field and Description
`protected TestRecordHelper`	`data` The TestRecordHelper the hook will use for handling TestRecordData.
`protected static int`	`DEBUG_MESSAGE` Convenience for local referencing instead of referencing AbstractLogFacility.
`protected GetText`	`errorText` "failedSAFSTextResourceBundle" -- our default source of error messages
`protected static int`	`FAILED_MESSAGE` Log MessageType for local referencing.
`protected static int`	`FAILED_OK_MESSAGE` Log MessageType for local referencing.
`protected static java.lang.String`	`GENERIC_ERROR` "generic_error"
`protected static int`	`GENERIC_MESSAGE` Convenience for local referencing instead of referencing AbstractLogFacility.
`protected STAFHelper`	`helper` The STAFHelper used to interact with STAF.
`protected HookConfig`	`hookconfig` Used to get settings from ConfigureInterface.
`protected LogUtilities`	`log` The LogUtilities the hook will use for logging.
`protected static int`	`PASSED_MESSAGE` Log MessageType for local referencing.
`static java.lang.String`	`PAUSE_EXECUTION` "PAUSE"
`static java.lang.String`	`PAUSE_SWITCH_OFF` "OFF" for SAFSVARS variable 'SAFS_DRIVER_CONTROL_POF'/'SAFS_DRIVER_CONTROL_POW'
`static java.lang.String`	`PAUSE_SWITCH_ON` "ON" for SAFSVARS variable 'SAFS_DRIVER_CONTROL_POF'/'SAFS_DRIVER_CONTROL_POW'
`protected java.lang.String`	`process_name` The name of the process this hook supports.
`protected ProcessRequest`	`processor` The ProcessRequest object the hook will use for handling input records.
`static long`	`REQUEST_PROCEED_TESTING` 0 Proceed with normal testing
`static long`	`REQUEST_USER_STOPPED_SCRIPT_REQUEST` -1 The user has requested to STOP or ABORT execution of this engine.
`static java.lang.String`	`RUNNING_EXECUTION` "RUNNING"
`protected java.lang.String`	`semaphore_name` The root name used in STAF Semaphore EVENT communication.
`static java.lang.String`	`SHUTDOWN_RECORD` "SHUTDOWN_HOOK"
`protected static java.lang.String`	`STAF_ERROR` "staf_error"
`static java.lang.String`	`STEP_EXECUTION` "STEP"
`static java.lang.String`	`STEP_RETRY_EXECUTION` "STEP_RETRY"
`static java.lang.String`	`STEPPING_EXECUTION` "STEPPING"
`static java.lang.String`	`STEPPING_RETRY_EXECUTION` "STEPPING_RETRY"
`protected java.lang.String`	`trd_name` Root Name of TestRecordData store in SAFSVARS.
`protected DDGUIUtilities`	`utils` The DDGUIUtilities the hook will use for handling components.
`protected static int`	`WARNING_MESSAGE` Log MessageType for local referencing.
`protected static int`	`WARNING_OK_MESSAGE` Log MessageType for local referencing.

Constructor Summary

Constructors
Constructor and Description
`JavaHook()` Empty Constructor.
`JavaHook(java.lang.String process_name)` Minimal initialization constructor.
`JavaHook(java.lang.String process_name, LogUtilities logs)` Minimal initialization constructor.
`JavaHook(java.lang.String process_name, java.lang.String trd_name)` Minimal initialization constructor.
`JavaHook(java.lang.String process_name, java.lang.String trd_name, LogUtilities logs)` Standard initialization constructor.
`JavaHook(java.lang.String process_name, java.lang.String trd_name, LogUtilities logs, TestRecordHelper trd_data, DDGUIUtilities gui_utils, ProcessRequest aprocessor)` Advanced Constructor.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected boolean`	`allowSystemExit()` Evaluate if the runtime hook should exit with System.exit(0).
`void`	`checkConfiguration()` Call `initConfigPaths()` to initialize the ConfigureInterface instance. Call `instantiateHookConfig()` to initialize the HookConfig instance. Call `HookConfig.checkConfiguration()` to check configuration settings for Hook.
`protected boolean`	`driverShutdownRequest()`
`protected long`	`evaluateRuntimeException(java.lang.RuntimeException ex)` Evaluate if the runtime hook should shutdown, proceed, or some other action following the receipt of a RuntimeException.
`abstract DDGUIUtilities`	`getGUIUtilities()` Retrieve the DDGUIUtilities used by the subclass.
`STAFHelper`	`getHelper()`
`abstract LogUtilities`	`getLogUtilities()` Retrieve the LogUtilities used by the subclass.
`java.lang.String`	`getProcessName()`
`abstract ProcessRequest`	`getRequestProcessor()` Retrieve the ProcessRequest instance used by the subclass.
`java.lang.String`	`getSemaphoreName()`
`abstract TestRecordHelper`	`getTRDData()` Retrieve the TestRecordHelper used by the subclass.
`java.lang.String`	`getTRDName()`
`protected boolean`	`hook_shutdown()` Perform final hook shutdown activities before the check for allowSystemExit.
`protected void`	`initConfigPaths()` Initialize access to chained ConfigurationInterface data.
`protected void`	`instantiateHookConfig()` Instantiate the HookConfig, used to get settings from ConfigureInterface.
`void`	`setGUIUtilities(DDGUIUtilities gui_utils)`
`void`	`setHelper(java.lang.Object processhelper)` Set our STAFHelper to be the one provided.
`void`	`setLogUtilities(LogUtilities lu)`
`protected void`	`setProcessName(java.lang.String process_name)` Set the process name for this hook for an instance created from an empty constructor.
`void`	`setRequestProcessor(ProcessRequest aprocessor)`
`protected void`	`setSemaphoreName(java.lang.String semname)`
`void`	`setTRDData(TestRecordHelper trd_data)`
`void`	`setTRDName(java.lang.String trdname)`
`void`	`start()` Insert this SAFS Engine hook into the STAF system.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SHUTDOWN_RECORD
```
public static final java.lang.String SHUTDOWN_RECORD
```
    "SHUTDOWN_HOOK"
    
    See Also:
    
    Constant Field Values
  - PAUSE_EXECUTION
```
public static final java.lang.String PAUSE_EXECUTION
```
    "PAUSE"
    
    See Also:
    
    Constant Field Values
  - STEP_EXECUTION
```
public static final java.lang.String STEP_EXECUTION
```
    "STEP"
    
    See Also:
    
    Constant Field Values
  - STEPPING_EXECUTION
```
public static final java.lang.String STEPPING_EXECUTION
```
    "STEPPING"
    
    See Also:
    
    Constant Field Values
  - RUNNING_EXECUTION
```
public static final java.lang.String RUNNING_EXECUTION
```
    "RUNNING"
    
    See Also:
    
    Constant Field Values
  - STEP_RETRY_EXECUTION
```
public static final java.lang.String STEP_RETRY_EXECUTION
```
    "STEP_RETRY"
    
    See Also:
    
    Constant Field Values
  - STEPPING_RETRY_EXECUTION
```
public static final java.lang.String STEPPING_RETRY_EXECUTION
```
    "STEPPING_RETRY"
    
    See Also:
    
    Constant Field Values
  - PAUSE_SWITCH_ON
```
public static final java.lang.String PAUSE_SWITCH_ON
```
    "ON" for SAFSVARS variable 'SAFS_DRIVER_CONTROL_POF'/'SAFS_DRIVER_CONTROL_POW'
    
    See Also:
    
    Constant Field Values
  - PAUSE_SWITCH_OFF
```
public static final java.lang.String PAUSE_SWITCH_OFF
```
    "OFF" for SAFSVARS variable 'SAFS_DRIVER_CONTROL_POF'/'SAFS_DRIVER_CONTROL_POW'
    
    See Also:
    
    Constant Field Values
  - DEBUG_MESSAGE
```
protected static final int DEBUG_MESSAGE
```
    Convenience for local referencing instead of referencing AbstractLogFacility.
    
    See Also:
    
    Constant Field Values
  - GENERIC_MESSAGE
```
protected static final int GENERIC_MESSAGE
```
    Convenience for local referencing instead of referencing AbstractLogFacility.
    
    See Also:
    
    Constant Field Values
  - FAILED_MESSAGE
```
protected static final int FAILED_MESSAGE
```
    Log MessageType for local referencing. Inherits AbstractLogFacility value.
    
    See Also:
    
    Constant Field Values
  - FAILED_OK_MESSAGE
```
protected static final int FAILED_OK_MESSAGE
```
    Log MessageType for local referencing. Inherits AbstractLogFacility value.
    
    See Also:
    
    Constant Field Values
  - PASSED_MESSAGE
```
protected static final int PASSED_MESSAGE
```
    Log MessageType for local referencing. Inherits AbstractLogFacility value.
    
    See Also:
    
    Constant Field Values
  - WARNING_MESSAGE
```
protected static final int WARNING_MESSAGE
```
    Log MessageType for local referencing. Inherits AbstractLogFacility value.
    
    See Also:
    
    Constant Field Values
  - WARNING_OK_MESSAGE
```
protected static final int WARNING_OK_MESSAGE
```
    Log MessageType for local referencing. Inherits AbstractLogFacility value.
    
    See Also:
    
    Constant Field Values
  - REQUEST_USER_STOPPED_SCRIPT_REQUEST
```
public static final long REQUEST_USER_STOPPED_SCRIPT_REQUEST
```
    -1 The user has requested to STOP or ABORT execution of this engine. This is often done by a special HOTKEY or some other tool-specific means.
    
    See Also:
    
    Constant Field Values
  - REQUEST_PROCEED_TESTING
```
public static final long REQUEST_PROCEED_TESTING
```
    0 Proceed with normal testing
    
    See Also:
    
    Constant Field Values
  - hookconfig
```
protected HookConfig hookconfig
```
    Used to get settings from ConfigureInterface.
    
    See Also:
    
    instantiateHookConfig()
  - process_name
```
protected java.lang.String process_name
```
    The name of the process this hook supports. This is typically the process name we have registered with STAF. NOTE: calling setProcessName or setHelper 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.
  - semaphore_name
```
protected java.lang.String semaphore_name
```
    The root name used in STAF Semaphore EVENT communication. In most cases this is the same as the process_name. An exception would be where multiple STAF clients all have the same process_name. A unique semaphore name must exist for these. NOTE: calling setProcessName or setHelper 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.
  - trd_name
```
protected java.lang.String trd_name
```
    Root Name of TestRecordData store in SAFSVARS. Default is STAFHelper.SAFS_HOOK_TRD
  - log
```
protected LogUtilities log
```
    The LogUtilities the hook will use for logging.
  - helper
```
protected STAFHelper helper
```
    The STAFHelper used to interact with STAF.
  - data
```
protected TestRecordHelper data
```
    The TestRecordHelper the hook will use for handling TestRecordData.
  - utils
```
protected DDGUIUtilities utils
```
    The DDGUIUtilities the hook will use for handling components.
  - processor
```
protected ProcessRequest processor
```
    The ProcessRequest object the hook will use for handling input records.
  - errorText
```
protected GetText errorText
```
    "failedSAFSTextResourceBundle" -- our default source of error messages
  - GENERIC_ERROR
```
protected static final java.lang.String GENERIC_ERROR
```
    "generic_error"
    
    See Also:
    
    Constant Field Values
  - STAF_ERROR
```
protected static final java.lang.String STAF_ERROR
```
    "staf_error"
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - JavaHook
```
public JavaHook()
```
    Empty Constructor. All class initialization must still be performed.
  - JavaHook
```
public JavaHook(java.lang.String process_name)
```
    Minimal initialization constructor. Additional initialization still required. This constructor will initializae the STAF connection with the process_name given. The hook will use the default global TestRecordData storage of SAFS/Hook/TRD
    
    Parameters:
    
    process_name - -- The process name associated with STAF for this hook.
  - JavaHook
```
public JavaHook(java.lang.String process_name,
                LogUtilities logs)
```
    Minimal initialization constructor. Additional initialization still required. This constructor will initializae the STAF connection with the process_name given. The hook will use the default global TestRecordData storage of SAFS/Hook/TRD
    
    Parameters:
    
    process_name - -- The process name associated with STAF for this hook.
    
    logs - -- The LogUtilities to use for STAF logging.
  - JavaHook
```
public JavaHook(java.lang.String process_name,
                java.lang.String trd_name)
```
    Minimal initialization constructor. Additional initialization still required. This constructor will initializae the STAF connection with the process_name given. The hook will use the global TestRecordData storage with the root TestRecordData name given.
    
    Parameters:
    
    process_name - -- The process name associated with STAF for this hook.
    
    trd_name - -- The root name for specific TestRecordData to reference in STAF. This should typically be STAFHelper.SAFS_HOOK_TRD which is used by default.
  - JavaHook
```
public JavaHook(java.lang.String process_name,
                java.lang.String trd_name,
                LogUtilities logs)
```
    Standard initialization constructor. This constructor will initialize the STAF connection with the process_name given. The hook will use the global TestRecordData storage with the root TestRecordData name given. The LogUtilities provided will be used for all logging.
    
    Parameters:
    
    process_name - -- The process name associated with STAF for this hook.
    
    trd_name - -- The root name for specific TestRecordData to reference in STAF. This should typically be STAFHelper.SAFS_HOOK_TRD which is used by default.
    
    logs - -- The LogUtilities to use for STAF logging.
  - JavaHook
```
public JavaHook(java.lang.String process_name,
                java.lang.String trd_name,
                LogUtilities logs,
                TestRecordHelper trd_data,
                DDGUIUtilities gui_utils,
                ProcessRequest aprocessor)
```
    Advanced Constructor. This constructor allows an advanced engine to override some of the default values or objects used by the standard constructor. Thus, a hook can be setup to use alternative implementations; or object instances more tailored for varying needs.
    The hook will use the global TestRecordData storage with the root TestRecordData name given. The LogUtilities provided will be used for all logging.
    
    Parameters:
    
    process_name - -- The process name associated with STAF for this hook.
    
    trd_name - -- The root name for specific TestRecordData to reference in SAFSVARS. This should typically be STAFHelper.SAFS_HOOK_TRD which is used by default.
    
    logs - -- The LogUtilities to use for STAF logging.
    
    trd_data - -- TestRecordHelper to hold TestRecordData.
    
    gui_utils - -- DDGUIUtilities the hook will use for handling components.
    
    aprocessor - -- ProcessRequest object the hook will use for routing records.
- Method Detail
  - getProcessName
```
public java.lang.String getProcessName()
```
  - setProcessName
```
protected void setProcessName(java.lang.String process_name)
```
    Set the process name for this hook for an instance created from an empty constructor. The function will not overwrite an existing process name. A STAFHelper will be initialized with the given process name if accepted. NOTE: calling setProcessName or setHelper 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.
  - setSemaphoreName
```
protected void setSemaphoreName(java.lang.String semname)
```
  - getSemaphoreName
```
public java.lang.String getSemaphoreName()
```
  - getTRDName
```
public java.lang.String getTRDName()
```
  - setTRDName
```
public void setTRDName(java.lang.String trdname)
```
  - getLogUtilities
```
public abstract LogUtilities getLogUtilities()
```
    Retrieve the LogUtilities used by the subclass. If no LogUtilities has been set (log == null), then the implementation is expected to instantiate and return a LogUtilities instance appropriate for the hook.
  - setLogUtilities
```
public void setLogUtilities(LogUtilities lu)
```
  - getHelper
```
public STAFHelper getHelper()
```
  - 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.
    
    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.
  - getTRDData
```
public abstract TestRecordHelper getTRDData()
```
    Retrieve the TestRecordHelper used by the subclass. If no TestRecordHelper has been set (data == null), then the implementation is expected to instantiate and return a TestRecordHelper instance appropriate for the hook.
  - setTRDData
```
public void setTRDData(TestRecordHelper trd_data)
```
  - getGUIUtilities
```
public abstract DDGUIUtilities getGUIUtilities()
```
    Retrieve the DDGUIUtilities used by the subclass. If no DDGUIUtilities has been set (utils == null), then the implementation is expected to instantiate and return a DDGUIUtilities instance appropriate for the hook.
  - setGUIUtilities
```
public void setGUIUtilities(DDGUIUtilities gui_utils)
```
  - getRequestProcessor
```
public abstract ProcessRequest getRequestProcessor()
```
    Retrieve the ProcessRequest instance used by the subclass. If no ProcessRequest has been set (processor == null), then the implementation is expected to instantiate and return a ProcessRequest instance appropriate for the hook.
  - setRequestProcessor
```
public void setRequestProcessor(ProcessRequest aprocessor)
```
  - initConfigPaths
```
protected void initConfigPaths()
```
    Initialize access to chained ConfigurationInterface data. We initialize the chained data based on the availability and contents of the System Property "safs.config.paths", as defined:
    
    See Also:
    
    DriverConstant.PROPERTY_SAFS_CONFIG_PATHS, ConfigureInterface, TestRecordHelper.setConfig(ConfigureInterface), TestRecordHelper.getConfig()
  - instantiateHookConfig
```
protected void instantiateHookConfig()
```
    Instantiate the HookConfig, used to get settings from ConfigureInterface.
    Custom Hooks may override this method to provide their own HookConfig.
    Note: This should be called after initConfigPaths().
    
    See Also:
    
    initConfigPaths()
  - checkConfiguration
```
public void checkConfiguration()
```
    Call initConfigPaths() to initialize the ConfigureInterface instance.
    Call instantiateHookConfig() to initialize the HookConfig instance.
    Call HookConfig.checkConfiguration() to check configuration settings for Hook.
    
    Specified by:
    
    checkConfiguration in interface HookConfig
  - start
```
public void start()
```
    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.
  - evaluateRuntimeException
```
protected long evaluateRuntimeException(java.lang.RuntimeException ex)
```
    Evaluate if the runtime hook should shutdown, proceed, or some other action following the receipt of a RuntimeException.
    By default, this implementation will proceed with testing. Subclasses may wish to override this function to evaluate the RuntimeException and react accordingly.
  - driverShutdownRequest
```
protected boolean driverShutdownRequest()
```
    Returns:
    
    true if we detect the external SAFS_DRIVER_CONTROL variable has been set to 'SHUTDOWN_HOOK'
  - hook_shutdown
```
protected boolean hook_shutdown()
```
    Perform final hook shutdown activities before the check for allowSystemExit.
    This default implementation simply unregisters our STAFProcessHelper if it is not null. Subclasses may wish to provide additional functionality before calling super.hook_shutdown().
    
    Returns:
    
    The default implementation will return true allowing the additional check of allowSystemExit. If a subclass overrides and returns false then the attempt to allowSystemExit will not happen.
    
    See Also:
    
    allowSystemExit()
  - allowSystemExit
```
protected boolean allowSystemExit()
```
    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.

Class JavaHook

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SHUTDOWN_RECORD

PAUSE_EXECUTION

STEP_EXECUTION

STEPPING_EXECUTION

RUNNING_EXECUTION

STEP_RETRY_EXECUTION

STEPPING_RETRY_EXECUTION

PAUSE_SWITCH_ON

PAUSE_SWITCH_OFF

DEBUG_MESSAGE

GENERIC_MESSAGE

FAILED_MESSAGE

FAILED_OK_MESSAGE

PASSED_MESSAGE

WARNING_MESSAGE

WARNING_OK_MESSAGE

REQUEST_USER_STOPPED_SCRIPT_REQUEST

REQUEST_PROCEED_TESTING

hookconfig

process_name

semaphore_name

trd_name

log

helper

data

utils

processor

errorText

GENERIC_ERROR

STAF_ERROR

Constructor Detail

JavaHook

JavaHook

JavaHook

JavaHook

JavaHook

JavaHook

Method Detail

getProcessName

setProcessName

setSemaphoreName

getSemaphoreName

getTRDName

setTRDName

getLogUtilities

setLogUtilities

getHelper

setHelper

getTRDData

setTRDData

getGUIUtilities

setGUIUtilities

getRequestProcessor

setRequestProcessor

initConfigPaths

instantiateHookConfig

checkConfiguration

start

evaluateRuntimeException

driverShutdownRequest

hook_shutdown

allowSystemExit