org.safs
Class DDGUIUtilities

java.lang.Object
  org.safs.STAFRequester
      org.safs.DDGUIUtilities

Direct Known Subclasses:

AbbotGUIUtilities, DCGUIUtilities, DGUIUtilities, IGUIUtilities, JREXGUIUtilities, RDDGUIUtilities, SeleniumGUIUtilities

public abstract class DDGUIUtilities
extends STAFRequester

Here we provide the basis for handling Application Maps through the SAFSMAPS service in STAF. This class handles the registering, opening, and storing of App Map references from different sources.

DDGUIUtilities handles interfacing to the text-based App Map files handled by SAFSMAPS. When doing this, it also forms a cache of all App Maps referenced AND the objects or items retrieved from those App Maps. These are all handled and stored in ApplicationMap objects and their subclasses.

For example, a Rational subclass for ApplicationMap would use the basic interface to lookup object recognition strings, but then would extend that functionality to actually store tool-dependent TestObject references in the RApplicationMap objects stored in this DDGUIUtilities.

As a subclass of STAFRequester, this class is expecting an implementation specific subclass to instantiate and provide a valid STAFHelper object.

Since:

JUN 26, 2003

Field Summary

protected static java.util.Hashtable	appmaps The storage of all ApplicationMaps ever opened or registered thru this class.
protected static int	DEBUG_MESSAGE Convenience for local referencing instead of referencing AbstractLogFacility.
protected static int	FAILED_MESSAGE Log MessageType for local referencing.
protected static int	FAILED_OK_MESSAGE Log MessageType for local referencing.
protected static int	GENERIC_MESSAGE Convenience for local referencing instead of referencing AbstractLogFacility.
protected LogUtilities	log
protected static int	PASSED_MESSAGE Log MessageType for local referencing.
protected TestRecordData	trdata
protected static int	WARNING_MESSAGE Log MessageType for local referencing.
protected static int	WARNING_OK_MESSAGE Log MessageType for local referencing.

Fields inherited from class org.safs.STAFRequester

staf

Constructor Summary

DDGUIUtilities()

Method Summary

void	clearAllAppMapCaches() clear all known local App Maps' caches.
void	clearAppMapCache(java.lang.String mapname) clear a single local App Map cache of all old references.
protected ApplicationMap	createAppMapInstance(java.lang.String mapname) Create an ApplicationMap instance.
abstract java.util.List	extractListItems(java.lang.Object obj, java.lang.String countProp, java.lang.String itemProp) Extract items from a List or Array type of object property.
abstract Tree	extractMenuBarItems(java.lang.Object obj) Extract a menu hierarchy from a MenuBar pseudo-object reference.
abstract Tree	extractMenuItems(java.lang.Object obj) Extract a menu hierarchy from a object.
abstract java.lang.Object	findPropertyMatchedChild(java.lang.Object obj, java.lang.String property, java.lang.String bench, boolean exactMatch) Attempt to locate a child object based on a matching property value.
protected ApplicationMap	getAppMap(java.lang.String mapname) Retrieve a named ApplicationMap object from storage.
abstract java.lang.String	getListItem(java.lang.Object obj, int i, java.lang.String itemProp) Get a single list item from a List or Array type of object property.
LogUtilities	getLogUtilities()
TestRecordData	getTestRecordData()
boolean	isAppMapRegistered(java.lang.String mapname) Checks for an ApplicationMap object stored with the given name.
boolean	openAppMap(java.lang.String mapname, java.lang.String mapfile) Attempts to open an ApplicationMap file via the SAFSMAPS service in STAF.
protected void	registerAppMap(java.lang.String mapname, ApplicationMap map) Store a named AppMap that has been successfully opened or found already opened.
boolean	registerAppMap(java.lang.String mapname, java.lang.String mapfile) Store a named AppMap that has been successfully opened or found already opened.
abstract int	setActiveWindow(java.lang.String appMapName, java.lang.String windowName, java.lang.String compName) "Activate" the specified component's topmost parent.
void	setLogUtilities(LogUtilities log) A one-time setting of the LogUtilities to be used by this instance.
void	setTestRecordData(TestRecordData trdata) A one-time setting of the RTestRecordData to be used by this instance.
abstract int	waitForObject(java.lang.String appMapName, java.lang.String windowName, java.lang.String compName, long secTimeout) Wait up to a maximum timeout value for the specified component to "exist".

