com.tplan.robot.remoteclient

Class RemoteDesktopClientFactory

java.lang.Object

com.tplan.robot.plugin.PluginFactory

com.tplan.robot.remoteclient.RemoteDesktopClientFactory

public class RemoteDesktopClientFactory
extends PluginFactory

Desktop client factory is central point of instantiation of desktop clients and makes it possible to deliver clients as standalone plugins. All other classes are strongly recommended to create desktop clients through this factory rather than instantiate them directly through their constructors.

The factory supports connection pooling (so called "client reuse mode") since v2.2. It allows individual automated testing processes (executed test scripts) running in the CLI mode to release connected desktop clients to the pool after use rather than destroying them. Such clients may be then picked up by other automated testing threads. This approach avoids the overhead of client creation and desktop connection and it may significantly improve performance (while increasing the memory requirements) of multi threaded automated testing applications, especially where multiple shorter test scripts are executed against just a few test environments.

To switch on the client pooling simply call setReuseClients(true). This will make the factory to pool the clients and pass them to automated tasks instead of creating new clients every time. This process works transparently for the standard "connect" functionality such as client connection through CLI parameters and the Connect commands and its counterpart method DefaultJavaTestScript.connect(). Be sure not to call DefaultJavaTestScript.disconnect() on clients which you intend to reuse because it destroys the connection and makes the client not eligible for pooling.

Third party Java programs working with client instances and custom connections are recommended to check for availability of reused clients through the getReusedClient(java.lang.String) method before proceeding to creation of a new one. When the client is not needed any more, the program should release it through the releaseClient(com.tplan.robot.remoteclient.RemoteDesktopClient) method instead of closing its connection through RemoteDesktopClient.close(). If the client pooling is switched off, the release method will call the client's close() and destroy() methods anyway.

Note that the connection pool was designed to maintain the pool at the maximum size of licensed seats minus one. For example on an environment with 2 licensed connections the pool will not save more than 1 connection. When the limit size is reached, the pool selects one of the pooled connections (usually the oldest one) and kills it.

When the client pooling is on, make sure to finish your program either through System.exit(int) or at least switch the pooling off in the end of the code. Otherwise the pooled client instances may keep your program alive even after all your test scripts finish because many clients run their connection in an independent thread.

The following example shows sequential execution of three test scripts against a single test environment. If the pooling were off, each task would create its own client instance and go through the desktop connection sequence. As the pooling is on, only the first task will create and connect the client and the two other tasks will transparently reuse it.

 import com.tplan.robot.ApplicationSupport;
 import com.tplan.robot.AutomatedRunnable;
 import com.tplan.robot.remoteclient.RemoteDesktopClientFactory;

 public class ClientPoolingExample {

     // Target desktop (test environment)
     static String HOST = "rfb://localhost:5901";

     // Desktop password
     static String PASSWD = "welcome";

     // File names of our three test scripts
     static String scripts[] = {"script1.tpr", "script2.tpr", "script3.tpr"};

     public static void main(String args[]) {
         ApplicationSupport robot = new ApplicationSupport();

         // Set on the client pooling mode
         RemoteDesktopClientFactory.setReuseClients(true);

         AutomatedRunnable runnable;
         for (int i = 0; i < scripts.length; i++) {
             runnable = robot.createAutomatedRunnable(
                     "cli-"+i,
                     new String[] {"-c", HOST, "-p", PASSWD, "-r", scripts[i], "-n"},
                     System.out,
                     false);
             // Here we call just run() because we want the scripts run sequentially
             runnable.run();
         }

         // This is needed to stop the pooled client from keeping the program alive
         System.exit(0);
     }
 }
 

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

Field Summary

Fields

Modifier and Type	Field and Description
static String	CFG_KEY_POOL_CONNECTIONS Configuration key of the pooling mode ("scripting.poolConnections").
static String	PROTOCOL_FILE Constant for static image client ("FILE").
static String	PROTOCOL_JAVA Constant for native Java client ("JAVA").
static String	PROTOCOL_RDP Constant for Remote Desktop Protocol ("RDP").
static String	PROTOCOL_RFB Constant for Remote Frame Buffer protocol ("RFB").

Method Summary

