org.safs.rmi.engine

Interface Agent

All Superinterfaces:

java.rmi.Remote

All Known Implementing Classes:

AgentImpl

public interface Agent
extends java.rmi.Remote

Defines a generic SAFS Engine RMI Agent communicating with a SAFS Engine RMI Server.

A SAFS Engine RMI Server is the centralized controller that will talk with each RMI Agent embedded within each enabled JVM. This provides an RMI alternative to STAF for multi-JVM communications between the very visible SAFS Engine and the invisible Agents in each JVM.

The typical scenario here would be that a SAFS Engine like SAFS/Abbot would still present a single STAF-based event-driven interface for the TID and any other Driver wishing to use it, but underneath the engine will be communicating with multiple JVMs over localhost RMI.

The RMI Agent is normally automatically loaded into each enabled JVM as a Java Extension exploiting the Accessibility hooks in the JVM. This will be done through the SAFS Bootstrap AgentClassLoader.

This is somewhat analogous to how other tools like RobotJ, Robot, and WinRunner communicate with all running JVMs through a single script engine or controller.

Note: For consistent operation the safs.server.hostname needs to be set in code or on the command line before launching an Agent connecting to a SAFS RMI Server:

• In Code:
  System.setProperty("safs.server.hostname", "<rmi server ip>");
  System.setProperty("safs.server.hostname", "hostname.company.internal.net");

• Command line:
  -Dsafs.server.hostname=<rmi server ip>
  -Dsafs.server.hostname=hostname.company.internal.net

Author:

Carl Nagle FEB 01, 2005 Original Release

See Also:

Bootstrap, AgentClassLoader

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	SERVER_HOSTNAME_SYSTEM_PROPERTY 'safs.server.hostname' Name of the System Property signifying a remote SAFS RMI Server hostname to seek for a SAFS RMI Server.

Method Summary

Modifier and Type	Method and Description
java.rmi.server.ObjID	getAgentID() Returns an ObjID to uniquely identify the JVM Agent.
java.lang.String	getAgentName() Returns the name or remoteType of the JVM Agent.
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).
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.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.
int	getTopLevelCount() Return the number of currently active Top Level Windows.
java.lang.Object[]	getTopLevelWindows() Return an array representing the TopLevel windows in the Agent JVM.
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 specified object is showing/visible.
boolean	isValid(java.lang.Object object) Return true if the object is still valid/finadable in the JVM.
void	ping() A simple RUThere call.
TestRecordData	process(java.lang.Object object, TestRecordData testRecordData) Process the action provided in the testRecordData.
java.lang.Object	runCommand(java.lang.Object command) This is a "do anything" function that the Server and Clients have a private contract to implement.
void	setActiveWindow(java.lang.Object theObject) Attempts to set theObject as the active (topmost?) Window or Component in the JVM.
void	shutdown() The RMI Server will instruct the Agent to shutdown when the Server itself is being shutdown or finalized.

Field Detail

SERVER_HOSTNAME_SYSTEM_PROPERTY

static final java.lang.String SERVER_HOSTNAME_SYSTEM_PROPERTY

'safs.server.hostname' Name of the System Property signifying a remote SAFS RMI Server hostname to seek for a SAFS RMI Server.

See Also:

Constant Field Values

Method Detail

ping

void ping()
   throws java.rmi.RemoteException

A simple RUThere call. The server will generally receive a ConnectException thrown by RMI if the Agent cannot be called because it has gone away.

Throws:

java.rmi.RemoteException

getAgentID

java.rmi.server.ObjID getAgentID()
                          throws java.rmi.RemoteException

Returns an ObjID to uniquely identify the JVM Agent.

Throws:

java.rmi.RemoteException

getAgentName

java.lang.String getAgentName()
                       throws java.rmi.RemoteException

Returns the name or remoteType of the JVM Agent.

Throws:

java.rmi.RemoteException

process

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

Process the action provided in the testRecordData.

The Agent is not intended to be logging to STAF. Each Agent is intended to be strictly an RMI client that will attempt actions and return success or failure information to the controlling SAFS Engine RMI Server.

Parameters:

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:

java.rmi.RemoteException

java.lang.Exception

shutdown

void shutdown()
       throws java.rmi.RemoteException

The RMI Server will instruct the Agent to shutdown when the Server itself is being shutdown or finalized. The Agent does not have to unRegister from the Server in this case because the Server will already be disconnecting from the Agent.

The Agent should accept the shutdown request and initiate a new shutdown Thread so that the call to shutdown from the Server can immediately return.

