com.jayway.android.robotium.remotecontrol.solo

Class SoloRemoteControl

java.lang.Object

com.jayway.android.robotium.remotecontrol.solo.SoloRemoteControl

All Implemented Interfaces:

ConnectionListener, DebugListener, NamedListener, SocketProtocolListener

Direct Known Subclasses:

SAFSRemoteControl

public class SoloRemoteControl
extends java.lang.Object
implements SocketProtocolListener, DebugListener

Author:

Carl Nagle, SAS Institute, Inc OCT 11, 2012 (Lei Wang) Remove field startEmulatorPortForwarding, because we can use portForwarding instead. FEB 06, 2013 (Carl Nagle) Fixed performRemoteShutdown to properly use secsWaitShutdown.

Field Summary

Fields

Modifier and Type	Field and Description
int	controllerPort
boolean	enableProtocolDebug
boolean	enableRunnerDebug
static java.lang.String	listenername
protected java.util.Vector	listeners
(package private) boolean	localShutdown
(package private) java.lang.Object	lock
protected LogsInterface	log
boolean	portForwarding
(package private) boolean	remoteConnected
(package private) boolean	remoteException
(package private) boolean	remoteMessage
(package private) java.lang.String	remoteMessageString
(package private) boolean	remoteReady
(package private) boolean	remoteResult
(package private) int	remoteResultCode
(package private) java.lang.String	remoteResultInfo
(package private) java.util.Properties	remoteResultProperties
(package private) boolean	remoteRunning
(package private) boolean	remoteShutdown
static java.lang.String	ROOT_DROID_SDK_DIR Default: C:\Program Files\Android\android-sdk\ Set to the root directory where the Droid Development SDK is located.
static java.lang.String	ROOT_DROID_SDK_TOOLS Default: C:\Program Files\Android\android-sdk\tools Set to the directory where the Droid Development SDK Tools are located.
protected SoloRemoteControlRunner	runner
protected java.lang.Thread	runnerThread
static AndroidTools	sdk
(package private) int	shutdownCause

Fields inherited from interface org.safs.sockets.SocketProtocolListener

DEFAULT_NAME

Constructor Summary

Constructors

Constructor and Description
SoloRemoteControl() No-arg constructor to instantiate and use all defaults.

Method Summary