Methods inherited from class org.safs.STAFRequester

getSTAFHelper, setSTAFHelper

Methods inherited from class java.lang.Object

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

Field Detail

appmaps

protected static java.util.Hashtable appmaps

The storage of all ApplicationMaps ever opened or registered thru this class. Each ApplicationMap is stored and referenced by its given name.

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

trdata

protected TestRecordData trdata

log

protected LogUtilities log

Constructor Detail

DDGUIUtilities

public DDGUIUtilities()

Method Detail

getAppMap

protected ApplicationMap getAppMap(java.lang.String mapname)

Retrieve a named ApplicationMap object from storage. Only ApplicationMaps that have been successfully registered or opened can be retrieved. This is normally only called by DDGUIUtilities and its subclasses to satisfy other calls.

The retrieved ApplicationMap may have to be cast to the appropriate ApplicationMap subclass. For example RApplicationMap for Rational.

Parameters:

mapname - -- the name by which the ApplicationMap will be known.

Returns:

null if not found, which generally means it hasn't been successfully registered or opened.

createAppMapInstance

protected ApplicationMap createAppMapInstance(java.lang.String mapname)

Create an ApplicationMap instance. Subclasses may override to provide engine-specific ApplicationMap subclass instances suitable for their needs.

registerAppMap

protected void registerAppMap(java.lang.String mapname,
                              ApplicationMap map)

Store a named AppMap that has been successfully opened or found already opened.

Parameters:

mapname - -- the name by which the ApplicationMap will be known.

map - -- the ApplicationMap to store with the given mapname.

registerAppMap

public boolean registerAppMap(java.lang.String mapname,
                              java.lang.String mapfile)

Store a named AppMap that has been successfully opened or found already opened. This will create an AppMapInstance to store in our local cache.

Parameters:

mapname - -- the name by which the ApplicationMap will be known.

mapfile - -- the ApplicationMap to store with the given mapname.

isAppMapRegistered

public boolean isAppMapRegistered(java.lang.String mapname)

Checks for an ApplicationMap object stored with the given name.

Parameters:

mapname - -- the name for the AppMap

Returns:

true if an ApplicationMap by this name is in storage.

openAppMap

public boolean openAppMap(java.lang.String mapname,
                          java.lang.String mapfile)

Attempts to open an ApplicationMap file via the SAFSMAPS service in STAF. The file will be opened, but a subclass will still have to register/store an ApplicationMap cache via a registerAppMap call.

The routine will NOT call STAF to open the file if an ApplicationMap object is already registered for a map with the given name.

Parameters:

mapname - -- the name for the AppMap

mapfile - -- the AppMap file to open. May be a full or relative path depending upon how SAFSMAPS is configured. If the mapfile value is null, then we will attempt to use the mapname as the filename.

Returns:

true if successfully opened (or already registered as open)

clearAppMapCache

public void clearAppMapCache(java.lang.String mapname)

clear a single local App Map cache of all old references.

Parameters:

mapname - of the App Map to clear

clearAllAppMapCaches

public void clearAllAppMapCaches()

clear all known local App Maps' caches.

waitForObject

public abstract int waitForObject(java.lang.String appMapName,
                                  java.lang.String windowName,
                                  java.lang.String compName,
                                  long secTimeout)
                           throws SAFSObjectNotFoundException

Wait up to a maximum timeout value for the specified component to "exist".

Parameters:

appMapName - name of AppMap used to lookup component.

windowName - name of Window in AppMap.

compName - name of Window Component in AppMap. If the Window IS the desired Component, then both windowName and compName will be the same.

