ICommandScheduler

public interface ICommandScheduler

com.android.tradefed.command.ICommandScheduler


A scheduler for running TradeFederation commands.

Summary

Nested classes

interface ICommandScheduler.IScheduledInvocationListener

Listener for invocation events when invocation completes. 

Public methods

abstract Pair<Boolean, Integer> addCommand(String[] args)

Adds a command to the scheduler.

abstract void addCommandFile(String cmdFile, extraArgs)

Adds all commands from given file to the scheduler

abstract void await()

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

abstract void displayCommandQueue(PrintWriter printWriter)

Output detailed debug info on state of command execution queue.

abstract void displayCommandsInfo(PrintWriter printWriter, String regex)

Output a list of current commands.

abstract void displayInvocationsInfo(PrintWriter printWriter)

Displays a list of current invocations.

abstract void dumpCommandsXml(PrintWriter printWriter, String regex)

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

abstract long execCommand(IInvocationContext context, ICommandScheduler.IScheduledInvocationListener listener, String[] args)

Directly allocates a device and executes a command without adding it to the command queue using an already existing IInvocationContext.

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

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

abstract long execCommand(ICommandScheduler.IScheduledInvocationListener listener, devices, String[] args)

Directly execute command on already allocated devices.

abstract CommandFileWatcher getCommandFileWatcher()

Get the appropriate CommandFileWatcher for this scheduler

abstract int getExecutingCommandCount()

Returns the number of Commands in executing state.

abstract String getInvocationInfo(int invocationId)

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

abstract CommandRunner.ExitCode getLastInvocationExitCode()

Return the error code of the last invocation that ran.

abstract Throwable getLastInvocationThrowable()

Return the Throwable from the last invocation that ran.

abstract int getReadyCommandCount()

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

abstract boolean isDeviceInInvocationThread(ITestDevice device)

Returns true if the device is used by an active invocation thread.

abstract void join()

Waits for scheduler to complete.

abstract void join(long millis)

Waits for scheduler to complete or timeout after the duration specified in milliseconds.

abstract void removeAllCommands()

Remove all commands from scheduler

abstract void setClearcutClient(ClearcutClient client)

Set the client to report harness data

abstract boolean shouldShutdownOnCmdfileError()

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

default void shutdown()

Attempt to gracefully shutdown the command scheduler.

abstract void shutdown(boolean notifyStop)

Attempt to gracefully shutdown the command scheduler.

abstract void shutdownHard(boolean killAdb)

Attempt to forcefully shutdown the command scheduler.

abstract void shutdownHard()

Attempt to forcefully shutdown the command scheduler.

abstract void shutdownOnEmpty()

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

abstract void start()

Start the ICommandScheduler.

abstract boolean stopInvocation(int invocationId, String cause)

Stop a running invocation by specifying it's id.

default boolean stopInvocation(int invocationId)

Stop a running invocation by specifying it's id.

abstract boolean stopInvocation(ITestInvocation invocation)

Stop a running invocation.

default void stopScheduling()

Stops scheduling and accepting new tests but does not stop Tradefed.

Public methods

addCommand

public abstract Pair<Boolean, Integer> 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
Pair<Boolean, Integer> A pair of values, first value is a Boolean true if command was added successfully. Second value is the known command tracker id(non-negative value) if the command was added successfully, return 0 when command is added for all devices, otherwise -1.

Throws
ConfigurationException if command could not be parsed

addCommandFile

public abstract void addCommandFile (String cmdFile, 
                 extraArgs)

Adds all commands from given file to the scheduler

Parameters
cmdFile String: the filesystem path of comand file

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

Throws
ConfigurationException if command file could not be parsed

See also:

await

public abstract void await ()

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

displayCommandQueue

public abstract void displayCommandQueue (PrintWriter printWriter)

Output detailed debug info on state of command execution queue.

displayCommandsInfo

public abstract void displayCommandsInfo (PrintWriter printWriter, 
                String regex)

Output a list of current commands.

