org.safs.abbot.jvmagent

Class JVMAgent

java.lang.Object

java.rmi.server.RemoteObject

java.rmi.server.RemoteServer

java.rmi.server.UnicastRemoteObject

org.safs.rmi.engine.RemoteRoot

org.safs.rmi.engine.AgentImpl

org.safs.abbot.jvmagent.JVMAgent

All Implemented Interfaces:

java.io.Serializable, java.rmi.Remote, Agent, SubItemsAgent

public class JVMAgent
extends AgentImpl

This is a concrete extension of a SAFS AgentImpl for Abbot This class is inserted into each JVM by our Bootstrap AgentClassLoader and subsequently communicates with our RMI "server-side" AServerImpl for automated testing.

To insert this class via the AgentClassLoader the following minimum settings must appear in the safsjvmagent.properties file:

safsjvmagent.properties:

safs.jvmagent.classes=org.safs.abbot.jvmagent.JVMAgent
safs.jvmagent.classpath=<pathto>\abbot.jar;c:/safs/lib/jaccess.jar;c:/safs/lib/safs.jar;c:/safs/lib/jakarta-regexp-1.3.jar;

See Also:

AgentImpl, ServerImpl, AServerImpl, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.safs.rmi.engine.AgentImpl

AgentImpl.ServerMonitor, AgentImpl.STAFMonitor

Nested classes/interfaces inherited from class org.safs.rmi.engine.RemoteRoot

RemoteRoot.ShutdownHook

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_ABBOT_AGENT 'SAFSAbbotJVMAgent': Unique Agent remoteType.
static java.lang.String	ROOT_JVMAGENT_PACKAGE "org.safs.abbot.jvmagent.agents" The root package for embedded SAFS JVM Agents for Abbot.

Fields inherited from class org.safs.rmi.engine.AgentImpl

DEFAULT_RMI_AGENT, DEFAULT_RMI_SERVER, monitor, objID, server, serverName, shutdown, stafHelper, stafmonitor, stafshutdown

Fields inherited from class org.safs.rmi.engine.RemoteRoot

remoteType

Fields inherited from class java.rmi.server.RemoteObject

ref

Constructor Summary

Constructors

Constructor and Description
JVMAgent() Constructor for JVMAgent.

Method Summary

Methods

Modifier and Type	Method and Description
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 local parent (Integer ID).
java.lang.Object[]	getChildren(java.lang.Object parent) Return the children available in the local parent (Integer ID).
java.lang.String	getClassName(java.lang.Object object) Return the class name of the provided object represented as an Integer hashcode previously sent over to the Server object.
protected java.awt.Component	getComponent(java.lang.Integer hashcode) Used internally to find the Component matching the stored Integer hashcode.
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).
java.lang.Object	getMatchingPathObject(java.lang.Object object, java.lang.String path) 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) Default no-op simply throws SAFSSubItemsAgentUnsupportedRuntimeException("SubItemAtIndex Unsupported").
java.lang.String[]	getSuperClassNames(java.lang.Object object) Return an Array of the complete superclass hierarchy of the provided object represented as an Integer hashcode previously sent over to the Server object.
java.lang.String	getText(java.lang.Object object) Retrieve the displayed text value of the object if the object has a text value.
int	getTopLevelCount() Returns the number of Root Windows known to the Abbot WindowTracker or 0 if there are no known Root Windows in this JVM.
java.lang.Object[]	getTopLevelWindows() Return array of Integer IDs representing keys to stored ComponentItems.
boolean	isMatchingPath(java.lang.Object object, java.lang.String path) 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 specified 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) An Agent may throw various types of Agent-specific RuntimeExceptions depending upon failure modes.
void	setActiveWindow(java.lang.Object object) Make the Window/Component active.

Methods inherited from class org.safs.rmi.engine.AgentImpl

debugLogSystemProperties, finalize, getAgentID, getAgentName, initialize, ping, runCommand, shutdown

Methods inherited from class org.safs.rmi.engine.RemoteRoot

rebindLocalRMIRegistry

Methods inherited from class java.rmi.server.UnicastRemoteObject

clone, exportObject, exportObject, exportObject, unexportObject

Methods inherited from class java.rmi.server.RemoteServer

getClientHost, getLog, setLog

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_ABBOT_AGENT

public static final java.lang.String DEFAULT_ABBOT_AGENT

'SAFSAbbotJVMAgent': Unique Agent remoteType. Note: Cannot begin with 'SAFS/Abbot' or the SAFS/Abbot engine will not launch due to the implementation of STAFHelper.isToolAvailable().

