org.safs.jvmagent.agents

Class ObjectAgent

java.lang.Object

org.safs.jvmagent.agents.ObjectAgent

All Implemented Interfaces:

AlternateAncestorUser, LocalAgent, LocalAgentFactoryUser, LocalSubItemsAgent

Direct Known Subclasses:

ComponentAgent

public class ObjectAgent
extends java.lang.Object
implements LocalAgent, LocalAgentFactoryUser, AlternateAncestorUser, LocalSubItemsAgent

Since:

FEB 16, 2005 Feb 17, 2006 (Szucs) extending the class with the LocalSubItemsAgent interface

Author:

Carl Nagle

Field Summary

Fields

Modifier and Type	Field and Description
protected LocalAgent	alternateAncestor
protected java.lang.String	alternateAncestorClassname AlternateAncestorUser implementation.
protected LocalAgentFactory	factory LocalAgentFactoryUser implementation.
static java.lang.String	objectType "Object" (Subclasses will override) The generic object type supported by this Agent helper class.

Constructor Summary

Constructors

Constructor and Description
ObjectAgent() Constructor for ObjectAgent.

Method Summary

Modifier and Type	Method and Description
LocalAgent	getAlternateAncestor() AlternateAncestorUser interface.
java.lang.String	getAlternateAncestorClassname() AlternateAncestorUser interface.
protected LocalAgent	getAncestorAgent() Used internally by processAncestor and subclasses to attempt to retrieve the alternateAncestor locally or via any stored LocalAgentFactory.
java.lang.String	getCaption(java.lang.Object object) Retrieve the Caption of the object if one exits.
int	getChildCount(java.lang.Object parent) Return the number of children available in the provided parent.
java.lang.Object[]	getChildren(java.lang.Object parent) Return an array representing the children of the provided parent object.
java.lang.String	getClassName(java.lang.Object object) Return the Class name of the object.
java.lang.String	getID(java.lang.Object object) Retrieve the ID of the object if the object has an ID.
int	getLevel(java.lang.Object object) Return the Z-Order level of the object (generally for a top level window).
LocalAgentFactory	getLocalAgentFactory() LocalAgentFactoryUser Interface.
java.lang.Object	getMatchingPathObject(java.lang.Object theObject, java.lang.String thePath) Mechanism to retrieve a subitem/object identified by the provided Path.
java.lang.String	getName(java.lang.Object object) Retrieve the name of the object if the object is named.
java.lang.String	getProperty(java.lang.Object object, java.lang.String property) Retrieve the property value of the object if the object has the property.
java.lang.String[]	getPropertyNames(java.lang.Object object) Retrieve the list of available properties for the object.
java.lang.String[][]	getStringData(java.lang.Object object, java.lang.Object dataInfo) Return whatever data is extractable (normally visible) from the object.
java.lang.Object	getSubItemAtIndex(java.lang.Object object, int index) Return the subitem at the specified index from the given object.
java.lang.String[]	getSuperClassNames(java.lang.Object object) Return the array of all superclass names for the object.
java.lang.String	getText(java.lang.Object object) Retrieve the displayed text value of the object if the object has a text value.
boolean	isMatchingPath(java.lang.Object theObject, java.lang.String thePath) Mechanism to determine if the object contains a subitem/object identified by the provided Path.
boolean	isShowing(java.lang.Object object) Return true if the object is showing/visible.
boolean	isValid(java.lang.Object object) Return true if the object is still valid/finadable in the JVM.
TestRecordData	process(java.lang.Object object, TestRecordData testRecordData) Process the action provided in the testRecordData.
TestRecordData	processAncestor(java.lang.Object object, TestRecordData testRecordData) Attempts to retrieve the alternateAncestor if defined and execute process on that.
void	setAlternateAncestor(LocalAgent ancestor) AlternateAncestorUser interface.
void	setAlternateAncestorClassname(java.lang.String ancestorClassname) AlternateAncestorUser interface.
void	setLocalAgentFactory(LocalAgentFactory factory) LocalAgentFactoryUser Interface.

