Package com.topjohnwu.superuser

Class Shell.Builder

java.lang.Object
com.topjohnwu.superuser.Shell.Builder
Enclosing class:
Shell
public abstract static class Shell.Builder extends Object
Builder class for Shell instances.

Set the default builder for the main shell instance with Shell.setDefaultBuilder(Builder), or directly use a builder object to create new Shell instances.

Do not subclass this class! Use create() to get a new Builder object.

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • create

      @NonNull public static Shell.Builder create()
      Create a new Shell.Builder.
      Returns:
      a new Builder object.

    • setInitializers

      @SafeVarargs @NonNull public final Shell.Builder setInitializers(@NonNull Class<? extends Shell.Initializer>... classes)
      Set the desired Shell.Initializers.
      Parameters:
      classes - the classes of desired initializers.
      Returns:
      this Builder object for chaining of calls.
      See Also:

    • setFlags

      @NonNull public abstract Shell.Builder setFlags(int flags)
      Set flags to control how a new Shell will be constructed.
      Parameters:
      flags - the desired flags. Value is either 0 or bitwise-or'd value of Shell.FLAG_NON_ROOT_SHELL or Shell.FLAG_MOUNT_MASTER
      Returns:
      this Builder object for chaining of calls.

    • setTimeout

      @NonNull public abstract Shell.Builder setTimeout(long timeout)
      Set the maximum time to wait for shell verification.

      After the timeout occurs and the shell still has no response, the shell process will be force-closed and throw NoShellException.

      Parameters:
      timeout - the maximum time to wait in seconds. The default timeout is 20 seconds.
      Returns:
      this Builder object for chaining of calls.

    • setCommands

      @NonNull public abstract Shell.Builder setCommands(String... commands)
      Set the commands that will be used to create a new Shell.
      Parameters:
      commands - commands that will be passed to Runtime.exec(String[]) to create a new Process.
      Returns:
      this Builder object for chaining of calls.

    • setContext

      @NonNull public final Shell.Builder setContext(@NonNull Context context)
      Set the Context to use when creating a shell.

      The ContextImpl of the application will be obtained through the provided context, and that will be passed to Shell.Initializer.onInit(Context, Shell).

      Calling this method is not usually necessary but recommended, as the library can obtain the current application context through Android internal APIs. However, if your application uses android.R.attr#sharedUserId, or a shell/root service can be created during the application attach process, then setting a Context explicitly using this method is required.

      Parameters:
      context - a context of the current package.
      Returns:
      this Builder object for chaining of calls.

    • build

      @NonNull public abstract Shell build()
      Combine all of the options that have been set and build a new Shell instance.

      If not setCommands(String...), there are 3 methods to construct a Unix shell; if any method fails, it will fallback to the next method:

      1. If Shell.FLAG_NON_ROOT_SHELL is not set and Shell.FLAG_MOUNT_MASTER is set, construct a Unix shell by calling su --mount-master. It may fail if the root implementation does not support mount master.
      2. If Shell.FLAG_NON_ROOT_SHELL is not set, construct a Unix shell by calling su. It may fail if the device is not rooted, or root permission is not granted.
      3. Construct a Unix shell by calling sh. This would never fail in normal conditions, but should it fail, it will throw NoShellException
      The developer should check the status of the returned Shell with Shell.getStatus() since it may be constructed with calling sh.

      If setCommands(String...) is called, the provided commands will be used to create a new Process directly. If the process fails to create, or the process is not a valid shell, it will throw NoShellException.

      Returns:
      the created Shell instance.
      Throws:
      NoShellException - impossible to construct a Shell instance, or initialization failed when using the configured Shell.Initializers.

    • build

      @NonNull public final Shell build(String... commands)
      Combine all of the options that have been set and build a new Shell instance with the provided commands.
      Parameters:
      commands - commands that will be passed to Runtime.exec(String[]) to create a new Process.
      Returns:
      the built Shell instance.
      Throws:
      NoShellException - the provided command cannot create a Shell instance, or initialization failed when using the configured Shell.Initializers.

    • build

      @NonNull public abstract Shell build(Process process)
      Combine all of the options that have been set and build a new Shell instance with the provided process.
      Parameters:
      process - a shell Process that has already been created.
      Returns:
      the built Shell instance.
      Throws:
      NoShellException - the provided process is not a valid shell, or initialization failed when using the configured Shell.Initializers.