See Also:

org.safs.STAFHelper#isToolAvailable(), Constant Field Values

ROOT_JVMAGENT_PACKAGE

public static final java.lang.String ROOT_JVMAGENT_PACKAGE

"org.safs.abbot.jvmagent.agents" The root package for embedded SAFS JVM Agents for Abbot. This is primarily for instancing the LocalAgentFactory.

See Also:

org.safs.jvmagent.LocalAgentFactory#LocalAgentFactory(String), Constant Field Values

Constructor Detail

JVMAgent

public JVMAgent()
         throws java.rmi.RemoteException

Constructor for JVMAgent.

Throws:

java.rmi.RemoteException

Method Detail

getTopLevelCount

public int getTopLevelCount()
                     throws java.rmi.RemoteException,
                            java.lang.Exception

Returns the number of Root Windows known to the Abbot WindowTracker or 0 if there are no known Root Windows in this JVM.

Specified by:

getTopLevelCount in interface Agent

Overrides:

getTopLevelCount in class AgentImpl

Returns:

int count top-level windows in this JVM.

Throws:

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getTopLevelCount()

getTopLevelWindows

public java.lang.Object[] getTopLevelWindows()
                                      throws java.rmi.RemoteException,
                                             java.lang.Exception

Return array of Integer IDs representing keys to stored ComponentItems. A zero-length Object array if there are none.

Specified by:

getTopLevelWindows in interface Agent

Overrides:

getTopLevelWindows in class AgentImpl

Returns:

Integer[] of top-level window IDs for this JVM.

Throws:

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getTopLevelWindows()

getChildCount

public int getChildCount(java.lang.Object parent)
                  throws java.rmi.RemoteException,
                         java.lang.Exception

Return the number of children available in the local parent (Integer ID).

Specified by:

getChildCount in interface Agent

Overrides:

getChildCount in class AgentImpl

Parameters:

Integer - ID of parent component.

Returns:

int count of known children for the parent.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - parent") if the provided parent cannot be located.

SAFSActionErrorRuntimeException(x.getMessage(), - x) if an unexpected Exception is thrown from a LocalAgentFactory derived Agent.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getChildCount(Object)

getChildren

public java.lang.Object[] getChildren(java.lang.Object parent)
                               throws java.rmi.RemoteException,
                                      java.lang.Exception

Return the children available in the local parent (Integer ID).

Specified by:

getChildren in interface Agent

Overrides:

getChildren in class AgentImpl

Parameters:

Integer - ID of parent component.

Returns:

Integer[] of child IDs.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - parent") if the provided parent cannot be located.

SAFSActionErrorRuntimeException(x.getMessage(), - x) if an unexpected Exception is thrown from

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getChildren(Object)

setActiveWindow

public void setActiveWindow(java.lang.Object object)
                     throws java.rmi.RemoteException,
                            java.lang.Exception

Make the Window/Component active. Ideally, bring the Window forward if it is not already the topmost window. Setting the Window "active", however, should not remove keyboard focus from one of its child components.

The object should have been found to be a valid Component object via waitForObject and isValid function calls.

Specified by:

setActiveWindow in interface Agent

Overrides:

setActiveWindow in class AgentImpl

Parameters:

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

Throws:

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided object cannot be located.

java.rmi.RemoteException

java.lang.Exception

getComponent

protected java.awt.Component getComponent(java.lang.Integer hashcode)

Used internally to find the Component matching the stored Integer hashcode.

Returns:

Component or null.

getClassName

public java.lang.String getClassName(java.lang.Object object)
                              throws java.rmi.RemoteException,
                                     java.lang.Exception

Return the class name of the provided object represented as an Integer hashcode previously sent over to the Server object.

Specified by:

getClassName in interface Agent

Overrides:

getClassName in class AgentImpl

Parameters:

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

Returns:

String Class name of the object.

Throws:

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided object cannot be located.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getClassName(Object)

getSuperClassNames

public java.lang.String[] getSuperClassNames(java.lang.Object object)
                                      throws java.rmi.RemoteException,
                                             java.lang.Exception

Return an Array of the complete superclass hierarchy of the provided object represented as an Integer hashcode previously sent over to the Server object.

Specified by:

getSuperClassNames in interface Agent

Overrides:

getSuperClassNames in class AgentImpl

Parameters:

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

Returns:

String[] Class names for the superclass hierarchy.

Throws:

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided object cannot be located.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getSuperClassNames(Object)

getPropertyNames

public java.lang.String[] getPropertyNames(java.lang.Object object)
                                    throws java.rmi.RemoteException,
                                           java.lang.Exception

