RunUtil

public class RunUtil
extends Object implements IRunUtil

java.lang.Object
↳	com.android.tradefed.util.RunUtil

---

A collection of helper methods for executing operations.

Summary

Fields
public static final String	INHERITIO_PREFIX
public static final String	RUNNABLE_NOTIFIER_NAME

Public constructors
RunUtil() Create a new RunUtil object to use.
RunUtil(boolean inheritEnvVars)

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, ErrorIdentifier errorId) Interrupts the ongoing/forthcoming run operations on the given thread.
void	interrupt(Thread thread, String message) Interrupts the ongoing/forthcoming run operations on the given thread.
boolean	isInterruptAllowed() Give the interrupt status of the RunUtil.
static void	linkFile(File destRoot, String relToRoot, File target) Links the target to a place under destRoot.
Process	runCmdInBackground(Redirect redirect, command) An alternate runCmdInBackground(String) method that accepts the command arguments in ERROR(/List) form.
Process	runCmdInBackground( command) An alternate runCmdInBackground(String) method that accepts the command arguments in ERROR(/List) form.
Process	runCmdInBackground( command, OutputStream output) Running command with a ERROR(/OutputStream) log the output of the command.
Process	runCmdInBackground(String... command) Helper method to execute a system command asynchronously.
Process	runCmdInBackground(Redirect redirect, String... command) Helper method to execute a system command asynchronously.
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.
boolean	runFixedTimedRetryWithOutputMonitor(long opTimeout, long idleOutputTimeout, 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, 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.
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	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.
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, 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.
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.
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.
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.
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.
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.
CommandResult	runTimedCmdWithOutputMonitor(long timeout, long idleOutputTimeout, OutputStream stdout, OutputStream stderr, ICacheClient cacheClient, String... command) Helper method to execute a system command with caching.
boolean	runTimedRetry(long opTimeout, long pollInterval, int attempts, IRunUtil.IRunnableResult runnable) Block and executes an operation multiple times until it is successful.
boolean	runTimedRetryWithOutputMonitor(long opTimeout, long idleOutputTimeout, long pollInterval, int attempts, IRunUtil.IRunnableResult runnable) Block and executes an operation multiple times until it is successful.
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.
void	setEnvVariable(String name, String value) Sets a environment variable to be used when running system commands.
void	setEnvVariablePriority(IRunUtil.EnvPriority priority) Decide whether or not when creating a process, unsetting environment variable is higher priority than setting them.
void	setInterruptibleInFuture(Thread thread, long timeMs) Set as interruptible after some waiting time.
void	setLinuxInterruptProcess(boolean interrupt) Allow to use linux 'kill' interruption on process running through #runTimed methods when it reaches a timeout.
void	setRedirectStderrToStdout(boolean redirect) Set the standard error stream to redirect to the standard output stream 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.
static String	toRelative(File start, String target)
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 ProcessBuilder.environment()

Fields

INHERITIO_PREFIX

public static final String INHERITIO_PREFIX

RUNNABLE_NOTIFIER_NAME

public static final String RUNNABLE_NOTIFIER_NAME

Public constructors

RunUtil

public RunUtil ()

Create a new RunUtil object to use.

RunUtil

public RunUtil (boolean inheritEnvVars)

Parameters
inheritEnvVars	boolean

Public methods

allowInterrupt

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.

getDefault

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

interrupt

public 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 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 boolean isInterruptAllowed ()

Give the interrupt status of the RunUtil.

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

linkFile

public static void linkFile (File destRoot, 
                String relToRoot, 
                File target)

Links the target to a place under destRoot.

If the target file or the symlink is already existed under the destRoot, the file won't be linked.

Parameters
destRoot	File: The root of the destination.
relToRoot	String: The relative path from the destination dir to root.
target	File: The target file to be linked.

Throws
	if the target file fails to be linked.

runCmdInBackground

public 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

runCmdInBackground

public 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

runCmdInBackground

public 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

runCmdInBackground

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

runCmdInBackground

public 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

runEscalatingTimedRetry

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

runFixedTimedRetry

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

runFixedTimedRetryWithOutputMonitor

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

setEnvVariablePriority

public 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 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 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 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 void setWorkingDir (File dir)

Sets the working directory for system commands.

Parameters
dir	File: the working directory

sleep

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

toRelative

public static String toRelative (File start, 
                String target)

Parameters
start	File
target	String

Returns
String

unsetEnvVariable

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 ProcessBuilder.environment()

Parameters
key	String: the variable name

See also:

• ProcessBuilder.environment()