public class

AdbWrapper

extends Object
java.lang.Object
   ↳ com.pnfsoftware.jeb.core.units.code.android.adb.AdbWrapper

Class Overview

A controller for the Android Debug Bridge (ADB) tool. Remember to call initialize() is necessary (eg, first adb run). Most methods in this class return null on error.

This class contains several helpful utility methods; if what you're looking for is not here, use #execute(long, Collection) execute or #executeOn(long, String, Collection) executeOn as a last resort. More complex and/or smarter wrapper functions can also be found in the AndroidDeviceUtil class.

This class is thread-safe; the object itself may be used in synchronized blocks for transactions.

TODO: use ProcessWrapper

Summary

Constants
long STANDARD_TIMEOUT Standard command execution timeout is 5 seconds.
Public Methods
synchronized boolean chmod(String user, String path, int perm, boolean recurse)
Change the permissions of a file or folder.
synchronized boolean chown(String user, String path, String userName, String groupName, boolean recurse)
Change the ownership of a file or folder.
synchronized boolean copyFile(String user, String srcPath, String dstPath, boolean recurse)
Copy a file or folder.
synchronized long dateEpoch()
Retrieve the device date in seconds since 1970-01-01 00:00:00 UTC.
synchronized String dateString(boolean appendTimezoneDelta)
Retrieve the device date in the following format: YYYY-mm-dd_HH:MM:SS or YYYY-mm-dd_HH:MM:SS_TZD where TZD is like "+/-HHMM"

Examples: "2016-01-16_12:32:44", 2016-01-16_12:32:44_-0500

synchronized boolean deleteFile(String user, String path, boolean recurse)
Delete a file or folder.
synchronized byte[] execute(Long timeout, Collection<String> arguments)
Execute a command using ADB.
synchronized ProcessWrapper executeAsync(Long timeout, Collection<String> arguments)
Advanced method used to execute an ADB command with as much flexibility as needed.
synchronized byte[] executeOn(Long timeout, String deviceSerial, Collection<String> arguments)
Execute a command using ADB.
synchronized boolean forwardJdwpToTcp(int srcJdwpPid, int dstTcpPort)
synchronized boolean forwardLocalToTcp(String srcDomainSocket, int dstTcpPort)
synchronized boolean forwardToTcp(AdbForwardType srcType, String srcDomainSocket, int dstTcpPort)
synchronized long getDefaultTimeout()
String getPath()
Get the path to the ADB binary wrapped by this object.
synchronized String getRunAs()
synchronized String getTargetDevice()
Get the default target device for operations.
synchronized String getVersion()
Get the adb tool version used by this wrapper.
synchronized boolean hasFile(String user, String path)
Verify if a file is present.
synchronized boolean initialize()
synchronized boolean installApp(String apkPath, boolean allowReplace, boolean onSdcard, boolean grantRuntimePermissions)
Install an APK.
synchronized boolean installApp(String apkPath)
synchronized boolean installAppForce(String apkPath)
synchronized void killProcess(String user, int pid, int signal)
Send a signal to a process.
synchronized void killProcess(String user, int pid)
Send the TERM signal to request normal termination of a process.
synchronized boolean killProcess(String user, int pid, String... signalNames)
Send a signal to a process.
synchronized List<AdbDevice> listDevices()
synchronized List<Integer> listJdwpPids()
List the PIDs of processes hosting a JDWP transport.
synchronized List<AdbPackage> listPackages()
synchronized List<AdbPackage> listPackages(AdbPackageManagerOptions options)
synchronized List<AdbProcess> listProcesses()
List the processes running on this device.
synchronized InputStream logcat()
Execute the logcat command.
synchronized InputStream logcat(Integer pid, String afterDate)
Execute the logcat command with filter options.
synchronized boolean logcatClear()
synchronized boolean pullFile(String remotePath, String localPath)
Download a file from a device.
synchronized boolean pushFile(String localPath, String remotePath)
Upload a file onto a device.
synchronized String readProperty(String propertyName)
Read a device Android property.
synchronized void setDefaultTimeout(long millis)
synchronized void setRunAs(String path)
synchronized void setTargetDevice(String deviceSerial)
Set the default target device for operations.
synchronized AdbResult shell(String user, List<String> arguments)
synchronized AdbResult shell(Long timeout, String deviceSerial, String user, List<String> arguments, boolean logOnResult)
synchronized AdbResult shell(List<String> arguments)
synchronized AdbResult shell(Long timeout, String deviceSerial, String user, List<String> arguments)
synchronized ProcessWrapper shellAsync(Long timeout, String deviceSerial, String user, List<String> arguments)
Advanced method used to execute a shell ADB command.
synchronized AdbResult shellLog(String user, List<String> arguments)
synchronized boolean startActivity(String pname, String aname)
synchronized boolean startActivity(String pname, String aname, boolean bEnableDebugging, boolean bWaitForLaunch, boolean bForceStopBeforeStart)
Start an activity.
synchronized boolean startServer()
Start the ADB server (on the local machine).
synchronized boolean stopAllForwards(int dstTcpPort)
synchronized boolean stopApp(String pname)
synchronized boolean stopForwardToTcp(int dstTcpPort)
Issue a adb forward --remove tcp:port command.
synchronized boolean stopProcess(String user, int pid)
Send the STOP signal to a process.
synchronized void stopServer()
Stop the ADB server.
synchronized String toString()
synchronized boolean touchFile(String user, String path)
Create an empty file.
synchronized boolean uninstallApp(String packageName)
synchronized boolean uninstallApp(String packageName, boolean keepData)
Uninstall an APK.
synchronized boolean waitForBootCompletionHeur1()
Uses dev.bootcomplete property.
synchronized boolean waitForBootCompletionHeur2()
Uses init.svc.bootanim property.
synchronized boolean waitForBootCompletionHeur3()
Uses the Package Manager to find out whether the system is ready for app installation.
synchronized boolean waitForDevice()
adb wait-for-device command.
synchronized String which(String user, String path)
Find the location of a binary file.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final long STANDARD_TIMEOUT

