org.safs.rational
Class RDDGUIUtilities

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

public class RDDGUIUtilities
extends DDGUIUtilities

Rational extension to DDGUIUtilities. Handles registering and storing Rational-specific RApplicationMap objects for Rational TestObject lookup and caching. Also provides Rational-specific functions for basic GUI object operations (setActive, waitFor, etc...)

Since:

JUN 04, 2003
JUN 04, 2003 (DBauman) Original Release

Field Summary

Fields inherited from class org.safs.DDGUIUtilities

appmaps, DEBUG_MESSAGE, FAILED_MESSAGE, FAILED_OK_MESSAGE, GENERIC_MESSAGE, log, PASSED_MESSAGE, trdata, WARNING_MESSAGE, WARNING_OK_MESSAGE

Fields inherited from class org.safs.STAFRequester

staf

Constructor Summary

RDDGUIUtilities()
The default, JavaBean-happy constructor.

RDDGUIUtilities(STAFHelper helper, Script script, LogUtilities log)
Constructor providing the STAFHelper and Script needed by the instance for proper operation.

RDDGUIUtilities(STAFHelper helper, Script script, RTestRecordData data, LogUtilities log)
Constructor providing the STAFHelper, Script, and RTestRecordData needed by the instance for proper operation.

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.
java.util.List	extractListItems(java.lang.Object obj, java.lang.String countProp, java.lang.String itemProp) Purpose: extract a list of items from a TestObject.
Tree	extractMenuBarItems(java.lang.Object obj) required implementation for superclass
Tree	extractMenuItems(java.lang.Object obj) required implementation for superclass
java.lang.Object	findPropertyMatchedChild(java.lang.Object testobject, java.lang.String property, java.lang.String bench, boolean exactMatch) Attempt to locate a child object based on a matching property value.
static GuiTestObject	getGuiTestObject(TestObject obj) Cast TestObject to GuiTestObject or create new GuiTestObject(ob).
static java.lang.String	getHtmlDocTitle(TestObject obj)
static TestObject	getHtmlDocumentObject(TestObject obj)
java.lang.String	getListItem(java.lang.Object obj, int i, java.lang.String itemProp) Purpose: get a list item from a TestObject.
TopLevelTestObject	getParentTestObject(TestObject obj) Attempt to retrieve either a TopLevelTestObject or BrowserTestObject, based on if it is a browser or not.
Script	getScript()
TestObject	getTestObject(java.lang.String mapname, java.lang.String windowName, java.lang.String childName) Attempt to retrieve a TestObject using the named references; this version calls the other version, passing 'false' to param 'ignoreCache'
TestObject	getTestObject(java.lang.String mapname, java.lang.String windowName, java.lang.String childName, boolean ignoreCache) Attempt to retrieve a TestObject using the named references; this version calls the other version, passing 'false' to param 'ignoreCache', and passing null to 'gather'
TestObject	getTestObject(java.lang.String mapname, java.lang.String windowName, java.lang.String childName, boolean ignoreCache, java.util.List gather) Attempt to retrieve a TestObject using the named references.
TestObject	getTestObject(java.lang.String mapname, java.lang.String windowName, java.lang.String childName, boolean ignoreCache, java.lang.String nameString) Attempt to retrieve a TestObject using the named references.
protected void	listAllProperties(TestObject obj, java.lang.String str)
void	listMapElements() Purpose: list Map elements Side Effects: Assumptions: none
protected void	listMethods(TestObject obj)
protected void	listNonValueProperties(TestObject obj)
protected void	listProperties(TestObject obj)
void	listTopLevelObjects() Purpose: list Map elements Side Effects: Assumptions: none
boolean	registerAppMap(java.lang.String mapname, java.lang.String mapfile) Register an AppMap for use.
int	setActiveWindow(java.lang.String mapName, java.lang.String windowName, java.lang.String compName) "Activate" the specified component's topmost parent.
void	setScript(Script script) A one-time setting of the Script (RationalTestScript) to be used by this instance.
int	waitForObject(java.lang.String mapName, 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.DDGUIUtilities

createAppMapInstance, getAppMap, getLogUtilities, getTestRecordData, isAppMapRegistered, maximizeWindow, minimizeWindow, openAppMap, registerAppMap, restoreWindow, setLogUtilities, setTestRecordData, setWindowFocus

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

Constructor Detail

RDDGUIUtilities

public RDDGUIUtilities()

The default, JavaBean-happy constructor. The instance cannot do much of anything without the STAFHelper, Script, and RTestRecordData references provided by the other constructors.

RDDGUIUtilities

public RDDGUIUtilities(STAFHelper helper,
                       Script script,
                       LogUtilities log)

Constructor providing the STAFHelper and Script needed by the instance for proper operation. For proper operation, the caller must still setTestRecordData. This constructor would be used when the RTestRecordData object to be used has not yet been instanced.

Parameters:

helper - The STAFHelper for performing STAF requests.

script - The Script (RationalTestScript) needed for RobotJ functions.

RDDGUIUtilities

public RDDGUIUtilities(STAFHelper helper,
                       Script script,
                       RTestRecordData data,
                       LogUtilities log)

Constructor providing the STAFHelper, Script, and RTestRecordData needed by the instance for proper operation.

Parameters:

helper - The STAFHelper for performing STAF requests.

script - The Script (RationalTestScript) needed for RobotJ functions.

data - The RTestRecordData needed for getting and updated TestRecordData.

Method Detail

setScript

public void setScript(Script script)

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

getScript

public Script getScript()

registerAppMap

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

Register an AppMap for use. If the map has not been opened by STAF, then we will attempt to open it.

Overrides:

registerAppMap in class DDGUIUtilities

Parameters:

mapname - the name of the map to register/open. This will be the same name used by the SAFSMAPS service to identify the AppMap.

mapfile - the filename of the file in the event we have to open it. This can be a relative or fullpath filename depending on how the SAFSMAPS service was configured. If mapfile is null, the underlying routines will attempt to use mapname as the mapfile filename.

Returns:

true if the map is registered, already registered, or successfully opened.

clearAppMapCache

public void clearAppMapCache(java.lang.String mapname)

clear a single local App Map cache of all old references. Here we also override and clear all registered TestObjects.

Overrides:

clearAppMapCache in class DDGUIUtilities

Parameters:

mapname - of the App Map to clear

See Also:

Script.localUnregisterAll()

clearAllAppMapCaches

public void clearAllAppMapCaches()

clear all known local App Maps' caches. Here we also override and clear all registered TestObjects.

Overrides:

clearAllAppMapCaches in class DDGUIUtilities

See Also:

Script.localUnregisterAll()

getParentTestObject

public TopLevelTestObject getParentTestObject(TestObject obj)

Attempt to retrieve either a TopLevelTestObject or BrowserTestObject, based on if it is a browser or not.

Parameters:

obj - a TestObject

Returns:

TestObject, either TopLevelTestObject or BrowserTestObject

getTestObject

public TestObject getTestObject(java.lang.String mapname,
                                java.lang.String windowName,
                                java.lang.String childName)

Attempt to retrieve a TestObject using the named references; this version calls the other version, passing 'false' to param 'ignoreCache'

First we see if the object is already cached in the TestRecordData.
Then we will see if it is already cached in our internal AppMap storage.
Then we will attempt to locate the object in the available RobotJ Object Map.

If not in any of these places, we will then attempt to locate the object by traversing the TestObject hierarchy in all supported test domains. The routine will require recognition strings retrieved from the external SAFSMAPS AppMap to identify parent and child components during this search.

The mapname is expected to already be open and registered prior to this call. If it is not, we will make an attempt to open/register the AppMap using the mapname provided. However, success on this is dependent on how the SAFSMAPS service was configured at launch and the extent of path information available in mapname.

Parameters:

mapname - the name of the stored AppMap

windowName - the name of the parent object to retrieve. This cannot be null as we always look for a parent object prior to walking the tree to look for its child.

childName - the name of the child object to find. If the parent object is actually the item of interest, then provide windowName as the childName as well.

Returns:

TestObject proxy for the object or null if it was not found or an error occurred.

getTestObject

public TestObject getTestObject(java.lang.String mapname,
                                java.lang.String windowName,
                                java.lang.String childName,
                                boolean ignoreCache)

Attempt to retrieve a TestObject using the named references; this version calls the other version, passing 'false' to param 'ignoreCache', and passing null to 'gather'

First we see if the object is already cached in the TestRecordData.
Then we will see if it is already cached in our internal AppMap storage.
Then we will attempt to locate the object in the available RobotJ Object Map.

If not in any of these places, we will then attempt to locate the object by traversing the TestObject hierarchy in all supported test domains. The routine will require recognition strings retrieved from the external SAFSMAPS AppMap to identify parent and child components during this search.

The mapname is expected to already be open and registered prior to this call. If it is not, we will make an attempt to open/register the AppMap using the mapname provided. However, success on this is dependent on how the SAFSMAPS service was configured at launch and the extent of path information available in mapname.

Parameters:

mapname - the name of the stored AppMap

windowName - the name of the parent object to retrieve. This cannot be null as we always look for a parent object prior to walking the tree to look for its child.

childName - the name of the child object to find. If the parent object is actually the item of interest, then provide windowName as the childName as well.

ignoreCache - will ignore the cached TestObject, and refind it if true.

Returns:

TestObject proxy for the object or null if it was not found or an error occurred.

getTestObject

public TestObject getTestObject(java.lang.String mapname,
                                java.lang.String windowName,
                                java.lang.String childName,
                                boolean ignoreCache,
                                java.util.List gather)

Attempt to retrieve a TestObject using the named references.

First we see if the object is already cached in the TestRecordData.
Then we will see if it is already cached in our internal AppMap storage.
Then we will attempt to locate the object in the available RobotJ Object Map.

If not in any of these places, we will then attempt to locate the object by traversing the TestObject hierarchy in all supported test domains. The routine will require recognition strings retrieved from the external SAFSMAPS AppMap to identify parent and child components during this search.

The mapname is expected to already be open and registered prior to this call. If it is not, we will make an attempt to open/register the AppMap using the mapname provided. However, success on this is dependent on how the SAFSMAPS service was configured at launch and the extent of path information available in mapname.

Parameters:

mapname - the name of the stored AppMap

windowName - the name of the parent object to retrieve. This cannot be null as we always look for a parent object prior to walking the tree to look for its child.

childName - the name of the child object to find. If the parent object is actually the item of interest, then provide windowName as the childName as well.

ignoreCache - will ignore the cached TestObject, and refind it if true.

gather, - List containing names matched, if null, then match first name

Returns:

TestObject proxy for the object or null if it was not found or an error occurred.

getTestObject

public TestObject getTestObject(java.lang.String mapname,
                                java.lang.String windowName,
                                java.lang.String childName,
                                boolean ignoreCache,
                                java.lang.String nameString)

Attempt to retrieve a TestObject using the named references.

First we see if the object is already cached in the TestRecordData.
Then we will see if it is already cached in our internal AppMap storage.
Then we will attempt to locate the object in the available RobotJ Object Map.

If not in any of these places, we will then attempt to locate the object by traversing the TestObject hierarchy in all supported test domains. The routine will require recognition strings retrieved from the external SAFSMAPS AppMap to identify parent and child components during this search.

The mapname is expected to already be open and registered prior to this call. If it is not, we will make an attempt to open/register the AppMap using the mapname provided. However, success on this is dependent on how the SAFSMAPS service was configured at launch and the extent of path information available in mapname.

Parameters:

mapname - the name of the stored AppMap

windowName - the name of the parent object to retrieve. This cannot be null as we always look for a parent object prior to walking the tree to look for its child.

childName - the name of the child object to find. If the parent object is actually the item of interest, then provide windowName as the childName as well.

ignoreCache - will ignore the cached TestObject, and refind it if true.

nameString, - name of the actual component, (childName should end in Name=*)

Returns:

TestObject proxy for the object or null if it was not found or an error occurred.

waitForObject

public int waitForObject(java.lang.String mapName,
                         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". Uses RFT's 'WAIT_FOR_EXISTENCE_DELAY_BETWEEN_RETRIES' between search iterations.

Specified by:

waitForObject in class DDGUIUtilities

Parameters:

mapName - 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.

Throws:

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

See Also:

localWaitForObject(String, String, String, long, boolean)

findPropertyMatchedChild

public java.lang.Object findPropertyMatchedChild(java.lang.Object testobject,
                                                 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.

Uses StringUtils.isCaseContainsMatch

Specified by:

findPropertyMatchedChild in class DDGUIUtilities

Parameters:

testobject - -- the object whose children will be evaluated. This is expected to be castable to a TestObject instance.

property - -- the property of each child that will be evaluated. The property is expected to be a Value Property 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 object whose property value matches accordingly; or,
null if a suitable match is not found.

Throws:

SAFSObjectNotFoundException - if no matching child object is found.

See Also:

StringUtils.isCaseContainsMatch(String,String,boolean)

setActiveWindow

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

"Activate" the specified component's topmost parent.

Specified by:

setActiveWindow in class DDGUIUtilities

Parameters:

mapName - 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.

Throws:

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

listMapElements

public void listMapElements()

Purpose: list Map elements
Side Effects:
Assumptions: none

Parameters:

script, - Object (Script)

listTopLevelObjects

public void listTopLevelObjects()

Purpose: list Map elements
Side Effects:
Assumptions: none

Parameters:

script, - Object (Script)

extractListItems

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

Purpose: extract a list of items from a TestObject. The item is either a String (for JList) or GuiTestObject (for JComboBox), for example.
This is the pseudo code for GuiTestObject items:
for(int i=0; i GuiTestObject item = (GuiTestObject) ((GuiSubitemTestObject)obj).getSubitem(script.localAtIndex(i));
result.add(item.getProperty(itemProp));
}

This is the pseudo code for String items:
for(int i=0; i String item = (String) ((GuiSubitemTestObject)obj).getSubitem(script.localAtIndex(i));
result.add(item);
}
Assumptions: obj is of type GuiSubitemTestObject

Specified by:

extractListItems in class DDGUIUtilities

Parameters:

obj, - Object (actually of type GuiSubitemTestObject)

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

itemProp, - String, the property which will contain

Returns:

List

Throws:

SAFSException

getListItem

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

Purpose: get a list item from a TestObject. The item is either a String (for JList) or GuiTestObject (for JComboBox), for example.
This is the pseudo code for GuiTestObject items:
GuiTestObject item = (GuiTestObject) ((GuiSubitemTestObject)obj).getSubitem(script.localAtIndex(i));
result.add(item.getProperty(itemProp));

This is the pseudo code for String items:
String item = (String) ((GuiSubitemTestObject)obj).getSubitem(script.localAtIndex(i));
result.add(item);
Assumptions: obj is of type GuiSubitemTestObject

Specified by:

getListItem in class DDGUIUtilities

Parameters:

obj, - Object (actually of type GuiSubitemTestObject)

i, - int, index into object

itemProp, - String, the property which will contain

Returns:

String

Throws:

SAFSException

extractMenuBarItems

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

required implementation for superclass

Specified by:

extractMenuBarItems in class DDGUIUtilities

Returns:

org.safs.Tree

Throws:

SAFSException

extractMenuItems

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

required implementation for superclass

Specified by:

extractMenuItems in class DDGUIUtilities

Returns:

org.safs.Tree

Throws:

SAFSException

listAllProperties

protected void listAllProperties(TestObject obj,
                                 java.lang.String str)

listProperties

protected void listProperties(TestObject obj)

listNonValueProperties

protected void listNonValueProperties(TestObject obj)

listMethods

protected void listMethods(TestObject obj)

getHtmlDocumentObject

public static TestObject getHtmlDocumentObject(TestObject obj)

Parameters:

obj - descendant TestObject in an Html.HtmlDocument

Returns:

Html.HtmlDocument TestObject or null

getHtmlDocTitle

public static java.lang.String getHtmlDocTitle(TestObject obj)

Parameters:

obj - TestObject expected to support 'title' or '.title' properties

Returns:

value of title or .title property or an empty String.

getGuiTestObject

public static GuiTestObject getGuiTestObject(TestObject obj)

Cast TestObject to GuiTestObject or create new GuiTestObject(ob).

Parameters:

obj - TestObject expected to be cast or created as GuiTestObject.

Returns:

GuiTestObject or null.