Methods inherited from class java.lang.Object

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

Field Detail

objectType

public static final java.lang.String objectType

"Object" (Subclasses will override) The generic object type supported by this Agent helper class. The generic object type is that returned by GuiClassData.getGenericObjectType. Example: Component Button Table etc..

See Also:

GuiClassData.getGenericObjectType(String), Constant Field Values

factory

protected LocalAgentFactory factory

LocalAgentFactoryUser implementation. storage for LocalAgentFactory that instanced us.

alternateAncestorClassname

protected java.lang.String alternateAncestorClassname

AlternateAncestorUser implementation. Subclasses can specify the fullclassname of an alternate LocalAgent instance that should be used to satisfy "super.process()" calls instead of the class's true superclass ancestor. For example, org.safs.abbot.JFrameAgent might specify "org.safs.abbot.FrameAgent" as the chosen LocalAgent to handle unknown actions instead of its true superclass "org.safs.jvmagent.JFrameAgent". If no alternate processAncestor is specified then the true superclass is used when forwarding process calls.

alternateAncestor

protected LocalAgent alternateAncestor

Constructor Detail

ObjectAgent

public ObjectAgent()

Constructor for ObjectAgent.

Method Detail

getChildCount

public int getChildCount(java.lang.Object parent)

Description copied from interface: LocalAgent

Return the number of children available in the provided parent.

Specified by:

getChildCount in interface LocalAgent

Parameters:

parent - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

0

Throws:

SAFSActionUnsupportedRuntimeException("ChildCount - Unsupported");

See Also:

LocalAgent.getChildCount(Object)

getChildren

public java.lang.Object[] getChildren(java.lang.Object parent)

Description copied from interface: LocalAgent

Return an array representing the children of the provided parent object.

Specified by:

getChildren in interface LocalAgent

Parameters:

parent - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

new String[0]

Throws:

SAFSActionUnsupportedRuntimeException("Children - Unsupported");

See Also:

LocalAgent.getChildren(Object)

getCaption

public java.lang.String getCaption(java.lang.Object object)

Description copied from interface: LocalAgent

Retrieve the Caption of the object if one exits.

Specified by:

getCaption in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

null

Throws:

SAFSActionUnsupportedRuntimeException("Caption - Unsupported");

See Also:

LocalAgent.getCaption(Object)

getName

public java.lang.String getName(java.lang.Object object)

Description copied from interface: LocalAgent

Retrieve the name of the object if the object is named.

Specified by:

getName in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

null

Throws:

SAFSActionUnsupportedRuntimeException("Name - Unsupported");

See Also:

LocalAgent.getName(Object)

getID

public java.lang.String getID(java.lang.Object object)

Description copied from interface: LocalAgent

Retrieve the ID of the object if the object has an ID.

Specified by:

getID in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

null

Throws:

SAFSActionUnsupportedRuntimeException("ID - Unsupported");

See Also:

LocalAgent.getID(Object)

getText

public java.lang.String getText(java.lang.Object object)

Description copied from interface: LocalAgent

Retrieve the displayed text value of the object if the object has a text value.

Specified by:

getText in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

null

Throws:

SAFSActionUnsupportedRuntimeException("Text - Unsupported");

See Also:

LocalAgent.getText(Object)

getPropertyNames

public java.lang.String[] getPropertyNames(java.lang.Object object)

Description copied from interface: LocalAgent

Retrieve the list of available properties for the object.

Specified by:

getPropertyNames in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

String[] of derived property names

See Also:

LocalAgent.getPropertyNames(Object)

getProperty

public java.lang.String getProperty(java.lang.Object object,
                                    java.lang.String property)

Description copied from interface: LocalAgent

Retrieve the property value of the object if the object has the property.

Specified by:

getProperty in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

property - -- case-sensitive name of the property to retrieve

Returns:

property value which may be null

Throws:

SAFSInvalidActionArgumentRuntimeException(property)

SAFSObjectNotFoundRuntimeException("Invalid - object")

See Also:

LocalAgent.getProperty(Object, String)

getClassName