Modifier and Type	Method and Description
void	addRemoteDesktopClientListener(RemoteDesktopClientListener listener) Add a remote desktop client listener to all clients which will be created by this factory.
void	addRemoteDesktopServerListener(RemoteDesktopServerListener listener) Add a remote desktop server listener to all clients which will be created by this factory.
RemoteDesktopClient	getClient(String protocol) Get a desktop client for a particular protocol.
RemoteDesktopClient	getClientForURI(String uri) Get a desktop client for a particular connection URI.
List<RemoteDesktopClient>	getConnectedClients() Get all connected clients existing in this Java instance.
String	getConnectionSummary(boolean useHtmlLineBreaks) Get a summary of all existing connections.
static RemoteDesktopClientFactory	getInstance() Get shared instance of this desktop client factory.
RemoteDesktopClient	getOldestPooledClient() Remove the oldest client from the pool.
List<RemoteDesktopClient>	getPooledClients() Get the list of currently pooled (unused) clients.
int	getPoolSize() Get number of pooled clients.
RemoteDesktopClient	getReusedClient(String connectString) Look if there's a reusable client for the given connect string (URL) in the client pool.
List<String>	getSupportedProtocols() Get list of supported protocol identifiers (in upper case).
static boolean	isReuseClients() Find out whether the client reuse mode (connection pooling) is on or off.
boolean	releaseClient(RemoteDesktopClient client) Release a client.
boolean	releaseClient(RemoteDesktopClient client, boolean forceClose) Release a client.
void	removeRemoteDesktopClientListener(RemoteDesktopClientListener listener) Remove remote desktop client listener from the list of listeners.
void	removeRemoteDesktopServerListener(RemoteDesktopServerListener listener) Remove remote desktop server listener from the list of listeners.
static void	setReuseClients(boolean reuseClientsMode) Set on/off reusing (pooling) of clients.

Methods inherited from class java.lang.Object

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

Field Detail

PROTOCOL_RFB

public static final String PROTOCOL_RFB

Constant for Remote Frame Buffer protocol ("RFB").

See Also:

Constant Field Values

PROTOCOL_RDP

public static final String PROTOCOL_RDP

Constant for Remote Desktop Protocol ("RDP").

See Also:

Constant Field Values

PROTOCOL_JAVA

public static final String PROTOCOL_JAVA

Constant for native Java client ("JAVA").

See Also:

Constant Field Values

PROTOCOL_FILE

public static final String PROTOCOL_FILE

Constant for static image client ("FILE").

See Also:

Constant Field Values

CFG_KEY_POOL_CONNECTIONS

public static final String CFG_KEY_POOL_CONNECTIONS

Configuration key of the pooling mode ("scripting.poolConnections").

See Also:

Constant Field Values

Method Detail

isReuseClients

public static boolean isReuseClients()

Find out whether the client reuse mode (connection pooling) is on or off. The method returns:

• If the setReuseClients(boolean) method has been called within the current JVM the method returns the mode set by the method call.
• Otherwise the method returns the mode specified in the in the Desktop Viewer panel of the Preferences window (the factory setting is false).

Returns:

true if the reuse mode is on or false otherwise.

setReuseClients

public static void setReuseClients(boolean reuseClientsMode)

Set on/off reusing (pooling) of clients. Setting of the pooling mode through this method overrides the default mode stored in the user configuration but it is not stored persistently (it remains valid until the JVM terminates). The default pooling preference can be found in the Desktop Viewer panel of the Preferences window. For details on the pooling mode see the description of this class.

When the method argument is true and the mode is off, the factory starts to accept clients submitted through the releaseClient(com.tplan.robot.remoteclient.RemoteDesktopClient) to the pool.

When the argument is false and the mode is on, the factory clears the pool and disconnects/destroys all pooled clients. This is expected to release all memory used by the clients.

Parameters:

reuseClientsMode - true sets the client reuse mode on, false off.

releaseClient

public boolean releaseClient(RemoteDesktopClient client)
                      throws IOException

Release a client. If the client is connected and the client reuse mode is on, it is pooled for reuse. Otherwise the method calls the client's close() and destroy() methods to make sure the client gets terminated properly and reclaimed by the garbage collector.

Parameters:

client - a client.

Returns:

true if the client was pooled, false if it was closed and destroyed.