secTimeout - maximum wait in seconds

Returns:

status 0 if successful; thrown exceptions if not. Other return codes may be implementation specific.

Throws:

SAFSObjectNotFoundException - if the component or its parent cannot be found.

setActiveWindow

public abstract int setActiveWindow(java.lang.String appMapName,
                                    java.lang.String windowName,
                                    java.lang.String compName)
                             throws SAFSObjectNotFoundException

"Activate" the specified component's topmost parent.

Parameters:

appMapName - name of AppMap used to lookup component.

windowName - name of Window in AppMap.

compName - name of Window Component in AppMap. If the Window IS the desired Component, then both windowName and compName will be the same.

Returns:

status 0 if successful; thrown exceptions if not. Other return codes may be implementation specific.

Throws:

SAFSObjectNotFoundException - if the component or its parent cannot be found.

findPropertyMatchedChild

public abstract java.lang.Object findPropertyMatchedChild(java.lang.Object obj,
                                                          java.lang.String property,
                                                          java.lang.String bench,
                                                          boolean exactMatch)
                                                   throws SAFSObjectNotFoundException

Attempt to locate a child object based on a matching property value. The check can require an exactMatch; or, a case-insensitive partial substring match if the exactMatch parameter is false. (Can use StringUtils.isCaseContainsMatch)

Parameters:

obj - -- the pseudo-object reference whose children will be evaluated.

property - -- the property of each child that will be evaluated. The property is expected to be one that can successfully return a value cast as type String.

bench - -- the benchmark value for the property to be used in comparisons.

exactMatch - -- if true, an exact case-sensitive match of the bench value provided is required to signal a match.
if false, a case-insensitive partial substring match with the bench value is performed.

Returns:

Object, the first child pseudo-object whose property value matches accordingly.

Throws:

SAFSObjectNotFoundException - if no matching child object is found.

See Also:

StringUtils.isCaseContainsMatch(String,String,boolean)

extractListItems

public abstract java.util.List extractListItems(java.lang.Object obj,
                                                java.lang.String countProp,
                                                java.lang.String itemProp)
                                         throws SAFSException

Extract items from a List or Array type of object property.

Parameters:

obj, - pseudo-object identifying object to extract from.

countProp, - String, the property which will contain an Integer count of items

itemProp, - String, the property which will contain the List or Array of items

Returns:

List

Throws:

SAFSException

getListItem

public abstract java.lang.String getListItem(java.lang.Object obj,
                                             int i,
                                             java.lang.String itemProp)
                                      throws SAFSException

Get a single list item from a List or Array type of object property.

Parameters:

obj, - pseudo-object identifying object to extract from.

i, - int, index into object list or array.

itemProp, - String, the property which will contain the List or Array of items

Returns:

String

Throws:

SAFSException

extractMenuBarItems

public abstract Tree extractMenuBarItems(java.lang.Object obj)
                                  throws SAFSException

Extract a menu hierarchy from a MenuBar pseudo-object reference. Often this can be served by the extracMenuItems function. This is generally for JMenuBars.

Parameters:

obj, - pseudo-object reference

Returns:

org.safs.Tree

Throws:

SAFSException

extractMenuItems

public abstract Tree extractMenuItems(java.lang.Object obj)
                               throws SAFSException

Extract a menu hierarchy from a object. This is generally for JPopupMenus, JMenus, and JMenuItems (JMenu is subclass of JMenuItem).

Parameters:

obj, - pseudo-object reference

Returns:

org.safs.Tree

Throws:

SAFSException

setTestRecordData

public void setTestRecordData(TestRecordData trdata)

A one-time setting of the RTestRecordData to be used by this instance. This normally happens as part of construction, or immediately following construction.

getTestRecordData

public TestRecordData getTestRecordData()

setLogUtilities

public void setLogUtilities(LogUtilities log)

A one-time setting of the LogUtilities to be used by this instance. This normally happens as part of construction, or immediately following construction.

getLogUtilities

public LogUtilities getLogUtilities()