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() if
necessary (e.g., 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 | getToolName(String name) | ||||||||||
| 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 void | setToolName(String standardName, String alternateName) | ||||||||||
| 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.
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 getToolName (String name)
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<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 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 void setToolName (String standardName, String alternateName)
public synchronized AdbResult shell (Long timeout, String deviceSerial, String user, List<String> arguments, boolean logOnResult)
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 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.