# Class: com.pnfsoftware.jeb.core.units.code.android.adb.AdbWrapper

A controller for the Android Debug Bridge \(ADB\) tool. Remember to call [#initialize()](#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](#execute(Long, Collection)) or [executeOn](#executeOn(Long, String, Collection)) as a last resort. More complex and/or smarter wrapper functions can also be found in the [AndroidDeviceUtil](AndroidDeviceUtil) class. 

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

 TODO: use [ProcessWrapper](ProcessWrapper)

## Static Field: STANDARD_TIMEOUT
Type: `long`

Constant value: `5000`
Description: Standard command execution timeout is 5 seconds.

## Method: chmod
- parameter: `user`, type: `java.lang.String`
- parameter: `path`, type: `java.lang.String`
- parameter: `perm`, type: `int`
- parameter: `recurse`, type: `boolean`
- return type: `boolean`

Description: Change the permissions of a file or folder.
parameter: user: optional run\-as user
parameter: path: path to modify
parameter: perm: octal permission bits
parameter: recurse: true to apply recursively
return: true on success

## Method: chown
- parameter: `user`, type: `java.lang.String`
- parameter: `path`, type: `java.lang.String`
- parameter: `userName`, type: `java.lang.String`
- parameter: `groupName`, type: `java.lang.String`
- parameter: `recurse`, type: `boolean`
- return type: `boolean`

Description: Change the ownership of a file or folder.
parameter: user: optional run\-as user
parameter: path: path to modify
parameter: userName: mandatory
parameter: groupName: optional
parameter: recurse: true to apply recursively
return: true on success

## Method: copyFile
- parameter: `user`, type: `java.lang.String`
- parameter: `srcPath`, type: `java.lang.String`
- parameter: `dstPath`, type: `java.lang.String`
- parameter: `recurse`, type: `boolean`
- return type: `boolean`

Description: Copy a file or folder.
parameter: user: optional run\-as user
parameter: srcPath: source path
parameter: dstPath: destination path
parameter: recurse: true to copy recursively
return: true on success

## Method: dateEpoch
- return type: `long`

Description: Retrieve the device date in seconds since 1970\-01\-01 00:00:00 UTC.
return: \-1 on error, else the Unix timestamp

## Method: dateString
- parameter: `appendTimezoneDelta`, type: `boolean`
- return type: `java.lang.String`

Description: 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
parameter: appendTimezoneDelta: append time zone delta information
return: the date string

## Method: deleteFile
- parameter: `user`, type: `java.lang.String`
- parameter: `path`, type: `java.lang.String`
- parameter: `recurse`, type: `boolean`
- return type: `boolean`

Description: Delete a file or folder.
parameter: user: optional run\-as user
parameter: path: path to delete
parameter: recurse: true to delete recursively
return: true on success

## Method: execute
- parameter: `timeout`, type: `java.lang.Long`
- parameter: `arguments`, type: `java.util.Collection<java.lang.String>`
- return type: `byte[]`

Description: Execute a command using ADB. This method may block indefinitely, for some time, or return immediately.
parameter: timeout: null to use the default timeout; else, refer to [ProcessExec](ProcessExec) for            timeout meaning
parameter: arguments: ADB arguments
return: command output bytes, or null on error

## Method: executeAsync
- parameter: `timeout`, type: `java.lang.Long`
- parameter: `redirectErrToOut`, type: `boolean`
- parameter: `arguments`, type: `java.util.Collection<java.lang.String>`
- return type: `com.pnfsoftware.jeb.util.concurrent.ProcessWrapper`

Description: Advanced method used to execute an ADB command with as much flexibility as needed. This method is non\-blocking.
parameter: timeout: timeout in ms \(use \-1 to specify no timeout; use null to use the default            timeout\)
parameter: redirectErrToOut: true to redirect stderr to stdout
parameter: arguments: adb arguments
return: a process wrapper object; null on error
throws: on error

## Method: executeOn
- parameter: `timeout`, type: `java.lang.Long`
- parameter: `deviceSerial`, type: `java.lang.String`
- parameter: `arguments`, type: `java.util.Collection<java.lang.String>`
- return type: `byte[]`

Description: Execute a command using ADB. Do not provide "\-s ..." manually, use the appropriate argument instead.
parameter: timeout: null to use a default timeout
parameter: deviceSerial: optional, leave null to let ADB decide on which device the command should            be executed
parameter: arguments: ADB arguments
return: command output bytes, or null on error

## Method: findProcess
- parameter: `pname`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.code.android.adb.AdbProcess`


## Method: findProcessId
- parameter: `packageName`, type: `java.lang.String`
- return type: `int`

Description: 
parameter: packageName: app name
return: the app process pid, \-1 on error

## Method: forwardJdwpToTcp
- parameter: `srcJdwpPid`, type: `int`
- parameter: `dstTcpPort`, type: `int`
- return type: `boolean`

Description: Forward a JDWP endpoint to a local TCP port.
parameter: srcJdwpPid: JDWP process id
parameter: dstTcpPort: destination TCP port
return: true on success

## Method: forwardJdwpToTcp
- parameter: `srcJdwpPid`, type: `int`
- parameter: `dstTcpPort`, type: `int`
- parameter: `forced`, type: `boolean`
- return type: `boolean`

Description: Forward a JDWP endpoint to a local TCP port.
parameter: srcJdwpPid: JDWP process id
parameter: dstTcpPort: destination TCP port
parameter: forced: if true, will attempt to stop forwarding to the provided destination port if a            forward is already in place
return: true on success

## Method: forwardLocalToTcp
- parameter: `srcDomainSocket`, type: `java.lang.String`
- parameter: `dstTcpPort`, type: `int`
- return type: `boolean`

Description: Forward a local filesystem socket to a local TCP port.
parameter: srcDomainSocket: source domain socket path
parameter: dstTcpPort: destination TCP port
return: true on success

## Method: forwardToTcp
- parameter: `srcType`, type: `com.pnfsoftware.jeb.core.units.code.android.adb.AdbForwardType`
- parameter: `srcDomainSocket`, type: `java.lang.String`
- parameter: `dstTcpPort`, type: `int`
- return type: `boolean`

Description: Forward a device endpoint to a local TCP port.
parameter: srcType: source endpoint type
parameter: srcDomainSocket: source endpoint name or path
parameter: dstTcpPort: destination TCP port
return: true on success

## Method: getDefaultTimeout
- return type: `long`

Description: Retrieve the default command timeout.
return: timeout in milliseconds; 0 means infinite

## Method: getPath
- return type: `java.lang.String`

Description: Get the path to the ADB binary wrapped by this object.
return: ADB binary path

## Method: getRunAs
- return type: `java.lang.String`

Description: Retrieve the `run-as` command path.
return: `run-as` path, or null

## Method: getTargetDevice
- return type: `java.lang.String`

Description: 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\).
return: the serial number \(the case matters\); may be null if no target was explicitly         specified

## Method: getToolName
- parameter: `name`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Retrieve the configured command name for a standard Android tool.
parameter: name: standard command name
return: configured command name

## Method: getVersion
- return type: `java.lang.String`

Description: Get the adb tool version used by this wrapper.
return: ADB version, or null on error

## Method: hasFile
- parameter: `user`, type: `java.lang.String`
- parameter: `path`, type: `java.lang.String`
- return type: `boolean`

Description: Verify if a file is present.
parameter: user: optional run\-as user
parameter: path: full exact path, no wildcard
return: true if the file exists

## Method: initialize
- return type: `boolean`

Description: Initialize the wrapper and wait for a device.
return: true if initialization succeeded

## Method: installApp
- parameter: `apkPath`, type: `java.lang.String`
- return type: `boolean`

Description: Install an APK.
parameter: apkPath: APK path
return: true on success

## Method: installApp
- parameter: `apkPath`, type: `java.lang.String`
- parameter: `allowReplace`, type: `boolean`
- parameter: `onSdcard`, type: `boolean`
- parameter: `grantRuntimePermissions`, type: `boolean`
- return type: `boolean`

Description: Install an APK.
parameter: apkPath: APK path
parameter: allowReplace: true to allow replacement
parameter: onSdcard: true to install on external storage
parameter: grantRuntimePermissions: true to grant runtime permissions on install when supported
return: true on success

## Method: installAppForce
- parameter: `apkPath`, type: `java.lang.String`
- return type: `boolean`

Description: Install or replace an APK.
parameter: apkPath: APK path
return: true on success

## Method: killProcess
- parameter: `user`, type: `java.lang.String`
- parameter: `pid`, type: `int`

Description: Send the TERM signal to request normal termination of a process.
parameter: user: optional run\-as user
parameter: pid: process id

## Method: killProcess
- parameter: `user`, type: `java.lang.String`
- parameter: `pid`, type: `int`
- parameter: `signal`, type: `int`

Description: Send a signal to a process.
parameter: user: optional run\-as user
parameter: pid: process id
parameter: signal: signal number

## Method: killProcess
- parameter: `user`, type: `java.lang.String`
- parameter: `pid`, type: `int`
- parameter: `signalNames`, type: `java.lang.String[]`
- return type: `boolean`

Description: Send a signal to a process.
parameter: user: optional run\-as user
parameter: pid: process id
parameter: signalNames: candidate signal names
return: true if one of the signals was accepted

## Method: listDevices
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.code.android.adb.AdbDevice>`

Description: List devices known to ADB.
return: device list, or null on error

## Method: listJdwpPids
- return type: `java.util.List<java.lang.Integer>`

Description: List the PIDs of processes hosting a JDWP transport. Use a timeout of 1 second.
return: a list of process ids

## Method: listPackages
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.code.android.adb.AdbPackage>`

Description: List installed packages.
return: package list, or null on error

## Method: listPackages
- parameter: `options`, type: `com.pnfsoftware.jeb.core.units.code.android.adb.AdbPackageManagerOptions`
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.code.android.adb.AdbPackage>`

Description: List installed packages.
parameter: options: package\-manager options, or null
return: package list, or null on error

## Method: listProcesses
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.code.android.adb.AdbProcess>`

Description: List the processes running on this device.
return: process list, or null on error

## Method: logcat
- return type: `com.pnfsoftware.jeb.util.concurrent.ProcessWrapper`

Description: Execute the `logcat` command.
return: the process wrapper
throws: on error

## Method: logcat
- parameter: `pid`, type: `java.lang.Integer`
- parameter: `afterDate`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.util.concurrent.ProcessWrapper`

Description: Execute the `logcat` command with filter options.
parameter: pid: \(optional\) only the logs issued by the specified process
parameter: 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`
return: the process wrapper
throws: on error

## Method: logcatClear
- return type: `boolean`

Description: Clear the device logcat buffer.
return: true on success

## Method: pullFile
- parameter: `remotePath`, type: `java.lang.String`
- parameter: `localPath`, type: `java.lang.String`
- return type: `boolean`

Description: Download a file from a device.
parameter: remotePath: device source path
parameter: localPath: local destination path
return: true on success

## Method: pushFile
- parameter: `localPath`, type: `java.lang.String`
- parameter: `remotePath`, type: `java.lang.String`
- return type: `boolean`

Description: Upload a file onto a device.
parameter: localPath: local source path
parameter: remotePath: device destination path
return: true on success

## Method: readProperty
- parameter: `propertyName`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Read a device Android property.
parameter: propertyName: property fully\-qualified name
return: property value, or null on error

## Method: setDefaultTimeout
- parameter: `millis`, type: `long`

Description: Set the default command timeout.
parameter: millis: timeout in milliseconds; 0 means infinite

## Method: setRunAs
- parameter: `path`, type: `java.lang.String`

Description: Set the `run-as` command path.
parameter: path: `run-as` path, or null to disable run\-as wrapping

## Method: setTargetDevice
- parameter: `deviceSerial`, type: `java.lang.String`

Description: Set the default target device for operations.
parameter: deviceSerial: the serial number \(the case matters\)

## Method: setToolName
- parameter: `standardName`, type: `java.lang.String`
- parameter: `alternateName`, type: `java.lang.String`

Description: Register an alternate command name for a standard Android tool.
parameter: standardName: standard command name
parameter: alternateName: alternate command name

## Method: shell
- parameter: `user`, type: `java.lang.String`
- parameter: `arguments`, type: `java.util.List<java.lang.String>`
- return type: `com.pnfsoftware.jeb.core.units.code.android.adb.AdbResult`

Description: Execute a shell command.
parameter: user: optional run\-as user
parameter: arguments: shell command arguments
return: ADB result

## Method: shell
- parameter: `timeout`, type: `java.lang.Long`
- parameter: `deviceSerial`, type: `java.lang.String`
- parameter: `user`, type: `java.lang.String`
- parameter: `arguments`, type: `java.util.List<java.lang.String>`
- return type: `com.pnfsoftware.jeb.core.units.code.android.adb.AdbResult`

Description: Execute a shell command.
parameter: timeout: optional timeout in milliseconds
parameter: deviceSerial: optional target device serial
parameter: user: optional run\-as user
parameter: arguments: shell command arguments
return: ADB result

## Method: shell
- parameter: `arguments`, type: `java.util.List<java.lang.String>`
- return type: `com.pnfsoftware.jeb.core.units.code.android.adb.AdbResult`

Description: Execute a shell command on the default target.
parameter: arguments: shell command arguments
return: ADB result

## Method: shell
- parameter: `timeout`, type: `java.lang.Long`
- parameter: `deviceSerial`, type: `java.lang.String`
- parameter: `user`, type: `java.lang.String`
- parameter: `arguments`, type: `java.util.List<java.lang.String>`
- parameter: `logOnResult`, type: `boolean`
- return type: `com.pnfsoftware.jeb.core.units.code.android.adb.AdbResult`

Description: Execute a shell command.
parameter: timeout: optional timeout in milliseconds
parameter: deviceSerial: optional target device serial
parameter: user: optional run\-as user
parameter: arguments: shell command arguments
parameter: logOnResult: true to log command output
return: ADB result

## Method: shellAsync
- parameter: `timeout`, type: `java.lang.Long`
- parameter: `deviceSerial`, type: `java.lang.String`
- parameter: `user`, type: `java.lang.String`
- parameter: `arguments`, type: `java.util.List<java.lang.String>`
- return type: `com.pnfsoftware.jeb.util.concurrent.ProcessWrapper`

Description: Advanced method used to execute a shell ADB command. This method is non\-blocking.
parameter: timeout: timeout in ms \(use \-1 to specify no timeout; use null to use the default            timeout\)
parameter: deviceSerial: optional target device
parameter: user: optional user
parameter: arguments: adb arguments
return: a process wrapper object; null on error
throws: on error

## Method: shellLog
- parameter: `user`, type: `java.lang.String`
- parameter: `arguments`, type: `java.util.List<java.lang.String>`
- return type: `com.pnfsoftware.jeb.core.units.code.android.adb.AdbResult`

Description: Execute a shell command and log its output.
parameter: user: optional run\-as user
parameter: arguments: shell command arguments
return: ADB result

## Method: startActivity
- parameter: `pname`, type: `java.lang.String`
- parameter: `aname`, type: `java.lang.String`
- parameter: `bEnableDebugging`, type: `boolean`
- parameter: `bWaitForLaunch`, type: `boolean`
- parameter: `bForceStopBeforeStart`, type: `boolean`
- return type: `boolean`

Description: Start an activity. Uses the Activity Manager \(am\) internally. Example: `adb shell am start -n com.xyz.appcheck/.AppCheck`
parameter: pname: package name
parameter: aname: activity name
parameter: 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
parameter: bWaitForLaunch: wait for activity to have launched before 'am' returns
parameter: bForceStopBeforeStart: the already running activity, if there is one, will be killed            \(instead of simply be brought up to the front\)
return: true on success

## Method: startActivity
- parameter: `pname`, type: `java.lang.String`
- parameter: `aname`, type: `java.lang.String`
- return type: `boolean`

Description: Start an activity.
parameter: pname: package name
parameter: aname: activity name
return: true on success

## Method: startServer
- return type: `boolean`

Description: Start the ADB server \(on the local machine\).
return: true on success

## Method: stopAllForwards
- parameter: `dstTcpPort`, type: `int`
- return type: `boolean`

Description: Remove all ADB forwards.
parameter: dstTcpPort: ignored
return: true on success

## Method: stopApp
- parameter: `pname`, type: `java.lang.String`
- return type: `boolean`

Description: Force\-stop an application.
parameter: pname: package name
return: true on success

## Method: stopForwardToTcp
- parameter: `dstTcpPort`, type: `int`
- return type: `boolean`

Description: Issue a `adb forward --remove tcp:port` command.
parameter: dstTcpPort: destination TCP port
return: true on success

## Method: stopProcess
- parameter: `user`, type: `java.lang.String`
- parameter: `pid`, type: `int`
- return type: `boolean`

Description: Send the STOP signal to a process.
parameter: user: optional run\-as user
parameter: pid: process id
return: true if one of the signal names was accepted

## Method: stopServer

Description: Stop the ADB server.

## Method: toString
- return type: `java.lang.String`


## Method: touchFile
- parameter: `user`, type: `java.lang.String`
- parameter: `path`, type: `java.lang.String`
- return type: `boolean`

Description: Create an empty file.
parameter: user: optional run\-as user
parameter: path: path to create
return: false indicates sure failure; true indicates potential success \(not guaranteed; use         [#hasFile(String, String)](#hasFile(String, String)) to confirm\)

## Method: uninstallApp
- parameter: `packageName`, type: `java.lang.String`
- return type: `boolean`

Description: Uninstall an APK.
parameter: packageName: package name
return: true on success

## Method: uninstallApp
- parameter: `packageName`, type: `java.lang.String`
- parameter: `keepData`, type: `boolean`
- return type: `boolean`

Description: Uninstall an APK.
parameter: packageName: package name
parameter: keepData: true to keep application data
return: true on success

## Method: waitForBootCompletionHeur1
- return type: `boolean`

Description: Uses `dev.bootcomplete` property. Uses a 30 second time\-out. 

 Does not seem reliable.
return: true if boot completion was detected

## Method: waitForBootCompletionHeur2
- return type: `boolean`

Description: Uses `init.svc.bootanim` property. Uses a 30 second time\-out. 

 Does not seem reliable.
return: true if boot completion was detected

## Method: waitForBootCompletionHeur3
- return type: `boolean`

Description: 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.
return: true if boot completion was detected

## Method: waitForDevice
- return type: `boolean`

Description: `adb wait-for-device` command. Uses a 30 second time\-out.
return: true on success

## Method: which
- parameter: `user`, type: `java.lang.String`
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Find the location of a binary file.
parameter: user: optional run\-as user
parameter: path: binary name
return: resolved path, or null on error