Standard command execution timeout is 5 seconds.

Constant Value: 5000 (0x0000000000001388)

Public Methods

public synchronized boolean chmod (String user, String path, int perm, boolean recurse)

Change the permissions of a file or folder.

public synchronized boolean chown (String user, String path, String userName, String groupName, boolean recurse)

Change the ownership of a file or folder.

Parameters
userName mandatory
groupName optional

public synchronized boolean copyFile (String user, String srcPath, String dstPath, boolean recurse)

Copy a file or folder.

public synchronized long dateEpoch ()

Retrieve the device date in seconds since 1970-01-01 00:00:00 UTC.

Returns
  • -1 on error, else the Unix timestamp

public synchronized String dateString (boolean appendTimezoneDelta)

Retrieve the device date in the following format: YYYY-mm-dd_HH:MM:SS or YYYY-mm-dd_HH:MM:SS_TZD where TZD is like "+/-HHMM"

Examples: "2016-01-16_12:32:44", 2016-01-16_12:32:44_-0500

Parameters
appendTimezoneDelta append time zone delta information
Returns
  • the date string

public synchronized boolean deleteFile (String user, String path, boolean recurse)

Delete a file or folder.

public synchronized byte[] execute (Long timeout, Collection<String> arguments)

Execute a command using ADB. This method may block indefinitely, for some time, or return immediately.

Parameters
timeout null to use the default timeout; else, refer to CommandExec(long) for timeout meaning

public synchronized ProcessWrapper executeAsync (Long timeout, Collection<String> arguments)

Advanced method used to execute an ADB command with as much flexibility as needed. This method is non-blocking.

Parameters
timeout timeout in ms (use -1 to specify no timeout; use null to use the default timeout)
arguments adb arguments
Returns
  • a process wrapper object; null on error
Throws
IOException on error

public synchronized byte[] executeOn (Long timeout, String deviceSerial, Collection<String> arguments)

Execute a command using ADB. Do not provide "-s ..." manually, use the appropriate argument instead.

Parameters
timeout null to use a default timeout
deviceSerial optional, leave null to let ADB decide on which device the command should be executed

public synchronized boolean forwardJdwpToTcp (int srcJdwpPid, int dstTcpPort)

public synchronized boolean forwardLocalToTcp (String srcDomainSocket, int dstTcpPort)

public synchronized boolean forwardToTcp (AdbForwardType srcType, String srcDomainSocket, int dstTcpPort)

public synchronized long getDefaultTimeout ()

public String getPath ()

Get the path to the ADB binary wrapped by this object.

public synchronized String getRunAs ()

public synchronized String getTargetDevice ()

Get the default target device for operations. The result may be null, in which case, adb will work if and only if a single device is connected (and that device will be used for operations).

Returns
  • the serial number (the case matters); may be null if no target was explicitly specified

public synchronized String getVersion ()

Get the adb tool version used by this wrapper.

public synchronized boolean hasFile (String user, String path)

Verify if a file is present.

Parameters
path full exact path, no wildcard

public synchronized boolean initialize ()

public synchronized boolean installApp (String apkPath, boolean allowReplace, boolean onSdcard, boolean grantRuntimePermissions)

Install an APK.

public synchronized boolean installApp (String apkPath)

public synchronized boolean installAppForce (String apkPath)

public synchronized void killProcess (String user, int pid, int signal)

Send a signal to a process.

public synchronized void killProcess (String user, int pid)