Modifier and Type	Method and Description
void	addListener(NamedListener listen) Add a listener to this Runner.
protected void	checkExceptions() Throw a ShutdownInvocationException only *IF* we have received a localShutdown or remoteShutdown message.
protected java.util.Properties	consolidateResults() Consolidates the remoteResult, remoteResultCode, and remoteResultInfo into any remoteResultProperties.
protected boolean	createProtocolRunner() Invoked from start().
void	debug(java.lang.String message)
java.lang.String	getListenerName() Unique name to identify the listener.
void	initAndroidTools() Set our static sdk tool to the one appropriate for the OS (Windows or Unix).
protected void	modifyEmbeddedProtocol() In this method, we can modify some properties of the embedded protocol DroidSocketProtocol. Note: this method MUST be called after createProtocolRunner() and before startProtocolRunner().
protected void	notifyConnectionListeners()
protected void	notifyExceptionListeners(java.lang.String message)
protected void	notifyLocalShutdownListeners(int cause)
protected void	notifyMessageListeners(java.lang.String message)
protected void	notifyReadyListeners()
protected void	notifyRemoteShutdownListeners(int cause)
protected void	notifyResultPropsListeners(java.util.Properties props)
protected void	notifyResultsListeners(int rc, java.lang.String info)
protected void	notifyRunningListeners()
void	onReceiveConnection() Called when a 2-way sockets connection has been established.
void	onReceiveDebug(java.lang.String message) A remote client has sent a Debug message to be logged by the listener.
void	onReceiveException(java.lang.String message) Remote client has thrown/issued an Exception message.
void	onReceiveLocalShutdown(int shutdownCause) A local source has issued a SHUTDOWN event/command.
void	onReceiveMessage(java.lang.String message) Remote client has sent an arbitrary message.
void	onReceiveReady() Remote client has issued the READY event
void	onReceiveRemoteShutdown(int shutdownCause) A remote source has issued a SHUTDOWN event/command.
void	onReceiveResult(int rc, java.lang.String info) Implemented here, but not currently used by this implementation.
void	onReceiveResultProperties(java.util.Properties result) Remote client has issued the RESULT event and is returning result information in Properties.
void	onReceiveRunning() Remote client has issued the RUNNING event--usually resulting from a DISPATCH event.
java.util.Properties	performRemoteFileCommand(java.lang.String filepath, int secsWaitReady, int secsWaitRunning, int secsWaitResult) Default implementation performs the following:
void	performRemoteMessageCommand(java.lang.String message, int secsWaitReady, int secsWaitRunning) Default implementation performs the following:
java.util.Properties	performRemotePropsCommand(java.util.Properties props, int secsWaitReady, int secsWaitRunning, int secsWaitResult) Default implementation performs the following:
void	performRemoteShutdown(int secsWaitReady, int secsWaitRunning, int secsWaitShutdown) Default implementation performs the following:
void	removeListener(NamedListener listen) Remove a previously added listener from this Runner.
protected void	resetReady() Used internally.
void	resetResults() reset the results fields and properties prior to dispatching a request.
void	resetRunningState()
void	setControllerPort(int controllerPort) Set the 'controller port' where we will connect for messenger service. The 'controller port' should be an available port, if it is not, it will be modified to an available one in method modifyEmbeddedProtocol()
void	setLogsInterface(LogsInterface ilog) Set the LogsInterface to be used by the class instance.
void	setPortForwarding(boolean portForwarding) Set if we will forward 'controller port' to remote messenger service's port.
void	shutdown() Command the RemoteControl infrastructure to shutdown.
void	start() Creates and Starts the asynchronous RemoteControl runner.
protected boolean	startProtocolRunner() Invoked from start().
void	waitForRemoteConnected(int sTimeout) Wait for the remote client to get connected.
void	waitForRemoteReady(int sTimeout) Wait for the remote client to signal Ready for a new command.
java.util.Properties	waitForRemoteResult(int sTimeout) Wait for the remote client to signal results are available and return those results.
void	waitForRemoteRunning(int sTimeout) Wait for the remote client to signal Running a new command.
void	waitForRemoteShutdown(int sTimeout) Wait for the remote client to signal its shutdown.

Methods inherited from class java.lang.Object

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

Field Detail

listenername

public static final java.lang.String listenername

See Also:

Constant Field Values

ROOT_DROID_SDK_DIR

public static java.lang.String ROOT_DROID_SDK_DIR

Default: C:\Program Files\Android\android-sdk\
Set to the root directory where the Droid Development SDK is located.

ROOT_DROID_SDK_TOOLS

public static java.lang.String ROOT_DROID_SDK_TOOLS

Default: C:\Program Files\Android\android-sdk\tools
Set to the directory where the Droid Development SDK Tools are located.

listeners

protected java.util.Vector listeners

log

protected LogsInterface log

runner

protected SoloRemoteControlRunner runner

runnerThread

protected java.lang.Thread runnerThread

controllerPort

public int controllerPort

portForwarding

public boolean portForwarding

sdk

public static AndroidTools sdk

enableProtocolDebug

public boolean enableProtocolDebug

enableRunnerDebug

public boolean enableRunnerDebug

remoteException

boolean remoteException

remoteMessage

boolean remoteMessage

remoteMessageString

java.lang.String remoteMessageString

remoteReady

boolean remoteReady

remoteConnected

boolean remoteConnected

remoteRunning

boolean remoteRunning

remoteResult

boolean remoteResult

remoteResultCode

int remoteResultCode

remoteResultInfo

java.lang.String remoteResultInfo

remoteResultProperties

java.util.Properties remoteResultProperties

localShutdown

boolean localShutdown

remoteShutdown

boolean remoteShutdown

shutdownCause

int shutdownCause

lock

java.lang.Object lock

Constructor Detail

SoloRemoteControl

public SoloRemoteControl()

No-arg constructor to instantiate and use all defaults. The default implementation does NOT have a LogsInterface object set until a successful call to setLogsInterface is made.

