Package com.pnfsoftware.jeb.core.units.code.android.adb

Class AdbWrapper

java.lang.Object
com.pnfsoftware.jeb.core.units.code.android.adb.AdbWrapper
public class AdbWrapper extends Object
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 or 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

  • Field Details

    • STANDARD_TIMEOUT

      public static final long STANDARD_TIMEOUT
      Standard command execution timeout is 5 seconds.
      See Also:

  • Method Details

    • initialize

      public boolean initialize()

    • getPath

      public String getPath()
      Get the path to the ADB binary wrapped by this object.
      Returns:

    • setTargetDevice

      public void setTargetDevice(String deviceSerial)
      Set the default target device for operations.
      Parameters:
      deviceSerial - the serial number (the case matters)

    • getTargetDevice

      public 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

    • setRunAs

      public void setRunAs(String path)

    • getRunAs

      public String getRunAs()

    • setToolName

      public void setToolName(String standardName, String alternateName)

    • getToolName

      public String getToolName(String name)

    • setDefaultTimeout

      public void setDefaultTimeout(long millis)

    • getDefaultTimeout

      public long getDefaultTimeout()

    • getVersion

      public String getVersion()
      Get the adb tool version used by this wrapper.
      Returns:

    • startServer

      public boolean startServer()
      Start the ADB server (on the local machine).
      Returns:

    • stopServer

      public void stopServer()
      Stop the ADB server.

    • listDevices

      public List<AdbDevice> listDevices()

    • logcat

      public InputStream logcat() throws IOException
      Execute the logcat command.
      Returns:
      the raw logcat stream data
      Throws:
      IOException - on error

    • logcat

      public InputStream logcat(Integer pid, String afterDate) throws IOException
      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

    • logcatClear

      public boolean logcatClear()

    • waitForDevice

      public boolean waitForDevice()
      adb wait-for-device command. Uses a 30 second time-out.
      Returns:

    • waitForBootCompletionHeur1

      public boolean waitForBootCompletionHeur1()
      Uses dev.bootcomplete property. Uses a 30 second time-out.

      Does not seem reliable.

      Returns:

    • waitForBootCompletionHeur2

      public boolean waitForBootCompletionHeur2()
      Uses init.svc.bootanim property. Uses a 30 second time-out.

      Does not seem reliable.

      Returns:

    • waitForBootCompletionHeur3

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

      Returns:

    • installApp

      public boolean installApp(String apkPath)

    • installAppForce

      public boolean installAppForce(String apkPath)

    • installApp

      public boolean installApp(String apkPath, boolean allowReplace, boolean onSdcard, boolean grantRuntimePermissions)
      Install an APK.
      Parameters:
      apkPath -
      allowReplace -
      onSdcard -
      grantRuntimePermissions -
      Returns:

    • uninstallApp

      public boolean uninstallApp(String packageName)

    • uninstallApp

      public boolean uninstallApp(String packageName, boolean keepData)
      Uninstall an APK.
      Parameters:
      packageName -
      keepData -
      Returns:

    • pushFile

      public boolean pushFile(String localPath, String remotePath)
      Upload a file onto a device.
      Parameters:
      localPath -
      remotePath -
      Returns:

    • pullFile

      public boolean pullFile(String remotePath, String localPath)
      Download a file from a device.
      Parameters:
      remotePath -
      localPath -
      Returns:

    • listJdwpPids

      public List<Integer> listJdwpPids()
      List the PIDs of processes hosting a JDWP transport. Use a timeout of 1 second.
      Returns:
      a list of process ids

    • forwardJdwpToTcp

      public boolean forwardJdwpToTcp(int srcJdwpPid, int dstTcpPort)

    • forwardLocalToTcp

      public boolean forwardLocalToTcp(String srcDomainSocket, int dstTcpPort)

    • forwardToTcp

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

    • stopForwardToTcp

      public boolean stopForwardToTcp(int dstTcpPort)
      Issue a adb forward --remove tcp:port command.
      Parameters:
      dstTcpPort -
      Returns:

    • stopAllForwards

      public boolean stopAllForwards(int dstTcpPort)

    • readProperty

      public String readProperty(String propertyName)
      Read a device Android property.
      Parameters:
      propertyName - property fully-qualified name
      Returns:

    • listProcesses

      public List<AdbProcess> listProcesses()
      List the processes running on this device.
      Returns:

    • listPackages

      public List<AdbPackage> listPackages()

    • listPackages

      public List<AdbPackage> listPackages(AdbPackageManagerOptions options)

    • startActivity

      public 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:
      pname -
      aname -
      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)
      Returns:

    • startActivity

      public boolean startActivity(String pname, String aname)

    • stopApp

      public boolean stopApp(String pname)

    • killProcess

      public void killProcess(String user, int pid)
      Send the TERM signal to request normal termination of a process.

    • stopProcess

      public boolean stopProcess(String user, int pid)
      Send the STOP signal to a process.

    • killProcess

      public void killProcess(String user, int pid, int signal)
      Send a signal to a process.

    • killProcess

      public boolean killProcess(String user, int pid, String... signalNames)
      Send a signal to a process.

    • hasFile

      public boolean hasFile(String user, String path)
      Verify if a file is present.
      Parameters:
      user -
      path - full exact path, no wildcard
      Returns:

    • touchFile

      public boolean touchFile(String user, String path)
      Create an empty file.
      Parameters:
      user -
      path -
      Returns:
      false indicates sure failure; true indicates potential success (not guaranteed; use #hasFile(String, String, String) to confirm)

    • deleteFile

      public boolean deleteFile(String user, String path, boolean recurse)
      Delete a file or folder.
      Parameters:
      user -
      path -
      recurse -
      Returns:

    • copyFile

      public boolean copyFile(String user, String srcPath, String dstPath, boolean recurse)
      Copy a file or folder.
      Parameters:
      user -
      srcPath -
      dstPath -
      Returns:

    • chmod

      public boolean chmod(String user, String path, int perm, boolean recurse)
      Change the permissions of a file or folder.
      Parameters:
      user -
      path -
      perm -
      recurse -
      Returns:

    • chown

      public boolean chown(String user, String path, String userName, String groupName, boolean recurse)
      Change the ownership of a file or folder.
      Parameters:
      user -
      path -
      userName - mandatory
      groupName - optional
      recurse -
      Returns:

    • which

      public String which(String user, String path)
      Find the location of a binary file.
      Parameters:
      user -
      path -
      Returns:

    • dateEpoch

      public long dateEpoch()
      Retrieve the device date in seconds since 1970-01-01 00:00:00 UTC.
      Returns:
      -1 on error, else the Unix timestamp

    • dateString

      public 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

    • shellLog

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

    • shell

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

    • shell

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

    • shell

      public AdbResult shell(List<String> arguments)

    • shell

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

    • executeOn

      public 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
      arguments -
      Returns:

    • execute

      public 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
      arguments -
      Returns:

    • executeAsync

      public ProcessWrapper executeAsync(Long timeout, Collection<String> arguments) throws IOException
      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

    • shellAsync

      public ProcessWrapper shellAsync(Long timeout, String deviceSerial, String user, List<String> arguments) throws IOException
      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

    • toString

      public String toString()
      Overrides:
      toString in class Object