The Agent will normally reset itself to an idle state where it is polling once again for the existence of another RMI Server object in the RMI Registry.

Throws:

java.rmi.RemoteException

getTopLevelCount

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

Return the number of currently active Top Level Windows.

Throws:

java.rmi.RemoteException

java.lang.Exception

getTopLevelWindows

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

Return an array representing the TopLevel windows in the Agent JVM.

Returns:

Object[] representing all active top level windows in the Agent JVM. This array will be Server/Agent specific and may be nothing more than arrays of the hashcodes used to uniquely identify objects in an Agent-maintained Hashtable. A zero-length array will be returned if no Top Level Windows are active.

Throws:

java.rmi.RemoteException

java.lang.Exception

getChildCount

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

Return the number of children available in the provided parent.

Throws:

java.rmi.RemoteException

java.lang.Exception

getChildren

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

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

Parameters:

parent - An object from getTopLevelWindows or from a previous call to getChildren. The parent is often one of the elements of the TopLevelWindow array or somewhere lower in that same hierarchy.

Returns:

Object[] representing all known children of the provided parent. This array will be Server/Agent specific and may be nothing more than arrays of the hashcodes used to uniquely identify objects in an Agent-maintained Hashtable. A zero-length array will be returned if the parent has no children.

Throws:

java.rmi.RemoteException

java.lang.Exception

getCaption

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

Retrieve the Caption of the object if one exits.

Parameters:

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

Returns:

String the caption of the object.

Throws:

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

java.rmi.RemoteException

java.lang.Exception

getName

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

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

Parameters:

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

Returns:

String the name of the object.

Throws:

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

java.rmi.RemoteException

java.lang.Exception

getID

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

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

Parameters:

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

Returns:

String the ID of the object.

Throws:

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

java.rmi.RemoteException

java.lang.Exception

getText

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.

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:

java.rmi.RemoteException

java.lang.Exception

getPropertyNames

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

Retrieve the list of available properties for the object.

Parameters:

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

Returns:

String[] the names of available properties.

Throws:

java.rmi.RemoteException

java.lang.Exception

getProperty

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

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

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:

java.rmi.RemoteException

java.lang.NoSuchFieldException

java.lang.Exception

getClassName

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

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.

Parameters:

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

Returns:

String Class name of the object.

Throws:

java.rmi.RemoteException

java.lang.Exception

getLevel

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

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

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:

java.rmi.RemoteException

java.lang.NoSuchFieldException

java.lang.Exception

getSuperClassNames

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

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

Parameters:

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

Returns:

String[] Class names for the superclass hierarchy.

Throws:

java.rmi.RemoteException

java.lang.Exception

getStringData

java.lang.String[][] getStringData(java.lang.Object object,
                                   java.lang.Object dataInfo)
                            throws java.rmi.RemoteException,
                                   java.lang.NoSuchMethodException,
                                   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.

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:

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

isShowing

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

Return true if the specified object is showing/visible.

Parameters:

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

Returns:

boolean

Throws:

java.rmi.RemoteException

java.lang.Exception

isValid

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.

Parameters:

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

Returns:

boolean true if the object is still valid/findable.

Throws:

java.rmi.RemoteException

java.lang.Exception

getMatchingPathObject

java.lang.Object getMatchingPathObject(java.lang.Object theObject,
                                       java.lang.String thePath)
                                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

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:

java.rmi.RemoteException

java.lang.Exception

isMatchingPath

boolean isMatchingPath(java.lang.Object theObject,
                       java.lang.String thePath)
                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

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:

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

Throws:

java.rmi.RemoteException

java.lang.Exception

runCommand

java.lang.Object runCommand(java.lang.Object command)
                     throws java.rmi.RemoteException,
                            java.lang.Exception

This is a "do anything" function that the Server and Clients have a private contract to implement. It essentially allows a Client/Server implementation to pass anything back and forth and act according to their shared designs.

For example, the Client and Server may have been coded to pass string commands back and forth and the string commands can be parsed to provide an unlimited number of command possibilities.

Parameters:

command - Object of a type expected by the Client implementation for this method.

Returns:

Object of a type expected by the Server implementation calling this method.

Throws:

java.rmi.RemoteException

java.lang.Exception

setActiveWindow

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

Attempts to set theObject as the active (topmost?) Window or Component in the JVM.

Parameters:

theObject - Object of a type expected by the Client implementation for this method.

Throws:

java.rmi.RemoteException

java.lang.Exception