to top
public class

RunUtil

extends Object
implements IRunUtil
java.lang.Object
   ↳ com.android.tradefed.util.RunUtil

Class Overview

A collection of helper methods for executing operations.

Summary

Public Constructors
RunUtil()
Create a new RunUtil object to use.
Public Methods
void allowInterrupt(boolean allow)
Allows/disallows run interrupts on the current thread.
static IRunUtil getDefault()
Get a reference to the default RunUtil object.
void interrupt(Thread thread, String message)
Interrupts the ongoing/forthcoming run operations on the given thread.
Process runCmdInBackground(List<String> command, OutputStream output)
Running command with a OutputStream log the output of the command.
Process runCmdInBackground(String... command)
Helper method to execute a system command asynchronously.
Process runCmdInBackground(List<String> command)
An alternate runCmdInBackground(String) method that accepts the command arguments in List form.
boolean runEscalatingTimedRetry(long opTimeout, long initialPollInterval, long maxPollInterval, long maxTime, IRunUtil.IRunnableResult runnable)
Block and executes an operation multiple times until it is successful.
boolean runFixedTimedRetry(long opTimeout, long pollInterval, long maxTime, IRunUtil.IRunnableResult runnable)
Block and executes an operation multiple times until it is successful.
CommandStatus runTimed(long timeout, IRunUtil.IRunnableResult runnable, boolean logErrors)
Block and executes an operation, aborting if it takes longer than a specified time.
CommandResult runTimedCmd(long timeout, String... command)
Helper method to execute a system command, and aborting if it takes longer than a specified time.
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.
CommandResult runTimedCmdSilently(long timeout, String... command)
Helper method to execute a system command, and aborting if it takes longer than a specified time.
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.
CommandResult runTimedCmdWithInput(long timeout, String input, List<String> command)
Helper method to execute a system command that requires stdin input, and aborting if it takes longer than a specified time.
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.
boolean runTimedRetry(long opTimeout, long pollInterval, int attempts, IRunUtil.IRunnableResult runnable)
Block and executes an operation multiple times until it is successful.
void setEnvVariable(String name, String value)
Sets a environment variable to be used when running system commands.
void setWorkingDir(File dir)
Sets the working directory for system commands.
void sleep(long time)
Helper method to sleep for given time, ignoring any exceptions.
void unsetEnvVariable(String key)
Unsets an environment variable, so the system commands run without this environment variable. Environment variables may inherit from the parent process, so we need to delete the environment variable from environment()
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.android.tradefed.util.IRunUtil

Public Constructors

public RunUtil ()

Create a new RunUtil object to use.

Public Methods

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

public static IRunUtil getDefault ()

Get a reference to the default RunUtil object.

This is useful for callers who want to use IRunUtil without customization. Its recommended that callers who do need a custom IRunUtil instance (ie need to call either setEnvVariable(String, String) or setWorkingDir(File) create their own copy.

Returns
IRunUtil

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

public Process runCmdInBackground (List<String> command, OutputStream output)

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

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

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

public Process runCmdInBackground (List<String> command)

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

Parameters
command List: the List containing specified system command and optionally arguments to exec
Returns
Process the Process of the executed command
Throws
IOException

public 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

public 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

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

public 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
command String: the specified system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

public 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

public 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

public 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 ERROR(/#runTimedCmdRetry(long, 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

public CommandResult runTimedCmdWithInput (long timeout, String input, List<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 List: List containing the system command and optionally arguments to exec
Returns
CommandResult a CommandResult containing result from command run

public 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

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

public void setEnvVariable (String name, String value)

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

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

public void setWorkingDir (File dir)

Sets the working directory for system commands.

Parameters
dir File: the working directory

public 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

public void unsetEnvVariable (String key)

Unsets an environment variable, so the system commands run without this environment variable. Environment variables may inherit from the parent process, so we need to delete the environment variable from environment()

Parameters
key String: the variable name