IRunUtil

public interface IRunUtil

com.android.tradefed.util.IRunUtil

Interface for running timed operations and system commands.

Summary

Nested classes

interface IRunUtil.IRunnableResult

An interface for asynchronously executing an operation that returns a boolean status. 

Public methods

abstract void allowInterrupt(boolean allow)

Allows/disallows run interrupts on the current thread.

abstract void interrupt(Thread thread, String message, ErrorIdentifier errorId)

Interrupts the ongoing/forthcoming run operations on the given thread.

abstract void interrupt(Thread thread, String message)

Interrupts the ongoing/forthcoming run operations on the given thread.

abstract boolean isInterruptAllowed()

Give the interrupt status of the RunUtil.

abstract Process runCmdInBackground(Redirect redirect, command)

An alternate runCmdInBackground(String) method that accepts the command arguments in ERROR(/List) form.

abstract Process runCmdInBackground( command)

An alternate runCmdInBackground(String) method that accepts the command arguments in ERROR(/List) form.

abstract Process runCmdInBackground( command, OutputStream output)

Running command with a ERROR(/OutputStream) log the output of the command.

abstract Process runCmdInBackground(String... command)

Helper method to execute a system command asynchronously.

abstract Process runCmdInBackground(Redirect redirect, String... command)

Helper method to execute a system command asynchronously.

abstract boolean runEscalatingTimedRetry(long opTimeout, long initialPollInterval, long maxPollInterval, long maxTime, IRunUtil.IRunnableResult runnable)

Block and executes an operation multiple times until it is successful.

abstract boolean runFixedTimedRetry(long opTimeout, long pollInterval, long maxTime, IRunUtil.IRunnableResult runnable)

Block and executes an operation multiple times until it is successful.

abstract boolean runFixedTimedRetryWithOutputMonitor(long opTimeout, long idleOutputTimeout, long pollInterval, long maxTime, IRunUtil.IRunnableResult runnable)

Block and executes an operation multiple times until it is successful.

abstract CommandStatus runTimed(long timeout, IRunUtil.IRunnableResult runnable, boolean logErrors)

Block and executes an operation, aborting if it takes longer than a specified time.

abstract CommandResult runTimedCmd(long timeout, OutputStream stdout, OutputStream stderr, String... command)

Helper method to execute a system command, abort if it takes longer than a specified time, and redirect output to files if specified.