See Also:

setLogsInterface(LogsInterface)

Method Detail

initAndroidTools

public void initAndroidTools()

Set our static sdk tool to the one appropriate for the OS (Windows or Unix). The routine does nothing if the appropriate sdk instance is already set.

See Also:

DUtilities#getAndroidTools()

setLogsInterface

public void setLogsInterface(LogsInterface ilog)

Set the LogsInterface to be used by the class instance.

Parameters:

ilog -

addListener

public void addListener(NamedListener listen)

Add a listener to this Runner. Could be a DebugListener, ConnectionListener, or a SoloRemoteControlListener--any subclass of NamedListener.

Parameters:

listen -

See Also:

NamedListener, ConnectionListener, SoloRemoteControlListener

removeListener

public void removeListener(NamedListener listen)

Remove a previously added listener from this Runner.

Parameters:

listen -

createProtocolRunner

protected boolean createProtocolRunner()

Invoked from start(). Creates the default instance of our Runner.

Returns:

true to allow normal execution to proceed. Returning false should cause an abort of the test startup procedure.

See Also:

start()

startProtocolRunner

protected boolean startProtocolRunner()

Invoked from start(). Creates the default instance of the runnerThread providing the current Runner as its Runnable argument. The runnerThread is then immediately started.

Returns:

true to allow normal execution to proceed. Returning false should cause an abort of the test startup procedure.

See Also:

start()

start

public void start()
           throws java.lang.IllegalThreadStateException

Creates and Starts the asynchronous RemoteControl runner.

Throws:

java.lang.IllegalThreadStateException - if we were unable to create and run the protocol runner.

modifyEmbeddedProtocol

protected void modifyEmbeddedProtocol()

In this method, we can modify some properties of the embedded protocol DroidSocketProtocol.
Note: this method MUST be called after createProtocolRunner() and before startProtocolRunner(). Just like in start().
For example, we can modify the controllerPort as SocketProtocol.setControllerPort(int)
or modify portForwarding as DroidSocketProtocol.setPortForwarding(boolean)
If the 'port forwarding' is set to true, we MUST call DroidSocketProtocol.adjustControllerPort() to choose an available port for 'controller'.

See Also:

start(), SocketProtocol.setControllerPort(int), DroidSocketProtocol.setPortForwarding(boolean), DroidSocketProtocol.adjustControllerPort()

setControllerPort

public void setControllerPort(int controllerPort)

Set the 'controller port' where we will connect for messenger service.
The 'controller port' should be an available port, if it is not, it will be
modified to an available one in method modifyEmbeddedProtocol()

Parameters:

controllerPort - int, an available port number

See Also:

modifyEmbeddedProtocol()

setPortForwarding

public void setPortForwarding(boolean portForwarding)

Set if we will forward 'controller port' to remote messenger service's port. Must be set before start() is called to have affect.

Parameters:

portForwarding - set true if the controller should attempt port forwarding before starting the runner thread.

shutdown

public void shutdown()

Command the RemoteControl infrastructure to shutdown.

See Also:

AbstractProtocolRunner.shutdownThread()

resetResults

public void resetResults()

reset the results fields and properties prior to dispatching a request. remoteResult = false
remoteResultCode = -99
remoteResultInfo = null
remoteResultProperties = null
remoteComment = null
remoteDetail = null

resetReady

protected void resetReady()

Used internally. Reset the ready field--normally immediately after having received it. remoteReady = false

consolidateResults

protected java.util.Properties consolidateResults()

Consolidates the remoteResult, remoteResultCode, and remoteResultInfo into any remoteResultProperties. If remoteResultProperties is null, the routine will create the Properties object before the consolidation. remoteResultInfo will only be written to the Properties if it is a non-null String value. The routine will NOT overwrite any of these remoteResult properties if they already exist in the remoteResultProperties object.

Returns:

remoteResultProperties

resetRunningState

public void resetRunningState()

onReceiveConnection

public void onReceiveConnection()

Description copied from interface: ConnectionListener

Called when a 2-way sockets connection has been established.

Specified by:

onReceiveConnection in interface ConnectionListener