Throws:

IOException - the method re-throws any I/O exceptions thrown by the client's close() and destroy() methods.

releaseClient

public boolean releaseClient(RemoteDesktopClient client,
                             boolean forceClose)
                      throws IOException

Release a client. If the client is connected, the client reuse mode is on and the forceClose is false, the client (connection) it is pooled for reuse. Otherwise the method calls the client's close() and destroy() methods to make sure the client gets terminated properly and reclaimed by the garbage collector.

Parameters:

client - a client.

forceClose - if the flag is set to true, the client will not be pooled even if pooling is on and it will be disconnected and destroyed.

Returns:

true if the client was pooled, false if it was closed and destroyed.

Throws:

IOException - the method rethrows any I/O exceptions thrown by the client's close() and destroy() methods.

getReusedClient

public RemoteDesktopClient getReusedClient(String connectString)

Look if there's a reusable client for the given connect string (URL) in the client pool.

Parameters:

connectString - connect string as is returned by the RemoteDesktopClient.getConnectString() method (for example "rfb://localhost:5901" or "file://C:/Images/desktop.png").

Returns:

a client from the pool which is free and already connected to the specified host or null if there's no such client.

getConnectedClients

public List<RemoteDesktopClient> getConnectedClients()

Get all connected clients existing in this Java instance. The list will include all clients which are either pooled or being used by a test script.

Returns:

a list of all connected clients.

Since:

2.3.1

getConnectionSummary

public String getConnectionSummary(boolean useHtmlLineBreaks)

Get a summary of all existing connections.

Parameters:

useHtmlLineBreaks - true will produce output ready to be embedded into an HTML document with '<br/>' tags instead of plain text line breaks.

Returns:

summary of existing connections.

Since:

2.3.1

getPooledClients

public List<RemoteDesktopClient> getPooledClients()

Get the list of currently pooled (unused) clients.

Returns:

list of pooled clients.

getPoolSize

public int getPoolSize()

Get number of pooled clients.

Returns:

pool size.

getOldestPooledClient

public RemoteDesktopClient getOldestPooledClient()

Remove the oldest client from the pool. The method returns the client which is in the pool for the longest time or null if the pool is empty.

Returns:

oldest client removed from the pool.

getClient

public RemoteDesktopClient getClient(String protocol)

Get a desktop client for a particular protocol.

Parameters:

protocol - protocol identifier. Supported values are: "RFB". There might be more clients delivered as plugins.

Returns:

a new instance of client able to handle communication in the selected protocol.

getClientForURI

public RemoteDesktopClient getClientForURI(String uri)

Get a desktop client for a particular connection URI. The method parses the protocol from the URI, creates a clien for that protocol and initializes it with any other URI components like host and port.

Parameters:

uri - connection URI in form of <protocol>://<host>:<port>

Returns:

a new instance of client able to handle communication in the selected protocol.

getSupportedProtocols

public List<String> getSupportedProtocols()

Get list of supported protocol identifiers (in upper case).

Returns:

list of supported protocols.

getInstance

public static RemoteDesktopClientFactory getInstance()

Get shared instance of this desktop client factory.

Returns:

shared factory instance.

addRemoteDesktopServerListener

public void addRemoteDesktopServerListener(RemoteDesktopServerListener listener)

Add a remote desktop server listener to all clients which will be created by this factory.

Parameters:

listener - a remote desktop server listener.

removeRemoteDesktopServerListener

public void removeRemoteDesktopServerListener(RemoteDesktopServerListener listener)

Remove remote desktop server listener from the list of listeners. The method will cause the factory to stop adding this listener to the newly created clients. It will not remove the listener from clients created in the past.

Parameters:

listener - a remote desktop server listener.

addRemoteDesktopClientListener

public void addRemoteDesktopClientListener(RemoteDesktopClientListener listener)

Add a remote desktop client listener to all clients which will be created by this factory.

Parameters:

listener - a remote desktop client listener.

removeRemoteDesktopClientListener

public void removeRemoteDesktopClientListener(RemoteDesktopClientListener listener)

Remove remote desktop client listener from the list of listeners. The method will cause the factory to stop adding this listener to the newly created clients. It will not remove the listener from clients created in the past.

Parameters:

listener - a remote desktop client listener.