Retrieve the list of available properties for the object.

Specified by:

getPropertyNames in interface Agent

Overrides:

getPropertyNames in class AgentImpl

Parameters:

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

Returns:

String[] the names of available properties.

Throws:

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided object cannot be located.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getProperty(Object, String)

getProperty

public java.lang.String getProperty(java.lang.Object object,
                           java.lang.String property)
                             throws java.rmi.RemoteException,
                                    java.lang.Exception

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

Specified by:

getProperty in interface Agent

Overrides:

getProperty in class AgentImpl

Parameters:

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

property - -- the case-sensitive name of the property to seek.

Returns:

String the text value of the object property. Since property values can theoretically legally be zero-length, a null value will be returned if no value exists for the object.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSInvalidActionArgumentRuntimeException(property)

SAFSActionErrorRuntimeException(x.getMessage(), - x) if an unexpected Exception is thrown from

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getProperty(Object, String)

getCaption

public java.lang.String getCaption(java.lang.Object object)
                            throws java.rmi.RemoteException,
                                   java.lang.Exception

Retrieve the Caption of the object if one exits.

Specified by:

getCaption in interface Agent

Overrides:

getCaption in class AgentImpl

Parameters:

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

Returns:

String the caption of the object.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSActionUnsupportedRuntimeException("Caption - Unsupported") if the action is unsupported.

SAFSActionErrorRuntimeException(x.getMessage(), - x) if an unexpected Exception is thrown from

java.lang.NoSuchFieldException - if the object does not provide a caption.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getCaption(Object)

getName

public java.lang.String getName(java.lang.Object object)
                         throws java.rmi.RemoteException,
                                java.lang.Exception

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

Specified by:

getName in interface Agent

Overrides:

getName in class AgentImpl

Parameters:

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

Returns:

String the name of the object.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSActionUnsupportedRuntimeException("Name - Unsupported") if the action is unsupported.

SAFSActionErrorRuntimeException(x.getMessage(), - x) if an unexpected Exception is thrown from

java.lang.NoSuchFieldException - if the object does not provide a name.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getName(Object)

getID

public java.lang.String getID(java.lang.Object object)
                       throws java.rmi.RemoteException,
                              java.lang.Exception

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

Specified by:

getID in interface Agent

Overrides:

getID in class AgentImpl

Parameters:

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

Returns:

String the ID of the object.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSActionUnsupportedRuntimeException("ID - Unsupported") if the action is unsupported.

SAFSActionErrorRuntimeException(x.getMessage(), - x) if an unexpected Exception is thrown from

java.lang.NoSuchFieldException - if the object does not provide an ID.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getID(Object)

getText

public java.lang.String getText(java.lang.Object object)
                         throws java.rmi.RemoteException,
                                java.lang.Exception

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

Specified by:

getText in interface Agent

Overrides:

getText in class AgentImpl

Parameters:

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

Returns:

String the text value of the object. Since text values can theoretically legally be zero-length, a null value will be returned if no value exists for the object.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSActionUnsupportedRuntimeException("Text - Unsupported") if the action is unsupported.

SAFSActionErrorRuntimeException(x.getMessage(), - x) if an unexpected Exception is thrown from

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getText(Object)

getLevel

public int getLevel(java.lang.Object object)
             throws java.rmi.RemoteException,
                    java.lang.Exception

Return the Z-Order level of the object (generally for a top level window). This may not be possible with just Java because we want to know the z-order of all windows -- even non-Java windows -- on the system.

Specified by:

getLevel in interface Agent

Overrides:

getLevel in class AgentImpl

Parameters:

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

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:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSActionUnsupportedRuntimeException("Level - Unsupported") if the level cannot be determined.

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getLevel(Object)

isShowing

public boolean isShowing(java.lang.Object object)
                  throws java.rmi.RemoteException,
                         java.lang.Exception

Return true if the specified object is showing/visible.

The object has already been found to be a valid Component object via waitForObject and possibly isValid function calls.

Specified by:

isShowing in interface Agent

Overrides:

isShowing in class AgentImpl

Parameters:

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

Returns:

boolean

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSActionUnsupportedRuntimeException("Showing - Unsupported") if the action is unsupported.

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.isShowing(Object)

isValid

public boolean isValid(java.lang.Object object)
                throws java.rmi.RemoteException,
                       java.lang.Exception

Return true if the object is still valid/finadable in the JVM.

The object has usually been found to be a valid Component object via waitForObject.

Specified by:

isValid in interface Agent

Overrides:

isValid in class AgentImpl

Parameters:

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

Returns:

boolean true if the object is still valid/findable.

Throws:

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

java.rmi.RemoteException

java.lang.Exception

getStringData

public java.lang.String[][] getStringData(java.lang.Object object,
                                 java.lang.Object dataInfo)
                                   throws java.rmi.RemoteException,
                                          java.lang.Exception

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 Agent

Overrides:

getStringData in class AgentImpl

Parameters:

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

dataInfo - Allows us to specify what type of data we want returned. This will be specific to the types of objects from which we extract data. For example, Tables might provide "Contents" or "Headers" or other different types of data.

Returns:

String[][] 2D array of extracted data. 0-length arrays if no data is available or the ability to extract data is not supported.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSActionUnsupportedRuntimeException("StringData - Unsupported") if action is not supported.

SAFSInvalidActionArgumentRuntimeException(dataInfo) - if specified dataInfo is not supported.

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

java.lang.NoSuchMethodException - if the object type does not support the extraction of data or the specific type of data requested.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getStringData(Object, Object)

process

public TestRecordData process(java.lang.Object object,
                     TestRecordData testRecordData)
                       throws java.rmi.RemoteException,
                              java.lang.Exception

An Agent may throw various types of Agent-specific RuntimeExceptions depending upon failure modes. A Server should catch the RemoteException and Exception but test for subclasses of RuntimeException and let them through.

Specified by:

process in interface Agent

Overrides:

process in class AgentImpl

testRecordData - provides all the information needed by the Agent to perform an action. The RMI version of TestRecordData is likely going to be much sparser than the typical TestRecordHelper. It will also be pretty specific to the concrete implementations for the Server and Agent.

Returns:

TestRecordData which includes the statuscode

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSInvalidActionArgumentRuntimeException("Invalid - testRecordData") if the provided testRecordData is null.

SAFSRuntimeException - subclasses from the various Agents.

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.process(Object,TestRecordData)

getSubItemAtIndex

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

Description copied from class: AgentImpl

Default no-op simply throws SAFSSubItemsAgentUnsupportedRuntimeException("SubItemAtIndex Unsupported").

Specified by:

getSubItemAtIndex in interface SubItemsAgent

Overrides:

getSubItemAtIndex in class AgentImpl

Parameters:

object - reference (Integer) from which to locate the subitem.

index - of the subitem to retrieve.

Returns:

subitem object or String

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSSubItemsAgentUnsupportedRuntimeException - as necessay.

java.lang.IndexOutOfBoundsException - if index is invalid

SAFSObjectNotFoundException("Invalid - SubItem") if subitem at index cannot be retrieved.

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

java.rmi.RemoteException

java.lang.Exception

See Also:

SubItemsAgent.getSubItemAtIndex(Object,int)

getMatchingPathObject

public java.lang.Object getMatchingPathObject(java.lang.Object object,
                                     java.lang.String path)
                                       throws java.rmi.RemoteException,
                                              java.lang.Exception

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 Agent

Specified by:

getMatchingPathObject in interface SubItemsAgent

Overrides:

getMatchingPathObject in class AgentImpl

Parameters:

theObject--Object - proxy for the object to be evaluated.

thePath - information to locate another object or subitem relative to theObject. this is usually something like a menuitem or tree node where supported.

Returns:

Object child sub-object found relative to theObject

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSSubItemsAgentUnsupportedRuntimeException - as necessay.

SAFSObjectNotFoundException("Invalid - SubItem") if subitem at index cannot be retrieved.

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

java.rmi.RemoteException

java.lang.Exception

See Also:

Agent.getMatchingPathObject(Object, String)

isMatchingPath

public boolean isMatchingPath(java.lang.Object object,
                     java.lang.String path)
                       throws java.rmi.RemoteException,
                              java.lang.Exception

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 Agent

Specified by:

isMatchingPath in interface SubItemsAgent

Overrides:

isMatchingPath in class AgentImpl

Parameters:

object--Object - proxy for the object to be evaluated.

path - information to locate another object or subitem relative to theObject. this is usually something like a menuitem or tree node where supported.

Returns:

true if the child sub-object was found relative to theObject.

Throws:

SAFSObjectNotFoundRuntimeException("Invalid - object") if the provided parent cannot be located.

SAFSSubItemsAgentUnsupportedRuntimeException - as necessay.

SAFSActionErrorRuntimeException - if an unexpected (design?) problem occurs.

java.rmi.RemoteException

java.lang.Exception

See Also:

org.safs.rmi.engine.Agent#getMatchingPath(Object, String)