org.safs.rmi.engine

Class ServerImpl

java.lang.Object

java.rmi.server.RemoteObject

java.rmi.server.RemoteServer

java.rmi.server.UnicastRemoteObject

org.safs.rmi.engine.RemoteRoot

org.safs.rmi.engine.ServerImpl

All Implemented Interfaces:

java.io.Serializable, java.rmi.Remote, LocalAgent, LocalServer, LocalSubItemsAgent, Server

public class ServerImpl
extends RemoteRoot
implements Server, LocalServer, LocalSubItemsAgent

A concrete implementation of our Server Interface for Java RMI test automation. Specific Engine subclasses will extend this for specific tools -- like Abbot or others.

The server communicates with remote Agents on the local machine acting as Java Enablers. The security policy for the JVM running this RMI server may need the additional permissions specified in:

SAFS\lib\java.policy

Normally this RMI Server would be instanced in a JVM we control -- like the TID or a SAFS Engine. Thus, these settings do not impact any AUT security policy since the AUT is running in a different JVM.

Because this is an RMI implementation, an additional Java rmic build process is necessary prior to creating the JAR file containing all classes. The Java rmic program creates the Skeletons and Stubs needed by Java RMI.

Execute Java rmic from the root directory of the Java project:

rmic -d . org.safs.rmi.engine.ServerImpl

Note: For consistent operation the java.rmi.server.hostname needs to be set in code or on the command line before launching an RMI Server:

• In Code:

  System.setProperty("java.rmi.server.hostname", "<rmi server ip>");

• Command line:
  

  -Djava.rmi.server.hostname=<rmi server ip>

Minimum java.policy permissions needed for successful execution:

      // Allow RMI server objects to receive requests on this machine on port 1024 or higher.
      permission java.net.SocketPermission "*:1024-", "connect,accept,resolve";
      permission java.lang.RuntimePermission "shutdownHooks";
      permission java.util.PropertyPermission "safs.*", "write,read";
      permission java.util.PropertyPermission "java.rmi.server.hostname", "write,read";
 

Author:

Carl Nagle FEB 02, 2005 Original Feb 20, 2006 (Szucs) correcting the getMatchingPathObject( ) method to return the correct AgentWindow object, Carl Nagle FEB 23, 2015 Updates supporting remote RMI Servers.

See Also:

Serialized Form

Nested Class Summary

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_RMI_SERVER 'SAFS/RMIEngineServer'
protected java.lang.String	serverName Name of Server object in rmi Naming registry.

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

DEFAULT_RMI_SERVER_HOST, PROPERTY_REGISTRY_PORT, PROPERTY_SERVER_PORT, registryPort, remoteType, serverHost

Fields inherited from class java.rmi.server.RemoteObject

ref

Fields inherited from interface org.safs.rmi.engine.Server

JAVA_RMI_SERVER_HOSTNAME_PROPERTY, SERVER_SYSTEM_PROPERTY

Constructor Summary

Constructors

Constructor and Description
ServerImpl() Constructor for ServerImpl.

Method Summary

Modifier and Type	Method and Description
protected void	finalize() Remove this server object from the RMI registry.
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 remote parent (AgentWindow).
java.lang.Object[]	getChildren(java.lang.Object parent) Return an array representing the children of the provided parent AgentWindow.
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 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) 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.
int	getTopLevelCount() Return the number of currently active Top Level Windows from all known Agents.
java.lang.Object[]	getTopLevelWindows() Return an AgentWindow array representing the TopLevel windows from all known Agents.
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 object is showing/visible.
boolean	isValid(java.lang.Object object) Return true if the object is still valid/finadable in the Remote JVM.
static void	main(java.lang.String[] args) Primarily a test entry point.
protected void	pingAgents() Simple routine to ping each registered agent to see if it is actually still there.
TestRecordData	process(java.lang.Object object, TestRecordData testRecordData) Process the action provided in the testRecordData.
void	register(Agent anAgent) A JVM Agent will register with the RMI Server after it has become available in the RMI Naming registry.
java.lang.Object	runCommand(java.lang.Object command) Default implementation throws SAFSActionUnsupportedRuntimeException("runCommand Unsupported").
void	setActiveWindow(java.lang.Object object) Make the provided object the "active" object or window (bring it forward).
void	unRegister(Agent anAgent) Uses a separate Thread to unRegister the Agent and perform other internal checks after the Agent is unregistered.

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