onReceiveReady

public void onReceiveReady()

Description copied from interface: SocketProtocolListener

Remote client has issued the READY event

Specified by:

onReceiveReady in interface SocketProtocolListener

onReceiveRunning

public void onReceiveRunning()

Description copied from interface: SocketProtocolListener

Remote client has issued the RUNNING event--usually resulting from a DISPATCH event.

Specified by:

onReceiveRunning in interface SocketProtocolListener

onReceiveResult

public void onReceiveResult(int rc,
                            java.lang.String info)

Implemented here, but not currently used by this implementation. This implementation is using ResultProperties.

Specified by:

onReceiveResult in interface SocketProtocolListener

Parameters:

rc - -- int statuscode

info - -- String statusinfo. Can be null. Can be an empty string.

See Also:

onReceiveResultProperties(Properties)

onReceiveResultProperties

public void onReceiveResultProperties(java.util.Properties result)

Description copied from interface: SocketProtocolListener

Remote client has issued the RESULT event and is returning result information in Properties.

Specified by:

onReceiveResultProperties in interface SocketProtocolListener

onReceiveException

public void onReceiveException(java.lang.String message)

Description copied from interface: SocketProtocolListener

Remote client has thrown/issued an Exception message.

Specified by:

onReceiveException in interface SocketProtocolListener

onReceiveMessage

public void onReceiveMessage(java.lang.String message)

Description copied from interface: SocketProtocolListener

Remote client has sent an arbitrary message. This is for custom communication between an engine and a remote client.

Specified by:

onReceiveMessage in interface SocketProtocolListener

onReceiveLocalShutdown

public void onReceiveLocalShutdown(int shutdownCause)

Description copied from interface: ConnectionListener

A local source has issued a SHUTDOWN event/command.

Specified by:

onReceiveLocalShutdown in interface ConnectionListener

Parameters:

shutdownCause - is used to indicate whether the shutdown is due to normal or abnormal circumstances.

See Also:

SocketProtocol.STATUS_SHUTDOWN_NORMAL, SocketProtocol.STATUS_SHUTDOWN_REMOTE_CLIENT

onReceiveRemoteShutdown

public void onReceiveRemoteShutdown(int shutdownCause)

Description copied from interface: ConnectionListener

A remote source has issued a SHUTDOWN event/command.

Specified by:

onReceiveRemoteShutdown in interface ConnectionListener

Parameters:

shutdownCause - is used to indicate whether the shutdown is due to normal or abnormal circumstances.

See Also:

SocketProtocol.STATUS_SHUTDOWN_NORMAL, SocketProtocol.STATUS_SHUTDOWN_REMOTE_CLIENT

getListenerName

public java.lang.String getListenerName()

Description copied from interface: NamedListener

Unique name to identify the listener.

Specified by:

getListenerName in interface NamedListener

Returns:

name of listener. Might be null.

onReceiveDebug

public void onReceiveDebug(java.lang.String message)

Description copied from interface: DebugListener

A remote client has sent a Debug message to be logged by the listener.

Specified by:

onReceiveDebug in interface DebugListener

debug

public void debug(java.lang.String message)

checkExceptions

protected void checkExceptions()
                        throws RemoteException,
                               ShutdownInvocationException

Throw a ShutdownInvocationException only *IF* we have received a localShutdown or remoteShutdown message. Throw a RemoteException only *IF* we have received a remoteException. Otherwise, this routine returns doing nothing.

Throws:

ShutdownInvocationException - if localShutdown or remoteShutdown have been received.

RemoteException - if remoteException has been received.

waitForRemoteConnected

public void waitForRemoteConnected(int sTimeout)
                            throws java.util.concurrent.TimeoutException,
                                   RemoteException,
                                   ShutdownInvocationException

Wait for the remote client to get connected. This is typically called from an external Thread.

Parameters:

sTimeout - in seconds to wait for connection. If timeout is < 1 then the there is no wait.

Throws:

java.util.concurrent.TimeoutException - if connection was not made in the timeout period.

RemoteException - if we received an unexpected remote exception instead.

ShutdownInvocationException - if either a local or remote shutdown has been initiated.

