CommandScheduler

public class CommandScheduler
extends Thread implements ICommandScheduler, CommandFileWatcher.ICommandFileListener

java.lang.Object
   ↳ java.lang.Thread
     ↳ com.android.tradefed.command.CommandScheduler


A scheduler for running TradeFederation commands across all available devices.

Will attempt to prioritize commands to run based on a total running count of their execution time. e.g. infrequent or fast running commands will get prioritized over long running commands.

Runs forever in background until shutdown.

Summary

Nested classes

class CommandScheduler.CommandTracker

Represents one active command added to the scheduler. 

class CommandScheduler.CommandTrackerIdComparator

Comparator for CommandScheduler.CommandTracker

Public constructors

CommandScheduler()

Creates a CommandScheduler.

Public methods

boolean addCommand(String[] args, long totalExecTime)

An alternate addCommand(String[]) that accepts an initial total execution time for the command.

boolean addCommand(String[] args)

Adds a command to the scheduler.

void addCommandFile(String cmdFilePath, List<String> extraArgs)

Adds all commands from given file to the scheduler

void await()

Waits for scheduler to start running, including waiting for handover from old TF to complete if applicable.

void completeHandover()

Informs the command scheduler that a initiated handover sequence is fully complete, and it should re-initialize its remote manager on the default port.

void displayCommandQueue(PrintWriter printWriter)

Output detailed debug info on state of command execution queue.

void displayCommandsInfo(PrintWriter printWriter, String regex)

Output a list of current commands.

void displayInvocationsInfo(PrintWriter printWriter)

Displays a list of current invocations.

void dumpCommandsXml(PrintWriter printWriter, String regex)

Dump the expanded xml file for the command with all Option values specified for all current commands.

void execCommand(ICommandScheduler.IScheduledInvocationListener listener, ITestDevice device, String[] args)

Directly execute command on already allocated device.

void execCommand(ICommandScheduler.IScheduledInvocationListener listener, String[] args)

Directly allocates a device and executes a command without adding it to the command queue.

CommandFileWatcher getCommandFileWatcher()

Get the appropriate CommandFileWatcher for this scheduler

String getInvocationInfo(int invocationId)

Return the information on an invocation bu specifying the invocation id.

CommandRunner.ExitCode getLastInvocationExitCode()

Return the error code of the last invocation that ran.

Throwable getLastInvocationThrowable()

Return the Throwable from the last invocation that ran.

int getReadyCommandCount()

Returns the number of Commands in ready state in the queue.

long getShutdownTimeout()
void handoverInitiationComplete()

Informs the command scheduler that initial handover exchange of devices and commands in use is complete, and it can begin scheduling operation.

boolean handoverShutdown(int handoverPort)

Initiates a shutdown() and handover to another tradefed process on this same host.

void notifyFileChanged(File cmdFile, List<String> extraArgs)
void removeAllCommands()

Remove all commands from scheduler

void run()

The main execution block of this thread.

void setLastInvocationExitCode(CommandRunner.ExitCode code, Throwable throwable)

Helper method, when running inside a CommandRunner context, set an exit error code and a stack trace that can be returned.

boolean shouldShutdownOnCmdfileError()

Return true if we need to shutdown the scheduler on a command errors

void shutdown()

Attempt to gracefully shutdown the command scheduler.

void shutdownHard()

Attempt to forcefully shutdown the command scheduler.

void shutdownOnEmpty()

Similar to shutdown(), but will instead wait for all commands to be executed before exiting.

void start()

Starts the scheduler including setting up of logging, init of DeviceManager etc

boolean stopInvocation(int invocationId)

Stop a running invocation by specifying it's id.

boolean stopInvocation(ITestInvocation invocation)

Stop a running invocation.

Protected methods

void cleanUp()

Closes the logs and does any other necessary cleanup before we quit.

IConfigurationFactory getConfigFactory()

Factory method for getting a reference to the IConfigurationFactory

IDeviceManager getDeviceManager()

Factory method for getting a reference to the IDeviceManager

IKeyStoreClient getKeyStoreClient()

Fetches a IKeyStoreClient using the IKeyStoreFactory declared in IGlobalConfiguration or null if none is defined.

void initInvocation()