init, 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_RMI_SERVER

public static final java.lang.String DEFAULT_RMI_SERVER

'SAFS/RMIEngineServer'

See Also:

Constant Field Values

serverName

protected java.lang.String serverName

Name of Server object in rmi Naming registry. Subclasses should override the value. Defaults to DEFAULT_RMI_SERVER

Constructor Detail

ServerImpl

public ServerImpl()
           throws java.rmi.RemoteException

Constructor for ServerImpl. Sets our remoteType to DEFAULT_RMI_SERVER

Throws:

java.rmi.RemoteException

Method Detail

register

public void register(Agent anAgent)
              throws java.rmi.RemoteException

Description copied from interface: Server

A JVM Agent will register with the RMI Server after it has become available in the RMI Naming registry. The Agent usually is polling the registry at regular intervals waiting for the appropriate Server object to exist. The Server object is not created until the actual controlling SAFS Engine is launched.

Registering with the Server makes that remote JVM available for testing through the controlling SAFS Engine.

Specified by:

register in interface Server

Throws:

java.rmi.RemoteException

See Also:

Server.register(Agent)

unRegister

public void unRegister(Agent anAgent)
                throws java.rmi.RemoteException

Uses a separate Thread to unRegister the Agent and perform other internal checks after the Agent is unregistered. This should return to the calling Agent immediately so that we don't interfere with any remote JVM shutdowns.

Specified by:

unRegister in interface Server

Throws:

java.rmi.RemoteException

See Also:

Server.unRegister(Agent)

pingAgents

protected void pingAgents()

Simple routine to ping each registered agent to see if it is actually still there. The routine will unregister an agent when the attempt to contact it throws an exception. This can happen when a remote Agent's JVM does not call registered shutdown hooks and allow the Agent to gracefully unregister with the RMI server.

getTopLevelCount

public int getTopLevelCount()

Return the number of currently active Top Level Windows from all known Agents.

Specified by:

getTopLevelCount in interface LocalServer

See Also:

LocalServer.getTopLevelCount()

getTopLevelWindows

public java.lang.Object[] getTopLevelWindows()

Return an AgentWindow array representing the TopLevel windows from all known Agents.

Specified by:

getTopLevelWindows in interface LocalServer

Returns:

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

See Also:

LocalServer.getTopLevelWindows()

getChildCount

public int getChildCount(java.lang.Object parent)

Return the number of children available in the remote parent (AgentWindow).

Specified by:

getChildCount in interface LocalAgent

Throws:

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

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

See Also:

LocalAgent.getChildCount(Object)

getChildren

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

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

Specified by:

getChildren in interface LocalAgent

Parameters:

parent - An object (AgentWindow) 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:

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

Throws:

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

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

See Also:

LocalAgent.getChildren(Object)

setActiveWindow

public void setActiveWindow(java.lang.Object object)

Make the provided object the "active" object or window (bring it forward).

Specified by:

setActiveWindow in interface LocalServer

Parameters:

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

Throws:

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

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

getClassName

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

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 - An object from getTopLevelWindows or from a previous call to getChildren.

Returns:

String Class name of the object.

Throws:

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

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

See Also:

LocalAgent.getClassName(Object)

getSuperClassNames

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

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=java.lang.Object).

Specified by:

getSuperClassNames in interface LocalAgent

Parameters:

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

Returns:

String[] Class names for the superclass hierarchy.

Throws:

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

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

See Also:

LocalAgent.getSuperClassNames(Object)

getPropertyNames

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

Retrieve the list of available properties for the object.

Specified by:

getPropertyNames in interface LocalAgent

Parameters:

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

Returns:

String[] the names of available properties.

Throws:

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

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

See Also:

LocalAgent.getPropertyNames(Object)

getProperty

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

Specified by:

getProperty in interface LocalAgent

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

See Also:

LocalAgent.getProperty(Object,String)

getCaption

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

Retrieve the Caption of the object if one exits.