abstract CommandResult runTimedCmd(long timeout, String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time.

abstract CommandResult runTimedCmdRetry(long timeout, long retryInterval, int attempts, String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time.

abstract CommandResult runTimedCmdRetryWithOutputMonitor(long timeout, long idleOutputTimeout, long retryInterval, int attempts, String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time.

abstract CommandResult runTimedCmdSilently(long timeout, String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time.

abstract CommandResult runTimedCmdSilentlyRetry(long timeout, long retryInterval, int attempts, String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time.

abstract CommandResult runTimedCmdWithInput(long timeout, String input, File stdoutFile, File stderrFile, String... command)

Helper method to execute a system command, abort if it takes longer than a specified time, and redirect output to files if specified.

abstract CommandResult runTimedCmdWithInput(long timeout, String input, String... command)

Helper method to execute a system command that requires stdin input, and aborting if it takes longer than a specified time.

abstract CommandResult runTimedCmdWithInput(long timeout, String input, command)

Helper method to execute a system command that requires stdin input, and aborting if it takes longer than a specified time.

abstract CommandResult runTimedCmdWithInputRedirect(long timeout, File inputRedirect, String... command)

Helper method to execute a system command that requires redirecting Stdin from a file, and aborting if it takes longer than a specified time.

abstract CommandResult runTimedCmdWithOutputMonitor(long timeout, long idleOutputTimeout, OutputStream stdout, OutputStream stderr, String... command)

Helper method to execute a system command, abort if it takes longer than a specified time, and redirect output to files if specified.

abstract CommandResult runTimedCmdWithOutputMonitor(long timeout, long idleOutputTimeout, String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time.

abstract CommandResult runTimedCmdWithOutputMonitor(long timeout, long idleOutputTimeout, OutputStream stdout, OutputStream stderr, ICacheClient cacheClient, String... command)

Helper method to execute a system command with caching.

abstract boolean runTimedRetry(long opTimeout, long pollInterval, int attempts, IRunUtil.IRunnableResult runnable)

Block and executes an operation multiple times until it is successful.

abstract boolean runTimedRetryWithOutputMonitor(long opTimeout, long idleOutputTimeout, long pollInterval, int attempts, IRunUtil.IRunnableResult runnable)

Block and executes an operation multiple times until it is successful.

abstract CommandStatus runTimedWithOutputMonitor(long timeout, long idleOutputTimeout, IRunUtil.IRunnableResult runnable, boolean logErrors)

Block and executes an operation, aborting if it takes longer than a specified time.

abstract void setEnvVariable(String key, String value)

Sets a environment variable to be used when running system commands.

abstract void setEnvVariablePriority(IRunUtil.EnvPriority priority)

Decide whether or not when creating a process, unsetting environment variable is higher priority than setting them.

abstract void setInterruptibleInFuture(Thread thread, long timeMs)

Set as interruptible after some waiting time.

abstract void setLinuxInterruptProcess(boolean interrupt)

Allow to use linux 'kill' interruption on process running through #runTimed methods when it reaches a timeout.

abstract void setRedirectStderrToStdout(boolean redirect)

Set the standard error stream to redirect to the standard output stream when running system commands.

abstract void setWorkingDir(File dir)

Sets the working directory for system commands.

abstract void sleep(long time)

Helper method to sleep for given time, ignoring any exceptions.

abstract void unsetEnvVariable(String key)

Unsets an environment variable, so the system commands run without this environment variable.

abstract void uploadCache(ICacheClient cacheClient, ExecutableActionResult actionResult)

Uploads the last ExecutableActionResult ran with a cacheClient.

Public methods

allowInterrupt

public abstract void allowInterrupt (boolean allow)

Allows/disallows run interrupts on the current thread. If it is allowed, run operations of the current thread can be interrupted from other threads via interrupt(Thread, String) method.

Parameters
allow boolean: whether to allow run interrupts on the current thread.

interrupt

public abstract void interrupt (Thread thread, 
                String message, 
                ErrorIdentifier errorId)

Interrupts the ongoing/forthcoming run operations on the given thread. The run operations on the given thread will throw RunInterruptedException.

Parameters
message String: the message for RunInterruptedException.
errorId ErrorIdentifier: Representing the cause of the interruption when known.

interrupt

public abstract void interrupt (Thread thread, 
                String message)

Interrupts the ongoing/forthcoming run operations on the given thread. The run operations on the given thread will throw RunInterruptedException.

Parameters
message String: the message for RunInterruptedException.

isInterruptAllowed

public abstract boolean isInterruptAllowed ()

Give the interrupt status of the RunUtil.

Returns
boolean true if the Run can be interrupted, false otherwise.

runCmdInBackground

public abstract Process runCmdInBackground (Redirect redirect, 
                 command)

An alternate runCmdInBackground(String) method that accepts the command arguments in ERROR(/List) form.

Parameters
redirect Redirect: The ERROR(/Redirect) to apply to the ProcessBuilder.
command : the ERROR(/List) containing specified system command and optionally arguments to exec
Returns
Process the Process of the executed command
Throws
if command failed to run

runCmdInBackground

public abstract Process runCmdInBackground ( command)

An alternate runCmdInBackground(String) method that accepts the command arguments in ERROR(/List) form.

Parameters
command : the ERROR(/List) containing specified system command and optionally arguments to exec
Returns
Process the Process of the executed command
Throws
if command failed to run

runCmdInBackground

public abstract Process runCmdInBackground ( command, 
                OutputStream output)

Running command with a ERROR(/OutputStream) log the output of the command. Stdout and stderr are merged together.

Parameters
command : the command to run
output OutputStream: the OutputStream to save the output
Returns
Process the Process running the command
Throws
IOException

runCmdInBackground

public abstract Process runCmdInBackground (String... command)

Helper method to execute a system command asynchronously.

Will return immediately after launching command.

Parameters
command String: the specified system command and optionally arguments to exec
Returns
Process the Process of the executed command
Throws
if command failed to run

runCmdInBackground

public abstract Process runCmdInBackground (Redirect redirect, 
                String... command)

Helper method to execute a system command asynchronously.

Will return immediately after launching command.

Parameters
redirect Redirect: The ERROR(/Redirect) to apply to the ProcessBuilder.
command String: the specified system command and optionally arguments to exec
Returns
Process the Process of the executed command
Throws
if command failed to run

runEscalatingTimedRetry

public abstract boolean runEscalatingTimedRetry (long opTimeout, 
                long initialPollInterval, 
                long maxPollInterval, 
                long maxTime, 
                IRunUtil.IRunnableResult runnable)

Block and executes an operation multiple times until it is successful.

Exponentially increase the wait time between operation attempts. This is intended to be used when performing an operation such as polling a server, to give it time to recover in case it is temporarily down.

Parameters
opTimeout long: maximum time to wait in ms for a single operation attempt
initialPollInterval long: initial time to wait between operation attempts
maxPollInterval long: the max time to wait between operation attempts
maxTime long: the total approximate maximum time to keep trying the operation
runnable IRunUtil.IRunnableResult: IRunUtil.IRunnableResult to execute
Returns
boolean true if operation completed successfully before maxTime expired

runFixedTimedRetry

public abstract boolean runFixedTimedRetry (long opTimeout, 
                long pollInterval, 
                long maxTime, 
                IRunUtil.IRunnableResult runnable)

Block and executes an operation multiple times until it is successful.

Parameters
opTimeout long: maximum time to wait in ms for a single operation attempt
pollInterval long: initial time to wait between operation attempts
maxTime long: the total approximate maximum time to keep trying the operation
runnable IRunUtil.IRunnableResult: IRunUtil.IRunnableResult to execute
Returns
boolean true if operation completed successfully before maxTime expired

runFixedTimedRetryWithOutputMonitor

public abstract boolean runFixedTimedRetryWithOutputMonitor (long opTimeout, 
                long idleOutputTimeout, 
                long pollInterval, 
                long maxTime, 
                IRunUtil.IRunnableResult runnable)

Block and executes an operation multiple times until it is successful. Also monitors the output streams for activity, aborting if no stream activity is observed for a specified time. If the idleOutputTimeout is set to zero, no stream monitoring will occur.

Parameters
opTimeout long: maximum time to wait in ms for a single operation attempt
idleOutputTimeout long: maximum time to wait in ms for output on the output streams
pollInterval long: initial time to wait between operation attempts
maxTime long: the total approximate maximum time to keep trying the operation
runnable IRunUtil.IRunnableResult: IRunUtil.IRunnableResult to execute
Returns
boolean true if operation completed successfully before maxTime expired

runTimed

public abstract CommandStatus runTimed (long timeout, 
                IRunUtil.IRunnableResult runnable, 
                boolean logErrors)

Block and executes an operation, aborting if it takes longer than a specified time.

Parameters
timeout long: maximum time to wait in ms
runnable IRunUtil.IRunnableResult: IRunUtil.IRunnableResult to execute
logErrors boolean: log errors on exception or not.
Returns
CommandStatus the CommandStatus result of operation.

runTimedCmd

public abstract CommandResult runTimedCmd (long timeout, 
                OutputStream stdout, 
                OutputStream stderr, 
                String... command)

Helper method to execute a system command, abort if it takes longer than a specified time, and redirect output to files if specified. When ERROR(/OutputStream) are provided this way, they will be left open at the end of the function.

Parameters
timeout long: timeout maximum time to wait in ms. 0 means no timeout.
stdout OutputStream: ERROR(/OutputStream) where the std output will be redirected. Can be null.
stderr OutputStream: ERROR(/OutputStream) where the error output will be redirected. Can be null.
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmd

public abstract CommandResult runTimedCmd (long timeout, 
                String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time.

Parameters
timeout long: maximum time to wait in ms. 0 means no timeout.
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdRetry

public abstract CommandResult runTimedCmdRetry (long timeout, 
                long retryInterval, 
                int attempts, 
                String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time.

Parameters
timeout long: maximum time to wait in ms for each attempt
retryInterval long: time to wait between command retries
attempts int: the maximum number of attempts to try
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdRetryWithOutputMonitor

public abstract CommandResult runTimedCmdRetryWithOutputMonitor (long timeout, 
                long idleOutputTimeout, 
                long retryInterval, 
                int attempts, 
                String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time. Also monitors the output streams for activity, aborting if no stream activity is observed for a specified time. If the idleOutputTimeout is set to zero, no stream monitoring will occur.

Parameters
timeout long: maximum time to wait in ms for each attempt
idleOutputTimeout long: maximum time to wait in ms for output on the output streams
retryInterval long: time to wait between command retries
attempts int: the maximum number of attempts to try
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdSilently

public abstract CommandResult runTimedCmdSilently (long timeout, 
                String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time. Similar to runTimedCmd(long, String), but does not log any errors on exception.

Parameters
timeout long: maximum time to wait in ms
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdSilentlyRetry

public abstract CommandResult runTimedCmdSilentlyRetry (long timeout, 
                long retryInterval, 
                int attempts, 
                String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time. Similar to runTimedCmdRetry(long, long, int, String[]), but does not log any errors on exception.

Parameters
timeout long: maximum time to wait in ms
retryInterval long: time to wait between command retries
attempts int: the maximum number of attempts to try
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdWithInput

public abstract CommandResult runTimedCmdWithInput (long timeout, 
                String input, 
                File stdoutFile, 
                File stderrFile, 
                String... command)

Helper method to execute a system command, abort if it takes longer than a specified time, and redirect output to files if specified.

Parameters
timeout long: timeout maximum time to wait in ms. 0 means no timeout.
input String: the stdin input to pass to process
stdoutFile File: ERROR(/File) where the std output will be redirected. Can be null.
stderrFile File: ERROR(/File) where the error output will be redirected. Can be null.
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdWithInput

public abstract CommandResult runTimedCmdWithInput (long timeout, 
                String input, 
                String... command)

Helper method to execute a system command that requires stdin input, and aborting if it takes longer than a specified time.

Parameters
timeout long: maximum time to wait in ms
input String: the stdin input to pass to process
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdWithInput

public abstract CommandResult runTimedCmdWithInput (long timeout, 
                String input, 
                 command)

Helper method to execute a system command that requires stdin input, and aborting if it takes longer than a specified time.

Parameters
timeout long: maximum time to wait in ms
input String: the stdin input to pass to process
command : ERROR(/List) containing the system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdWithInputRedirect

public abstract CommandResult runTimedCmdWithInputRedirect (long timeout, 
                File inputRedirect, 
                String... command)

Helper method to execute a system command that requires redirecting Stdin from a file, and aborting if it takes longer than a specified time.

Parameters
timeout long: maximum time to wait in ms
inputRedirect File: the ERROR(/File) to redirect as standard input using ProcessBuilder.redirectInput(). If null, stdin won't be redirected.
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdWithOutputMonitor

public abstract CommandResult runTimedCmdWithOutputMonitor (long timeout, 
                long idleOutputTimeout, 
                OutputStream stdout, 
                OutputStream stderr, 
                String... command)

Helper method to execute a system command, abort if it takes longer than a specified time, and redirect output to files if specified. When ERROR(/OutputStream) are provided this way, they will be left open at the end of the function.

Parameters
timeout long: timeout maximum time to wait in ms. 0 means no timeout.
idleOutputTimeout long: maximum time to wait in ms for output on the output streams
stdout OutputStream: ERROR(/OutputStream) where the std output will be redirected. Can be null.
stderr OutputStream: ERROR(/OutputStream) where the error output will be redirected. Can be null.
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdWithOutputMonitor

public abstract CommandResult runTimedCmdWithOutputMonitor (long timeout, 
                long idleOutputTimeout, 
                String... command)

Helper method to execute a system command, and aborting if it takes longer than a specified time. Also monitors the output streams for activity, aborting if no stream activity is observed for a specified time. If the idleOutputTimeout is set to zero, no stream monitoring will occur.

Parameters
timeout long: maximum time to wait in ms. 0 means no timeout.
idleOutputTimeout long: maximum time to wait in ms for output on the output streams
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

runTimedCmdWithOutputMonitor

public abstract CommandResult runTimedCmdWithOutputMonitor (long timeout, 
                long idleOutputTimeout, 
                OutputStream stdout, 
                OutputStream stderr, 
                ICacheClient cacheClient, 
                String... command)

Helper method to execute a system command with caching.

If cacheClient is specified, the caching will be enabled. If the cache is available, the cached result will be returned. Otherwise, runTimedCmdWithOutputMonitor(long, long, OutputStream, OutputStream, String) will be used to execute the command and the result will be uploaded for caching.

Parameters
timeout long: timeout maximum time to wait in ms. 0 means no timeout.
idleOutputTimeout long: maximum time to wait in ms for output on the output streams.
stdout OutputStream: ERROR(/OutputStream) where the std output will be redirected. Can be null.
stderr OutputStream: ERROR(/OutputStream) where the error output will be redirected. Can be null.
cacheClient ICacheClient: an instance of ICacheClient used to handle caching.
command String: the specified system command and optionally arguments to exec.
Returns
CommandResult a CommandResult containing result from command run.

runTimedRetry

public abstract boolean runTimedRetry (long opTimeout, 
                long pollInterval, 
                int attempts, 
                IRunUtil.IRunnableResult runnable)

Block and executes an operation multiple times until it is successful.

Parameters
opTimeout long: maximum time to wait in ms for one operation attempt
pollInterval long: time to wait between command retries
attempts int: the maximum number of attempts to try
runnable IRunUtil.IRunnableResult: IRunUtil.IRunnableResult to execute
Returns
boolean true if operation completed successfully before attempts reached.

runTimedRetryWithOutputMonitor

public abstract boolean runTimedRetryWithOutputMonitor (long opTimeout, 
                long idleOutputTimeout, 
                long pollInterval, 
                int attempts, 
                IRunUtil.IRunnableResult runnable)

Block and executes an operation multiple times until it is successful. Also monitors the output streams for activity, aborting if no stream activity is observed for a specified time. If the idleOutputTimeout is set to zero, no stream monitoring will occur.

Parameters
opTimeout long: maximum time to wait in ms for one operation attempt
idleOutputTimeout long: maximum time to wait in ms for output on the output streams
pollInterval long: time to wait between command retries
attempts int: the maximum number of attempts to try
runnable IRunUtil.IRunnableResult: IRunUtil.IRunnableResult to execute
Returns
boolean true if operation completed successfully before attempts reached.

runTimedWithOutputMonitor

public abstract CommandStatus runTimedWithOutputMonitor (long timeout, 
                long idleOutputTimeout, 
                IRunUtil.IRunnableResult runnable, 
                boolean logErrors)

Block and executes an operation, aborting if it takes longer than a specified time. Also monitors the output streams for activity, aborting if no stream activity is observed for a specified time. If the idleOutputTimeout is set to zero, no stream monitoring will occur.

Parameters
timeout long: maximum time to wait in ms
idleOutputTimeout long: maximum time to wait in ms for output on the output streams
runnable IRunUtil.IRunnableResult: IRunUtil.IRunnableResult to execute
logErrors boolean: log errors on exception or not.
Returns
CommandStatus the CommandStatus result of operation.

setEnvVariable

public abstract void setEnvVariable (String key, 
                String value)

Sets a environment variable to be used when running system commands.

Parameters
key String: the variable name
value String: the variable value

setEnvVariablePriority

public abstract void setEnvVariablePriority (IRunUtil.EnvPriority priority)

Decide whether or not when creating a process, unsetting environment variable is higher priority than setting them. By Default, unsetting is higher priority: meaning if an attempt to set a variable with the same name is made, it won't happen since the variable will be unset. Cannot be used on the default IRunUtil instance.

Parameters
priority IRunUtil.EnvPriority

setInterruptibleInFuture

public abstract void setInterruptibleInFuture (Thread thread, 
                long timeMs)

Set as interruptible after some waiting time. ERROR(/CommandScheduler#shutdownHard()) to enforce we terminate eventually.

Parameters
thread Thread: the thread that will become interruptible.
timeMs long: time to wait before setting interruptible.

setLinuxInterruptProcess

public abstract void setLinuxInterruptProcess (boolean interrupt)

Allow to use linux 'kill' interruption on process running through #runTimed methods when it reaches a timeout. Cannot be used on the default IRunUtil instance.

Parameters
interrupt boolean

setRedirectStderrToStdout

public abstract void setRedirectStderrToStdout (boolean redirect)

Set the standard error stream to redirect to the standard output stream when running system commands. Initial value is false.

Parameters
redirect boolean: new value for whether or not to redirect

setWorkingDir

public abstract void setWorkingDir (File dir)

Sets the working directory for system commands.

Parameters
dir File: the working directory

sleep

public abstract void sleep (long time)

Helper method to sleep for given time, ignoring any exceptions.

Parameters
time long: ms to sleep. values less than or equal to 0 will be ignored

unsetEnvVariable

public abstract void unsetEnvVariable (String key)

Unsets an environment variable, so the system commands run without this environment variable.

Parameters
key String: the variable name

uploadCache

public abstract void uploadCache (ICacheClient cacheClient, 
                ExecutableActionResult actionResult)

Uploads the last ExecutableActionResult ran with a cacheClient.

Parameters
cacheClient ICacheClient: The ICacheClient used to upload the result.
actionResult ExecutableActionResult: The ExecutableActionResult to upload.