Optional initialization step before test invocation starts

void initLogging()

Initializes the ddmlib log.

boolean isShutdown()
boolean isShuttingDown()
void postProcessReadyCommands()

Placeholder method within the scheduler main loop, called after processReadyCommands(IDeviceManager).

void processReadyCommands(IDeviceManager manager)
void waitForAllInvocationThreads()

Wait until all invocation threads complete.

Public constructors

CommandScheduler

CommandScheduler ()

Creates a CommandScheduler.

Note: start must be called before use.

Public methods

addCommand

boolean addCommand (String[] args, 
                long totalExecTime)

An alternate addCommand(String[]) that accepts an initial total execution time for the command.

Useful when transitioning pre-existing commands from another tradefed process

Parameters
args String: the config arguments.

totalExecTime long: the accumulated elapsed execution time of the command

Returns
boolean true if command was added successfully

Throws
ConfigurationException

addCommand

boolean addCommand (String[] args)

Adds a command to the scheduler.

A command is essentially an instance of a configuration to run and its associated arguments.

If "--help" argument is specified the help text for the config will be outputed to stdout. Otherwise, the config will be added to the queue to run.

Parameters
args String: the config arguments.

Returns
boolean true if command was added successfully

Throws
ConfigurationException

addCommandFile

void addCommandFile (String cmdFilePath, 
                List<String> extraArgs)

Adds all commands from given file to the scheduler

Parameters
cmdFilePath String: the filesystem path of comand file

extraArgs List: a List of String arguments to append to each command parsed from file. Can be empty but should not be null.

Throws
ConfigurationException

await

void await ()

Waits for scheduler to start running, including waiting for handover from old TF to complete if applicable.

Throws
InterruptedException

completeHandover

void completeHandover ()

Informs the command scheduler that a initiated handover sequence is fully complete, and it should re-initialize its remote manager on the default port.

displayCommandQueue

void displayCommandQueue (PrintWriter printWriter)

Output detailed debug info on state of command execution queue.

displayCommandsInfo

void displayCommandsInfo (PrintWriter printWriter, 
                String regex)

Output a list of current commands.

Parameters
printWriter PrintWriter: the PrintWriter to output to.

regex String: the regular expression to which commands should be matched in order to be printed. If null, then all commands will be printed.

displayInvocationsInfo

void displayInvocationsInfo (PrintWriter printWriter)

Displays a list of current invocations.

Parameters
printWriter PrintWriter: the PrintWriter to output to.

dumpCommandsXml

void dumpCommandsXml (PrintWriter printWriter, 
                String regex)

Dump the expanded xml file for the command with all Option values specified for all current commands.

Parameters
printWriter PrintWriter: the PrintWriter to output the status to.

regex String: the regular expression to which commands should be matched in order for the xml file to be dumped. If null, then all commands will be dumped.

execCommand

void execCommand (ICommandScheduler.IScheduledInvocationListener listener, 
                ITestDevice device, 
                String[] args)

Directly execute command on already allocated device.

Parameters
listener ICommandScheduler.IScheduledInvocationListener: the ICommandScheduler.IScheduledInvocationListener to be informed

device ITestDevice: the ITestDevice to use

args String: the command arguments

Throws
ConfigurationException

execCommand

void execCommand (ICommandScheduler.IScheduledInvocationListener listener, 
                String[] args)

Directly allocates a device and executes a command without adding it to the command queue.

Parameters
listener ICommandScheduler.IScheduledInvocationListener: the ICommandScheduler.IScheduledInvocationListener to be informed

args String: the command arguments

Throws
ConfigurationException
NoDeviceException

getCommandFileWatcher

CommandFileWatcher getCommandFileWatcher ()

Get the appropriate CommandFileWatcher for this scheduler

Returns
CommandFileWatcher

getInvocationInfo

String getInvocationInfo (int invocationId)

Return the information on an invocation bu specifying the invocation id.

Parameters
invocationId int: the tracking id of the invocation.

Returns
String A String containing information about the invocation.

getLastInvocationExitCode

CommandRunner.ExitCode getLastInvocationExitCode ()

Return the error code of the last invocation that ran. Return 0 (no error), if no invocation has ran yet.

Returns
CommandRunner.ExitCode