Specified by:

getCaption in interface LocalAgent

Parameters:

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

Returns:

String the caption of the object or an empty String.

Throws:

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

SAFSActionUnsupportedRuntimeException("Caption - Unsupported") if the object does not provide a caption.

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

See Also:

LocalAgent.getCaption(Object)

getName

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

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

Specified by:

getName in interface LocalAgent

Parameters:

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

Returns:

String the name of the object or an empty String.

Throws:

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

SAFSActionUnsupportedRuntimeException("Name - Unsupported") if the object does not provide a caption.

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

See Also:

LocalAgent.getName(Object)

getID

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

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

Specified by:

getID in interface LocalAgent

Parameters:

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

Returns:

String the ID of the object or an empty String.

Throws:

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

SAFSActionUnsupportedRuntimeException("ID - Unsupported") if the object does not provide a caption.

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

See Also:

LocalAgent.getID(Object)

getText

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

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

Specified by:

getText in interface LocalAgent

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 object does not provide a caption.

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

See Also:

LocalAgent.getText(Object)

getLevel

public int getLevel(java.lang.Object object)

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

Specified by:

getLevel in interface LocalAgent

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.

See Also:

LocalAgent.getLevel(Object)

isShowing

public boolean isShowing(java.lang.Object object)

Return true if the object is showing/visible.

Specified by:

isShowing in interface LocalAgent

Parameters:

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

Returns:

boolean true if the object is showing/visible.

Throws:

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

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

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

See Also:

LocalAgent.isShowing(Object)

isValid

public boolean isValid(java.lang.Object object)

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

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 still valid/findable.

Throws:

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

See Also:

LocalAgent.isValid(Object)

getStringData

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

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

See Also:

LocalAgent.getStringData(Object,Object)

process

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

Process the action provided in the testRecordData. Subclasses must override this do-nothing method. An Agent may throw various types of Agent-specific SAFSRuntimeExceptions depending upon failure modes. A Server should catch the RemoteException and Exception but test for subclasses of RuntimeException and possibly let them through.

Specified by:

process in interface LocalAgent

Parameters:

object - must be serializable.

testRecordData - provides all the information needed by the Agent to perform the action. This must be a serializable version of testRecordData.

Returns:

TestRecordData with necessary info, especially the modified statuscode.

Throws:

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

SAFSRuntimeException - subclasses from the various Agents.

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

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 AgentWindow from which to locate the subitem.

index - of the subitem to retrieve.

Returns:

subitem object AgentWindow 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.lang.Exception

See Also:

SubItemsAgent.getSubItemAtIndex(Object,int)

getMatchingPathObject

public java.lang.Object getMatchingPathObject(java.lang.Object object,
                                              java.lang.String path)

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:

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.

See Also:

LocalAgent.getMatchingPathObject(Object,String)

isMatchingPath

public 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. 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:

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:

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

SAFSSubItemsAgentUnsupportedRuntimeException - as necessay.

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

See Also:

LocalAgent.isMatchingPath(Object,String)

runCommand

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

Default implementation throws SAFSActionUnsupportedRuntimeException("runCommand Unsupported").

Specified by:

runCommand in interface Server

Parameters:

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

Returns:

empty String

Throws:

SAFSActionUnsupportedRuntimeException("runCommand - Unsupported");

java.rmi.RemoteException

java.lang.Exception

See Also:

Server.runCommand(Object)

finalize

protected void finalize()
                 throws java.lang.Exception

Remove this server object from the RMI registry. Tell every registered Agent to disconnect via its shutdown function and then clear the list of registered Agents.

Overrides:

finalize in class RemoteRoot

Throws:

java.lang.Exception

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Primarily a test entry point. Sets an RMI Security Manager, instance a ServerImpl object, and binds to the RMI Registry with superclass rebindLocalRMIRegistry.

Example command-line invocation:

 java -cp %CLASSPATH% -Djava.security.policy=%SAFSDIR%\lib\java.policy
                      -Djava.rmi.server.hostname="thishost.internal.net" 
                      org.safs.rmi.engine.ServerImpl
 

Parameters:

args - -- none

Throws:

java.lang.Exception