Send the TERM signal to request normal termination of a process.

public synchronized boolean killProcess (String user, int pid, String... signalNames)

Send a signal to a process.

public synchronized List<AdbDevice> listDevices ()

public synchronized List<Integer> listJdwpPids ()

List the PIDs of processes hosting a JDWP transport. Use a timeout of 1 second.

Returns
  • a list of process ids

public synchronized List<AdbPackage> listPackages ()

public synchronized List<AdbPackage> listPackages (AdbPackageManagerOptions options)

public synchronized List<AdbProcess> listProcesses ()

List the processes running on this device.

public synchronized InputStream logcat ()

Execute the logcat command.

Returns
  • the raw logcat stream data
Throws
IOException on error

public synchronized InputStream logcat (Integer pid, String afterDate)

Execute the logcat command with filter options.

Parameters
pid (optional) only the logs issued by the specified process
afterDate (optional) cut-off date: only logs generated after the provided date are output; format must be like YYYY-mm-dd HH:MM:SS.xxx
Returns
  • the raw logcat stream data
Throws
IOException on error

public synchronized boolean logcatClear ()

public synchronized boolean pullFile (String remotePath, String localPath)

Download a file from a device.

public synchronized boolean pushFile (String localPath, String remotePath)

Upload a file onto a device.

public synchronized String readProperty (String propertyName)

Read a device Android property.

Parameters
propertyName property fully-qualified name

public synchronized void setDefaultTimeout (long millis)

public synchronized void setRunAs (String path)

public synchronized void setTargetDevice (String deviceSerial)

Set the default target device for operations.

Parameters
deviceSerial the serial number (the case matters)

public synchronized AdbResult shell (String user, List<String> arguments)

public synchronized AdbResult shell (Long timeout, String deviceSerial, String user, List<String> arguments, boolean logOnResult)

public synchronized AdbResult shell (List<String> arguments)

public synchronized AdbResult shell (Long timeout, String deviceSerial, String user, List<String> arguments)

public synchronized ProcessWrapper shellAsync (Long timeout, String deviceSerial, String user, List<String> arguments)

Advanced method used to execute a shell ADB command. This method is non-blocking.

Parameters
timeout timeout in ms (use -1 to specify no timeout; use null to use the default timeout)
deviceSerial optional target device
user optional user
arguments adb arguments
Returns
  • a process wrapper object; null on error
Throws
IOException on error

public synchronized AdbResult shellLog (String user, List<String> arguments)

public synchronized boolean startActivity (String pname, String aname)

public synchronized boolean startActivity (String pname, String aname, boolean bEnableDebugging, boolean bWaitForLaunch, boolean bForceStopBeforeStart)

Start an activity. Uses the Activity Manager (am) internally. Example: adb shell am start -n com.xyz.appcheck/.AppCheck

Parameters
bEnableDebugging will wait for debugger to connect. If true, bForceStopBeforeStart is disregarded; also not recommended to set bWaitForLaunch to true, as am would not return until a debugger connects
bWaitForLaunch wait for activity to have launched before 'am' returns
bForceStopBeforeStart the already running activity, if there is one, will be killed (instead of simply be brought up to the front)

public synchronized boolean startServer ()

Start the ADB server (on the local machine).

public synchronized boolean stopAllForwards (int dstTcpPort)

public synchronized boolean stopApp (String pname)

public synchronized boolean stopForwardToTcp (int dstTcpPort)

Issue a adb forward --remove tcp:port command.

public synchronized boolean stopProcess (String user, int pid)

Send the STOP signal to a process.

public synchronized void stopServer ()

Stop the ADB server.

public synchronized String toString ()

public synchronized boolean touchFile (String user, String path)

Create an empty file.

Returns
  • false indicates sure failure; true indicates potential success (not guaranteed; use #hasFile(String, String, String) to confirm)

public synchronized boolean uninstallApp (String packageName)

public synchronized boolean uninstallApp (String packageName, boolean keepData)

Uninstall an APK.

public synchronized boolean waitForBootCompletionHeur1 ()

Uses dev.bootcomplete property. Uses a 30 second time-out.

Does not seem reliable.

public synchronized boolean waitForBootCompletionHeur2 ()

Uses init.svc.bootanim property. Uses a 30 second time-out.

Does not seem reliable.

public synchronized boolean waitForBootCompletionHeur3 ()

Uses the Package Manager to find out whether the system is ready for app installation. Uses a 30 second time-out.

Flaky heuristic (Jenkins only), b/c reading 'init.svc.bootanim' does not seem to do the trick on my slow emulator.

public synchronized boolean waitForDevice ()

adb wait-for-device command. Uses a 30 second time-out.

public synchronized String which (String user, String path)

Find the location of a binary file.