getLastInvocationThrowable

Throwable getLastInvocationThrowable ()

Return the Throwable from the last invocation that ran. Return null, if no throwable is available.

Returns
Throwable

getReadyCommandCount

int getReadyCommandCount ()

Returns the number of Commands in ready state in the queue.

Returns
int

getShutdownTimeout

long getShutdownTimeout ()

Returns
long

handoverInitiationComplete

void handoverInitiationComplete ()

Informs the command scheduler that initial handover exchange of devices and commands in use is complete, and it can begin scheduling operation.

handoverShutdown

boolean handoverShutdown (int handoverPort)

Initiates a shutdown() and handover to another tradefed process on this same host.

The scheduler will inform the remote tradefed process listening on that port of freed devices as they become available.

Parameters
handoverPort int

Returns
boolean true if handover initiation was successful, false otherwise

notifyFileChanged

void notifyFileChanged (File cmdFile, 
                List<String> extraArgs)

Parameters
cmdFile File

extraArgs List

removeAllCommands

void removeAllCommands ()

Remove all commands from scheduler

run

void run ()

The main execution block of this thread.

setLastInvocationExitCode

void setLastInvocationExitCode (CommandRunner.ExitCode code, 
                Throwable throwable)

Helper method, when running inside a CommandRunner context, set an exit error code and a stack trace that can be returned.

Parameters
code CommandRunner.ExitCode

throwable Throwable

shouldShutdownOnCmdfileError

boolean shouldShutdownOnCmdfileError ()

Return true if we need to shutdown the scheduler on a command errors

Returns
boolean

shutdown

void shutdown ()

Attempt to gracefully shutdown the command scheduler.

Clears commands waiting to be tested, and requests that all invocations in progress shut down gracefully.

After shutdown is called, the scheduler main loop will wait for all invocations in progress to complete before exiting completely.

shutdownHard

void shutdownHard ()

Attempt to forcefully shutdown the command scheduler.

Similar to shutdown(), but will also forcefully kill the adb connection, in an attempt to 'inspire' invocations in progress to complete quicker.

shutdownOnEmpty

void shutdownOnEmpty ()

Similar to shutdown(), but will instead wait for all commands to be executed before exiting.

Note that if any commands are in loop mode, the scheduler will never exit.

start

void start ()

Starts the scheduler including setting up of logging, init of DeviceManager etc

stopInvocation

boolean stopInvocation (int invocationId)

Stop a running invocation by specifying it's id.

Parameters
invocationId int

Returns
boolean true if the invocation was stopped, false otherwise

stopInvocation

boolean stopInvocation (ITestInvocation invocation)

Stop a running invocation.

Parameters
invocation ITestInvocation

Returns
boolean true if the invocation was stopped, false otherwise

Protected methods

cleanUp

void cleanUp ()

Closes the logs and does any other necessary cleanup before we quit.

Exposed so unit tests can mock.

getConfigFactory

IConfigurationFactory getConfigFactory ()

Factory method for getting a reference to the IConfigurationFactory

Returns
IConfigurationFactory the IConfigurationFactory to use

getDeviceManager

IDeviceManager getDeviceManager ()

Factory method for getting a reference to the IDeviceManager

Returns
IDeviceManager the IDeviceManager to use

getKeyStoreClient

IKeyStoreClient getKeyStoreClient ()

Fetches a IKeyStoreClient using the IKeyStoreFactory declared in IGlobalConfiguration or null if none is defined.

Returns
IKeyStoreClient IKeyStoreClient

initInvocation

void initInvocation ()

Optional initialization step before test invocation starts

initLogging

void initLogging ()

Initializes the ddmlib log.

Exposed so unit tests can mock.

isShutdown

boolean isShutdown ()

Returns
boolean

isShuttingDown

boolean isShuttingDown ()

Returns
boolean

postProcessReadyCommands

void postProcessReadyCommands ()

Placeholder method within the scheduler main loop, called after processReadyCommands(IDeviceManager). Default implementation is empty and does not provide any extra actions.

processReadyCommands

void processReadyCommands (IDeviceManager manager)

Parameters
manager IDeviceManager

waitForAllInvocationThreads

void waitForAllInvocationThreads ()

Wait until all invocation threads complete.