public java.lang.String getClassName(java.lang.Object object)

Description copied from interface: LocalAgent

Return the Class name of the object. For example, we may get "javax.swing.JFrame" or the name of the subclass if it is a subclass of JFrame.

Specified by:

getClassName in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

object.getClass().getName()

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object")

See Also:

LocalAgent.getClassName(Object)

getLevel

public int getLevel(java.lang.Object object)

Description copied from interface: LocalAgent

Return the Z-Order level of the object (generally for a top level window).

Specified by:

getLevel in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

int z-order value of the object among all objects if this can be determined. 0 normally indicates the topmost Window. 1 is normally the Window behind that, etc..

Throws:

SAFSActionUnsupportedRuntimeException("Level - Unsupported");

See Also:

LocalAgent.getLevel(Object)

isShowing

public boolean isShowing(java.lang.Object object)

Description copied from interface: LocalAgent

Return true if the object is showing/visible.

Specified by:

isShowing in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

false

Throws:

new - SAFSActionUnsupportedRuntimeException("Showing Unsupported");

See Also:

LocalAgent.isShowing(Object)

isValid

public boolean isValid(java.lang.Object object)

Return true if the object is still valid/finadable in the JVM. This is normally already handled by the Agent using the LocalAgentFactory and finding the actual Component objects in the JVM. Thus, this function is not normally called in this class or its subclasses.

Specified by:

isValid in interface LocalAgent

Parameters:

object - An object from getTopLevelWindows or from a previous call to getChildren.

Returns:

boolean true if the object is not null.

getSuperClassNames

public java.lang.String[] getSuperClassNames(java.lang.Object object)

Description copied from interface: LocalAgent

Return the array of all superclass names for the object. This should return the Class hierarchy for the object all the way to Class Object. A 0-length array will be returned if there are none (Class Object).

Specified by:

getSuperClassNames in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

Returns:

Array of class names. String[0] = "java.lang.Object" and on up.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - Object")

See Also:

LocalAgent.getSuperClassNames(Object)

getSubItemAtIndex

public java.lang.Object getSubItemAtIndex(java.lang.Object object,
                                          int index)
                                   throws java.lang.Exception

Description copied from interface: LocalSubItemsAgent

Return the subitem at the specified index from the given object. This may be a ComboBox item, a List item, or a Tree node, etc... The returned item may be a component object or perhaps a String representing the text of the item. The return type is object specific.

Specified by:

getSubItemAtIndex in interface LocalSubItemsAgent

Parameters:

object - reference from which to locate the subitem.

index - of the subitem to retrieve.

Returns:

subitem object or String

Throws:

java.lang.Exception

getMatchingPathObject

public java.lang.Object getMatchingPathObject(java.lang.Object theObject,
                                              java.lang.String thePath)
                                       throws java.lang.Exception

Description copied from interface: LocalAgent

Mechanism to retrieve a subitem/object identified by the provided Path. Path is hierarchical information showing parent->child relationships separated by '->'. This is often used in Menus and Trees.

Ex:

File->Exit
Root->Branch->Leaf

Specified by:

getMatchingPathObject in interface LocalAgent

Specified by:

getMatchingPathObject in interface LocalSubItemsAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

thePath -

Returns:

null

Throws:

SAFSSubItemsAgentUnsupportedRuntimeException("MatchingPathObject - Unsupported")

java.lang.Exception

See Also:

LocalAgent.getMatchingPathObject(Object, String)

isMatchingPath

public boolean isMatchingPath(java.lang.Object theObject,
                              java.lang.String thePath)
                       throws java.lang.Exception

Description copied from interface: LocalAgent

Mechanism to determine if the object contains a subitem/object identified by the provided Path. Path is hierarchical information showing parent->child relationships separated by '->'. This is often used in Menus and Trees.

Ex:

File->Exit
Root->Branch->Leaf

Specified by:

isMatchingPath in interface LocalAgent

Specified by:

isMatchingPath in interface LocalSubItemsAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

thePath -

Returns:

false

Throws:

SAFSSubItemsAgentUnsupportedRuntimeException("MatchingPath - Unsupported")

java.lang.Exception

See Also:

LocalAgent.isMatchingPath(Object, String)

getStringData

public java.lang.String[][] getStringData(java.lang.Object object,
                                          java.lang.Object dataInfo)

Description copied from interface: LocalAgent

Return whatever data is extractable (normally visible) from the object. Some objects like Lists may only require 1D of the 2D array. Some objects like Tables will use the full 2D array. Objects like Trees may use special techniques of storing their multi-dimensional data in the 2D array.

Specified by:

getStringData in interface LocalAgent

Parameters:

object - -- the actual object or component to be checked -- not a pseudo reference.

dataInfo -

Returns:

new String[0][0]

Throws:

SAFSActionUnsupportedRuntimeException("StringData - Unsupported")

See Also:

LocalAgent.getStringData(Object, Object)

setLocalAgentFactory

public void setLocalAgentFactory(LocalAgentFactory factory)

LocalAgentFactoryUser Interface. Set the LocalAgentFactory used by the class instance. This is normally set by the LocalAgentFactory itself when the User is instanced.

Specified by:

setLocalAgentFactory in interface LocalAgentFactoryUser

getLocalAgentFactory

public LocalAgentFactory getLocalAgentFactory()

LocalAgentFactoryUser Interface. Retrieve any LocalAgentFactory set for this object. May be null if not set.

Specified by:

getLocalAgentFactory in interface LocalAgentFactoryUser

getAlternateAncestor

public LocalAgent getAlternateAncestor()

AlternateAncestorUser interface.

Specified by:

getAlternateAncestor in interface AlternateAncestorUser

setAlternateAncestor

public void setAlternateAncestor(LocalAgent ancestor)

AlternateAncestorUser interface.

Specified by:

setAlternateAncestor in interface AlternateAncestorUser

getAlternateAncestorClassname

public java.lang.String getAlternateAncestorClassname()

AlternateAncestorUser interface.

Specified by:

getAlternateAncestorClassname in interface AlternateAncestorUser

setAlternateAncestorClassname

public void setAlternateAncestorClassname(java.lang.String ancestorClassname)

AlternateAncestorUser interface.

Specified by:

setAlternateAncestorClassname in interface AlternateAncestorUser

getAncestorAgent

protected LocalAgent getAncestorAgent()

Used internally by processAncestor and subclasses to attempt to retrieve the alternateAncestor locally or via any stored LocalAgentFactory.

Returns:

LocalAgent alternateAncestor stored or retrieved from the LocalAgentFactory or a null if not set or available.

process

public TestRecordData process(java.lang.Object object,
                              TestRecordData testRecordData)

Process the action provided in the testRecordData. Subclasses will override this method as necessary.

Subclasses in the org.safs.jvmagent package should always attempt to processAncestor if they themselves do not handle the command in the testRecordData. This is shown below: if (testRecordData.getStatusCode() == StatusCodes.SCRIPT_NOT_EXECUTED) processAncestor(object, testRecordData); Subclasses in other packages like org.safs.abbot should typically always call super.process() if they themselves do not handle the command in the testRecordData. This is shown below: if (testRecordData.getStatusCode() == StatusCodes.SCRIPT_NOT_EXECUTED) super.process(object, testRecordData); In this way, the proper order of processing in-package classes and superclasses is maintained.

An Agent may throw various types of Agent-specific RuntimeExceptions depending upon failure modes.

Specified by:

process in interface LocalAgent

Parameters:

testRecordData - provides all the information needed by the Agent to perform the action and to get/set the process statuscode.

Returns:

TestRecordData with necessary info, especially the modified statuscode.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object")

SAFSObjectNotFoundRuntimeException("Invalid - testRecordData")

processAncestor

public TestRecordData processAncestor(java.lang.Object object,
                                      TestRecordData testRecordData)

Attempts to retrieve the alternateAncestor if defined and execute process on that. If no alternate ancestor is found then we simply exit without modifying anything.

Specified by:

processAncestor in interface AlternateAncestorUser