com.tplan.robot.remoteclient

Interface RemoteDesktopClient

All Superinterfaces:

Plugin

All Known Implementing Classes:

AbstractRemoteDesktopClient

public interface RemoteDesktopClient
extends Plugin

Remote desktop client is a high level interface describing common capabilities of remote desktop technologies. The point is to provide a common API to most existing remote desktop protocols such as RFB (aka VNC), RDP and others. The term "remote" is not exact here because the client can in fact be implemented to connect to the local desktop, such as for example the Java client or VNC client and server running on the same Windows instance.

Particular remote desktop capabilities are described through interfaces in the com.tplan.robot.remoteclient.capabilities package. They declare what the client can do with regard to its protocol. For example, if the client is able to transfer key strokes typed on the local keyboard to the remote desktop, it should declare this capability through implementation of the KeyTransferCapable interface.

Clients are typically implemented as plugins. They are instantiated indirectly through the RemoteDesktopClientFactory class by name of the protocol they implement. For example, an RFB client instance can be obtained through RemoteDesktopClientFactory.getInstance().getClient("rfb"). The factory can also parse a connect URI and create a suitable client, for example RemoteDesktopClientFactory.getInstance().getClientForURI("rfb://localhost:5901"). While these methods may be used in a custom program, a typical T-Plan Robot Enterprise user creating just test scripts is more likely to call the Connect command or its corresponding DefaultJavaTestScript.connect(java.lang.String, java.lang.String, java.lang.String, boolean) Java method.

An instantiated client should be first populated with login parameters such as connect URI (containing protocol, host name and optional port number), user name and password. This should be done through the setLoginParams(java.util.Map) method. The parameter set depends on the protocol (RFB may need just host name and port) and configuration of particular server (for example, an RFB server may be configured to require password). Client parameter sets can be easily customized through the getLoginParamsSpecification() method. Particular parameter values may be then specified through the Login Dialog, through the --clientparam CLI option or through the connect() method of Java Test Script API.

Once the login parameters are passed to the client, an attempt to connect to the desktop through the connect() method may be invoked. The client is expected to fire expected server events to all registered RemoteDesktopServerListener listeners. It should also fire client events to all registered RemoteDesktopClientListener instances. Correct implementation of the event system is essential for the framework to work correctly.

T-Plan Robot Enterprise, (C) 2009-2022 T-Plan Limited. All rights reserved.

Field Summary

Fields

Modifier and Type	Field and Description
static String	LOGIN_PARAM_PASSWORD Constant for password.
static String	LOGIN_PARAM_URI Constant for server URI.
static String	LOGIN_PARAM_USER Constant for user name.

Method Summary

Modifier and Type	Method and Description
void	addClientListener(RemoteDesktopClientListener listener) Add a client listener.
void	addServerListener(RemoteDesktopServerListener listener) Add an RFB server listener to the client.
Thread	close() Close the connection to the RFB server.If there's no connection, the method should do nothing.
Thread	connect() Connect the client to the specified host.
void	destroy() Destroy the client.
String	getConnectString() Get the connect string (URL).
int	getDefaultPort() Get the default server port.
int	getDesktopHeight() Get the remote desktop height.
String	getDesktopName() Get the remote desktop name.
int	getDesktopWidth() Get the remote desktop width.
String	getHost() Get the server host name.
Image	getImage() Get the remote desktop image.
MouseEvent	getLastMouseEvent() This is a convenience method allowing to track the mouse pointer coordinates.
List<Preference>	getLoginParamsSpecification() Get the list of login parameters (parameters).
String	getPassword() Get the password.
int	getPort() Get the port of the target RFB server.
String	getProtocol() Get the protocol and eventually version supported by the client.
String	getUser() Get the user.
boolean	hasSufficientConnectInfo() Indicate whether the client has sufficient connect information or not.
boolean	isConnected() Should indicate whether the client is connected to an RFB server, i.e.
boolean	isConnectedTo(String connectString) Test whether this client is connected to a desktop identified by a particular URL (connect string).
boolean	isConnecting() Should indicate whether the client is currently connecting to an RFB server but the communication hasn't passed the authentication and init phases, i.e.it is in the process of initial handshake, authentication or exchange of session parameters.
boolean	isConsoleMode() Indicates if the client runs in the console or GUI mode.
boolean	isLocalDisplay() Find out whether the client is connected to the local display.
boolean	isLocalDisplay(Rectangle r) Test out if the argument rectangle intersects the automated screen.
void	removeClientListener(RemoteDesktopClientListener listener) Remove an object from the list of client listeners.
void	removeServerListener(RemoteDesktopServerListener listener) Remove an object from the list of server listeners.
void	sendClientCutText(String text) Implementation of the ClientCutText client-to-server RFB v3.3 message.The method is supposed to send the update of the local clipboard to the server.
void	setConsoleMode(boolean consoleMode) Set the console mode flag.
void	setLoginParams(Map<String,Object> params) Set the client login parameter values.