notifyConnectionListeners

protected void notifyConnectionListeners()

waitForRemoteReady

public void waitForRemoteReady(int sTimeout)
                        throws java.util.concurrent.TimeoutException,
                               RemoteException,
                               ShutdownInvocationException

Wait for the remote client to signal Ready for a new command. This is typically called from an external Thread.

Parameters:

sTimeout - in seconds to wait for ready. If timeout is < 1 then there is no wait.

Throws:

java.util.concurrent.TimeoutException - if Ready was not seen in the timeout period.

RemoteException - if we received an unexpected remote exception instead.

ShutdownInvocationException - if either a local or remote shutdown has been initiated.

notifyReadyListeners

protected void notifyReadyListeners()

performRemotePropsCommand

public java.util.Properties performRemotePropsCommand(java.util.Properties props,
                                                      int secsWaitReady,
                                                      int secsWaitRunning,
                                                      int secsWaitResult)
                                               throws java.lang.IllegalThreadStateException,
                                                      RemoteException,
                                                      java.util.concurrent.TimeoutException,
                                                      ShutdownInvocationException

Default implementation performs the following:

 resetResults();
 waitForRemoteReady(secsWaitReady);
 runner.sendDispatchProps(props);
 waitForRemoteRunning(secsWaitRunning);
 return waitForRemoteResult(secsWaitResult);
  

Parameters:

props - - the Dispatch Properties object containing all required command parameters for the remote client.

secsWaitRead - -- timeout in seconds to detect remoteReady.

secsWaitRunning - -- timeout in seconds to detect remoteRunning following the dispatch.

secsWaitResults - -- timeout in seconds to wait for results from the remote client.

Returns:

- the Result Properties returned by the remote client.

Throws:

ShutdownInvocationException

java.util.concurrent.TimeoutException

RemoteException

java.lang.IllegalThreadStateException - -- if the attempt to send the properties failed for some unknown reason.

See Also:

SoloRemoteControlRunner.sendDispatchProps(Properties)

performRemoteFileCommand

public java.util.Properties performRemoteFileCommand(java.lang.String filepath,
                                                     int secsWaitReady,
                                                     int secsWaitRunning,
                                                     int secsWaitResult)
                                              throws java.lang.IllegalThreadStateException,
                                                     RemoteException,
                                                     java.util.concurrent.TimeoutException,
                                                     ShutdownInvocationException

Default implementation performs the following:

 resetResults();
 waitForRemoteReady(secsWaitReady);
 runner.sendDispatchFile(filepath);
 waitForRemoteRunning(secsWaitRunning);
 return waitForRemoteResult(secsWaitResult);
  

Parameters:

filepath - - the filepath to the File to process.

secsWaitRead - -- timeout in seconds to detect remoteReady.

secsWaitRunning - -- timeout in seconds to detect remoteRunning following the dispatch.

secsWaitResults - -- timeout in seconds to wait for results from the remote client.

Returns:

- the Result Properties returned by the remote client.

Throws:

ShutdownInvocationException

java.util.concurrent.TimeoutException

RemoteException

java.lang.IllegalThreadStateException - -- if the attempt to send failed for some unknown reason.

See Also:

SoloRemoteControlRunner.sendDispatchProps(Properties)

performRemoteMessageCommand

public void performRemoteMessageCommand(java.lang.String message,
                                        int secsWaitReady,
                                        int secsWaitRunning)
                                 throws java.lang.IllegalThreadStateException,
                                        RemoteException,
                                        java.util.concurrent.TimeoutException,
                                        ShutdownInvocationException

Default implementation performs the following:

 resetResults();
 waitForRemoteReady(secsWaitReady);
 runner.sendMessage(message);
 waitForRemoteRunning(secsWaitRunning);
 

The routine does NOT waitForResults. This allows arbitrary messaging not always expecting a response.

Parameters:

message - to send to remote client

secsWaitRead - -- timeout in seconds to detect remoteReady.

secsWaitRunning - -- timeout in seconds to detect remoteRunning following the dispatch.

secsWaitResults - -- timeout in seconds to wait for results from the remote client.

Throws:

ShutdownInvocationException

java.util.concurrent.TimeoutException

RemoteException

java.lang.IllegalThreadStateException - -- if the attempt to send the message failed for some unknown reason.

See Also:

SoloRemoteControlRunner.sendDispatchProps(Properties)

performRemoteShutdown

public void performRemoteShutdown(int secsWaitReady,
                                  int secsWaitRunning,
                                  int secsWaitShutdown)
                           throws java.lang.IllegalThreadStateException,
                                  RemoteException,
                                  java.util.concurrent.TimeoutException,
                                  ShutdownInvocationException

Default implementation performs the following:

 resetResults();
 waitForRemoteReady(secsWaitReady);
 runner.sendShutdown();
 waitForRemoteRunning(secsWaitRunning);
 

The routine does NOT waitForResults. This allows arbitrary messaging not always expecting a response.

Parameters:

message - to send to remote client

secsWaitRead - -- timeout in seconds to detect remoteReady.

secsWaitRunning - -- timeout in seconds to detect remoteRunning following the dispatch.

secsWaitShutdown - -- timeout in seconds to wait to receive shutdown confirmation.

Throws:

java.util.concurrent.TimeoutException

RemoteException

java.lang.IllegalThreadStateException - -- if the attempt to send the message failed for some unknown reason.

ShutdownInvocationException

See Also:

SoloRemoteControlRunner.sendDispatchProps(Properties)

waitForRemoteRunning

public void waitForRemoteRunning(int sTimeout)
                          throws java.util.concurrent.TimeoutException,
                                 RemoteException,
                                 ShutdownInvocationException

Wait for the remote client to signal Running a new command. This is typically called from an external Thread.

Parameters:

sTimeout - in seconds to wait for Running. If timeout is < 1 then there is no wait.

Throws:

java.util.concurrent.TimeoutException - if Running was not seen in the timeout period.

RemoteException - if we received an unexpected remote exception instead.

ShutdownInvocationException - if either a local or remote shutdown has been initiated.

notifyRunningListeners

protected void notifyRunningListeners()

waitForRemoteResult

public java.util.Properties waitForRemoteResult(int sTimeout)
                                         throws java.util.concurrent.TimeoutException,
                                                RemoteException,
                                                ShutdownInvocationException

Wait for the remote client to signal results are available and return those results. This is typically called from an external Thread immediately following a "dispatch" call.

When a valid remote result has been received it is first checked for the presence of a special property . If that key is present then the property value is processed for a new timeout value and the routine waits for a new remote result using the new timeout value. If no new timeout is provided, or the format is non-numeric, the routine will simply wait again using the original sTimeout value.

Parameters:

sTimeout - in seconds to wait for Results. If timeout is < 1 then there is no wait.

Returns:

Properties -- the resultProps returned from the remote client or a new Properties object containing the consolidated remote result information.

Throws:

java.util.concurrent.TimeoutException - if Results was not seen in the timeout period.

RemoteException - if we received an unexpected remote exception instead.

ShutdownInvocationException - if either a local or remote shutdown has been initiated.

See Also:

consolidateResults()

notifyResultsListeners

protected void notifyResultsListeners(int rc,
                                      java.lang.String info)

notifyResultPropsListeners

protected void notifyResultPropsListeners(java.util.Properties props)

waitForRemoteShutdown

public void waitForRemoteShutdown(int sTimeout)
                           throws java.util.concurrent.TimeoutException,
                                  RemoteException

Wait for the remote client to signal its shutdown. This is typically called from an external Thread.

Parameters:

sTimeout - in seconds to wait for shutdown. If timeout is < 1 then there is no wait.

Throws:

java.util.concurrent.TimeoutException - if shutdown was not seen in the timeout period.

RemoteException - if we received an unexpected remote exception instead.

notifyRemoteShutdownListeners

protected void notifyRemoteShutdownListeners(int cause)

notifyLocalShutdownListeners

protected void notifyLocalShutdownListeners(int cause)

notifyExceptionListeners

protected void notifyExceptionListeners(java.lang.String message)

notifyMessageListeners

protected void notifyMessageListeners(java.lang.String message)