Method Detail

• setDefaultBuilder

   static void setDefaultBuilder(Shell.Builder builder)

  Override the default Builder.

  This shell builder will be used to construct the main shell.Set this before the main shell is created anywhere in the program.

• getShell

  @NonNull() static Shell getShell()

  Get the main shell instance.

  If getCachedShell returns null, the default Builder will be used toconstruct a new {@code Shell}.

  Unless already cached, this method blocks until the main shell is created.The process could take a very long time (e.g. root permission request prompt),so be extra careful when calling this method from the main thread!

  A good practice is to "preheat" the main shell during app initialization(e.g. the splash screen) by either calling this method in a background thread orcalling getShell so subsequent calls to this functionreturns immediately.

• getShell

   static void getShell(@NonNull() Shell.GetShellCallback callback)

  Get the main shell instance asynchronously via a callback.

  If getCachedShell returns null, the default Builder will be used toconstruct a new {@code Shell} in a background thread.The cached/created shell instance is returned to the callback on the main thread.

  Parameters:

  callback - invoked when a shell is acquired.

• getShell

   static void getShell(@Nullable() Executor executor, @NonNull() Shell.GetShellCallback callback)

  Get the main shell instance asynchronously via a callback.

  If getCachedShell returns null, the default Builder will be used toconstruct a new {@code Shell} in a background thread.The cached/created shell instance is returned to the callback executed by provided executor.

  Parameters:

  executor - the executor used to handle the result callback event.

  callback - invoked when a shell is acquired.

• getCachedShell

  @Nullable() static Shell getCachedShell()

  Get the cached main shell.

• isAppGrantedRoot

  @Nullable() static Boolean isAppGrantedRoot()

  Whether the application has access to root.

  This method returns {@code null} when it is currently unable to determine whetherroot access has been granted to the application. A non-null value meant that the rootpermission grant state has been accurately determined and finalized. The applicationmust have at least 1 root shell created to have this method return {@code true}.This method will not block the calling thread; results will be returned immediately.

• cmd

  @NonNull() static Shell.Job cmd(@NonNull() Array<String> commands)

  Create a pending Job of the main shell with commands.

  This method can be treated as functionally equivalent to {@code Shell.getShell().newJob().add(commands).to(new ArrayList<>())}, but the internalimplementation is specialized for this use case and does not run this exact code.The developer can manually override output destination(s) with either to or to.

  The main shell will NOT be requested until the developer invokes either exec, enqueue, or {@code Job.submit(...)}. This makes itpossible to construct Jobs before the program has created any root shell.

• cmd

  @NonNull() static Shell.Job cmd(@NonNull() InputStream in)

  Create a pending Job of the main shell with an InputStream.

  This method can be treated as functionally equivalent to {@code Shell.getShell().newJob().add(in).to(new ArrayList<>())}, but the internalimplementation is specialized for this use case and does not run this exact code.The developer can manually override output destination(s) with either to or to.

  The main shell will NOT be requested until the developer invokes either exec, enqueue, or {@code Job.submit(...)}. This makes itpossible to construct Jobs before the program has created any root shell.

• isAlive

   abstract boolean isAlive()

  Return whether the shell is still alive.

• execTask

   abstract void execTask(@NonNull() Shell.Task task)

  Execute a low-level Task using the shell. USE THIS METHOD WITH CAUTION!

  This method exposes raw STDIN/STDOUT/STDERR directly to the developer. This is meant forimplementing low-level operations. The shell may stall if the buffer of STDOUT/STDERRis full. It is recommended to use additional threads to consume STDOUT/STDERR in parallel.

  STDOUT/STDERR is cleared before executing the task. No output from any previous tasks shouldbe left over. It is the developer's responsibility to make sure all operations are done;the shell should be in idle and waiting for further input when the task returns.

  Parameters:

  task - the desired task.

• submitTask

   abstract void submitTask(@NonNull() Shell.Task task)

  Submits a low-level Task for execution in a queue of the shell.

  Parameters:

  task - the desired task.

• newJob

  @NonNull() abstract Shell.Job newJob()

  Construct a new Job that uses the shell for execution.

  Unlike cmd and cmd, NOoutput will be collected if the developer did not set the output destination with to or to.

• getStatus

   abstract int getStatus()

  Get the status of the shell.

• isRoot

   boolean isRoot()

  Return whether the shell has root access.

• waitAndClose

   abstract boolean waitAndClose(long timeout, @NonNull() TimeUnit unit)

  Wait for any current/pending tasks to finish before closing this shelland release any system resources associated with the shell.

  Blocks until all current/pending tasks have completed execution, orthe timeout occurs, or the current thread is interrupted,whichever happens first.

  Parameters:

  timeout - the maximum time to wait

  unit - the time unit of the timeout argument

• waitAndClose

   void waitAndClose()

  Wait indefinitely for any current/pending tasks to finish before closing this shelland release any system resources associated with the shell.

• rootAccess

  @Deprecated() static boolean rootAccess()

  Whether the application has access to root.

  This method would NEVER produce false negatives, but false positives can be returned beforeactually constructing a root shell. A {@code false} returned is guaranteed to be100% accurate, while {@code true} may be returned if the device is rooted, but the userdid not grant root access to your application. However, after any root shell is constructed,this method will accurately return {@code true}.