Methods inherited from interface com.tplan.robot.plugin.Plugin

checkDependencies, getCode, getDate, getDescription, getDisplayName, getImplementedInterface, getLowestSupportedVersion, getMessageAfterInstall, getMessageBeforeInstall, getSupportContact, getUniqueId, getVendorHomePage, getVendorName, getVersion, requiresRestart

Field Detail

LOGIN_PARAM_URI

static final String LOGIN_PARAM_URI

Constant for server URI. Used as key of the port value in the map of CLI arguments.

See Also:

Constant Field Values

LOGIN_PARAM_PASSWORD

static final String LOGIN_PARAM_PASSWORD

Constant for password. Used as key of the password value in the map of CLI arguments.

See Also:

Constant Field Values

LOGIN_PARAM_USER

static final String LOGIN_PARAM_USER

Constant for user name. Used as key of the user name value in the map of CLI arguments.

See Also:

Constant Field Values

Method Detail

isLocalDisplay

boolean isLocalDisplay()

Find out whether the client is connected to the local display. By "local display" we mean the very same desktop displayed on the local display device (such as users's computer screen). An example of a local display is VNC server running on Windows or Java client connected directly to the system desktop buffer. On contrary, VNC servers running on ports 5901 and higher on a local Linux/Unix machine (localhost:1, localhost:2,...) must not be considered local by this method.

Value returned by this method affects behavior of the T-Plan Robot Enterprise GUI. If the display is local, the viewer doesn't display the desktop image because it would lead to recursive image (infinite mirroring effect). When a test script is executed on the local display, the GUI minimizes in order to hide from eventual screenshots.

Returns:

true if the client is connected to a local display, false if not.

isLocalDisplay

boolean isLocalDisplay(Rectangle r)

Test out if the argument rectangle intersects the automated screen. Introduced to address automation of a single local screen in a multi screen environment.

Parameters:

r - a rectangle.

Returns:

true if the rectangle intersects the automated screen or not. All remote clients should return false.

getProtocol

String getProtocol()

Get the protocol and eventually version supported by the client.

Returns:

Protocol version in the format defined by the protocol.

getHost

String getHost()

Get the server host name. If the name hasn't been set through setHost(), the method returns null.

Returns:

Server host name (can be both name or IP address).

getPort

int getPort()

Get the port of the target RFB server. Note that it is the real port, not the display number. If you are connecting e.g. to a server called myserver.mydomain.com:2, the port is 5902.

Returns:

RFB server port number.

getDefaultPort

int getDefaultPort()

Get the default server port. For RFB (VNC) it is 5900 while RDP uses 3389.

Returns:

default port number.

getPassword

String getPassword()

Get the password. If the password hasn't been set through setPassword(), the method returns null.

Returns:

Password for authentication to the RFB server.

getUser

String getUser()

Get the user. If the user name hasn't been set through setLoginParams(java.util.Map), the method returns null.

Returns:

user name for authentication to the RFB server.

getDesktopWidth

int getDesktopWidth()

Get the remote desktop width. If the client is not connected to a server, the method should return zero.

Returns:

Remote desktop width or zero if not connected.

getDesktopHeight

int getDesktopHeight()

Get the remote desktop height. If the client is not connected to any RFB server, the method should return zero.

Returns:

Remote desktop width or zero if not connected.

getDesktopName

String getDesktopName()

Get the remote desktop name. If the client is not connected to any RFB server, the method should return null or an empty string.

Returns:

Remote desktop width or null or empty string if not connected.

isConsoleMode

boolean isConsoleMode()

Indicates if the client runs in the console or GUI mode. In the console mode all log messages should be printed out to the standard output.

In GUI mode the client should rather fire the messages to all registered RfbServerListener instances. The GUI components should then report the messages in an appropriate way.

Returns:

true if the client runs in CLI mode, false if in GUI mode.

setConsoleMode

void setConsoleMode(boolean consoleMode)

Set the console mode flag.

Parameters:

consoleMode - false indicates that the application runs in GUI mode, true indicates CLI one.

getLastMouseEvent

MouseEvent getLastMouseEvent()

This is a convenience method allowing to track the mouse pointer coordinates. The client is expected to cache the last mouse event sent by the sendMouseEvent() and return it through this method.

Returns:

The last mouse event sent to the server.

getImage

Image getImage()

Get the remote desktop image. The client should maintain an off screen image (e.g. a BufferedImage instance) and synchronize it with the updates received in the FrameBufferUpdate server messages.

Returns:

Remote desktop image.

isConnected

boolean isConnected()

Should indicate whether the client is connected to an RFB server, i.e. if there's an active connection which has already passed the authentication and init phase (after ServerInit message is received from the server).

Returns:

true if there's an active connection, false if not.

isConnecting

boolean isConnecting()

Should indicate whether the client is currently connecting to an RFB server but the communication hasn't passed the authentication and init phases, i.e.it is in the process of initial handshake, authentication or exchange of session parameters.

Returns:

true if in the connecting phase or false otherwise.

connect

Thread connect()
        throws Exception,
               com.tplan.robot.remoteclient.rfb.PasswordRequiredException

Connect the client to the specified host.

Returns:

the connection thread.

Throws:

Exception - on any other error.

com.tplan.robot.remoteclient.rfb.PasswordRequiredException - if the connection requires a password and it is not provided.

hasSufficientConnectInfo

boolean hasSufficientConnectInfo()

Indicate whether the client has sufficient connect information or not. If false is returned, the tool will display the Login dialog (in GUI mode) or reports an error (in CLI mode).

Returns:

true if the client has sufficient data to establish a connection to the desktop, false if not.

close

Thread close()
      throws IOException

Close the connection to the RFB server.If there's no connection, the method should do nothing.

Returns:

the connection thread.

Throws:

IOException - on an I/O error.

sendClientCutText

void sendClientCutText(String text)
                throws IOException

Implementation of the ClientCutText client-to-server RFB v3.3 message.The method is supposed to send the update of the local clipboard to the server.

Parameters:

text - content of the local clipboard.

Throws:

IOException - on an I/O error.

addServerListener

void addServerListener(RemoteDesktopServerListener listener)

Add an RFB server listener to the client. Each registered listener will receive an event whenever a RFB server messages is received, such as FrameBufferUpdate, Bell or ServerCutText.

Parameters:

listener - an object implementing the RfbServerListener interface.

removeServerListener

void removeServerListener(RemoteDesktopServerListener listener)

Remove an object from the list of server listeners. If the argument object is not registered in the list, the method should do nothing.

Parameters:

listener - an object implementing the RfbServerListener interface.

addClientListener

void addClientListener(RemoteDesktopClientListener listener)

Add a client listener. Each registered listener will receive an event whenever the client sends one of the selected messages to the server, such as PointerEvent, KeyEvent etc.

Parameters:

listener - an object implementing the RemoteDesktopClientListener interface.

removeClientListener

void removeClientListener(RemoteDesktopClientListener listener)

Remove an object from the list of client listeners. If the argument object is not registered in the list, the method should do nothing.

Parameters:

listener - an object implementing the RemoteDesktopClientListener interface.

getLoginParamsSpecification

List<Preference> getLoginParamsSpecification()

Get the list of login parameters (parameters). This is a generic mechanism allowing the client to declare a custom list of input arguments required to connect to the server, such as server name, user name, password, certificate file name etc. This data is used by the Login dialog to display corresponding GUI controls.

Returns:

list of required login arguments.

setLoginParams

void setLoginParams(Map<String,Object> params)

Set the client login parameter values. This is the entry point to specify connection URI (parameter name LOGIN_PARAM_URI), user name (LOGIN_PARAM_USER) and password (LOGIN_PARAM_PASSWORD). The client is expected to parse the URI for the host name and port number to be returned by the getHost() and getPort() methods. The point is to let the client to provide default values when the URI doesn't contain them.

Save for these standard parameters listed above the table can be populated with any other protocol specific parameters understood by the client. Any such parameter should be declared through the getLoginParamsSpecification() method to make the Login Dialog to display an appropriate GUI component and allow user to enter a parameter value.

Custom parameters can be also passed through the --clientparam CLI option. Any such instance will be parsed and passed to the client through this method.

Parameters:

params - map of the [parameter name, parameter value] pairs.

destroy

void destroy()

Destroy the client. The method will be called after the script using the client terminates. The method is supposed to perform a complete clean up to release references to internal objects to get ready for garbage collection.

getConnectString

String getConnectString()

Get the connect string (URL). It typically contains protocol, host name and optional port. The connect string must uniquely identify the connected desktop (or desktop this client is initialized to connect to).

Returns:

connect string (URI), for example "rfb://fox.mydomain.com:5901".

isConnectedTo

boolean isConnectedTo(String connectString)

Test whether this client is connected to a desktop identified by a particular URL (connect string). The method should for example check whether the referred host and port is the same (if applicable). For example, if the client is a VNC one and is connected to "localhost:1", the method should return true when the argument is "rfb://127.0.0.1:5901" because the URL refers to the same host and port.

Parameters:

connectString - an URL (connect string).

Returns:

true if the client is connected to the connect string