Parameters
printWriter PrintWriter: the ERROR(/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

public abstract void displayInvocationsInfo (PrintWriter printWriter)

Displays a list of current invocations.

Parameters
printWriter PrintWriter: the ERROR(/PrintWriter) to output to.

dumpCommandsXml

public abstract 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 ERROR(/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

public abstract long execCommand (IInvocationContext context, 
                ICommandScheduler.IScheduledInvocationListener listener, 
                String[] args)

Directly allocates a device and executes a command without adding it to the command queue using an already existing IInvocationContext.

Parameters
context IInvocationContext: an existing IInvocationContext.

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

args String: the command arguments

Returns
long

Throws
ConfigurationException if command was invalid
NoDeviceException if there is no device to use

execCommand

public abstract long 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

Returns
long The invocation id of the scheduled command.

Throws
ConfigurationException if command was invalid
NoDeviceException if there is no device to use

execCommand

public abstract long execCommand (ICommandScheduler.IScheduledInvocationListener listener, 
                 devices, 
                String[] args)

Directly execute command on already allocated devices.

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

devices : the ERROR(/List) to use

args String: the command arguments

Returns
long The invocation id of the scheduled command.

Throws
ConfigurationException if command was invalid

getCommandFileWatcher

public abstract CommandFileWatcher getCommandFileWatcher ()

Get the appropriate CommandFileWatcher for this scheduler

Returns
CommandFileWatcher

getExecutingCommandCount

public abstract int getExecutingCommandCount ()

Returns the number of Commands in executing state.

Returns
int

getInvocationInfo

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

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

public abstract Throwable getLastInvocationThrowable ()

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

Returns
Throwable

getReadyCommandCount

public abstract int getReadyCommandCount ()

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

Returns
int

isDeviceInInvocationThread

public abstract boolean isDeviceInInvocationThread (ITestDevice device)

Returns true if the device is used by an active invocation thread.

Parameters
device ITestDevice

Returns
boolean

join

public abstract void join ()

Waits for scheduler to complete.

See also:

join

public abstract void join (long millis)

Waits for scheduler to complete or timeout after the duration specified in milliseconds.

Parameters
millis long

See also:

removeAllCommands

public abstract void removeAllCommands ()

Remove all commands from scheduler

setClearcutClient

public abstract void setClearcutClient (ClearcutClient client)

Set the client to report harness data

Parameters
client ClearcutClient

shouldShutdownOnCmdfileError

public abstract boolean shouldShutdownOnCmdfileError ()

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

Returns
boolean

shutdown

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

shutdown

public abstract void shutdown (boolean notifyStop)

Attempt to gracefully shutdown the command scheduler.

Parameters
notifyStop boolean: if true, notifies invocations of TF shutdown.

shutdownHard

public abstract void shutdownHard (boolean killAdb)

Attempt to forcefully shutdown the command scheduler.

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

Parameters
killAdb boolean

shutdownHard

public abstract void shutdownHard ()

Attempt to forcefully shutdown the command scheduler. Same as shutdownHard(true).

shutdownOnEmpty

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

public abstract void start ()

Start the ICommandScheduler.

Must be called before calling other methods.

Will run until shutdown() is called. see Thread.start().

stopInvocation

public abstract boolean stopInvocation (int invocationId, 
                String cause)

Stop a running invocation by specifying it's id.

Parameters
invocationId int: the tracking id of the invocation.

cause String: the cause for stopping the invocation.

Returns
boolean true if the invocation was stopped, false otherwise

Throws
UnsupportedOperationException if the implementation doesn't support this

stopInvocation

public 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

Throws
UnsupportedOperationException if the implementation doesn't support this

stopInvocation

public abstract boolean stopInvocation (ITestInvocation invocation)

Stop a running invocation.

Parameters
invocation ITestInvocation

Returns
boolean true if the invocation was stopped, false otherwise

Throws
UnsupportedOperationException if the implementation doesn't support this

stopScheduling

public void stopScheduling ()

Stops scheduling and accepting new tests but does not stop Tradefed. This is meant to enable a two steps shutdown where first we drain all the running tests, then terminate Tradefed process.