Shell.Interactive (libsuperuser 1.0.0.201704021214 API)

java.lang.Object
- eu.chainfire.libsuperuser.Shell.Interactive

Enclosing class:

Shell
```
public static class Shell.Interactive
extends java.lang.Object
```
An interactive shell - initially created with Shell.Builder - that executes blocks of commands you supply in the background, optionally calling callbacks as each block completes.

STDERR output can be supplied as well, but due to compatibility with older Android versions, wantSTDERR is not implemented using redirectErrorStream, but rather appended to the output. STDOUT and STDERR are thus not guaranteed to be in the correct order in the output.

Note as well that the close() and waitForIdle() methods will intentionally crash when run in debug mode from the main thread of the application. Any blocking call should be run from a background thread.

When in debug mode, the code will also excessively log the commands passed to and the output returned from the shell.

Though this function uses background threads to gobble STDOUT and STDERR so a deadlock does not occur if the shell produces massive output, the output is still stored in a List<String>, and as such doing something like 'ls -lR /' will probably have you run out of memory when using a Shell.OnCommandResultListener. A work-around is to not supply this callback, but using (only) Shell.Builder#setOnSTDOUTLineListener(OnLineListener). This way, an internal buffer will not be created and wasting your memory.

Callbacks, threads and handlers

On which thread the callbacks execute is dependent on your initialization. You can supply a custom Handler using Shell.Builder.setHandler(Handler) if needed. If you do not supply a custom Handler - unless you set Shell.Builder.setAutoHandler(boolean) to false - a Handler will be auto-created if the thread used for instantiation of the object has a Looper.

If no Handler was supplied and it was also not auto-created, all callbacks will be called from either the STDOUT or STDERR gobbler threads. These are important threads that should be blocked as little as possible, as blocking them may in rare cases pause the native process or even create a deadlock.

The main thread must certainly have a Looper, thus if you call Shell.Builder.open() from the main thread, a handler will (by default) be auto-created, and all the callbacks will be called on the main thread. While this is often convenient and easy to code with, you should be aware that if your callbacks are 'expensive' to execute, this may negatively impact UI performance.

Background threads usually do not have a Looper, so calling Shell.Builder.open() from such a background thread will (by default) result in all the callbacks being executed in one of the gobbler threads. You will have to make sure the code you execute in these callbacks is thread-safe.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addCommand(java.util.List<java.lang.String> commands)` Add commands to execute
`void`	`addCommand(java.util.List<java.lang.String> commands, int code, Shell.OnCommandLineListener onCommandLineListener)` Add commands to execute, with a callback.
`void`	`addCommand(java.util.List<java.lang.String> commands, int code, Shell.OnCommandResultListener onCommandResultListener)` Add commands to execute, with a callback to be called on completion (of all commands)
`void`	`addCommand(java.lang.String command)` Add a command to execute
`void`	`addCommand(java.lang.String[] commands)` Add commands to execute
`void`	`addCommand(java.lang.String[] commands, int code, Shell.OnCommandLineListener onCommandLineListener)` Add commands to execute, with a callback.
`void`	`addCommand(java.lang.String[] commands, int code, Shell.OnCommandResultListener onCommandResultListener)` Add commands to execute, with a callback to be called on completion (of all commands)
`void`	`addCommand(java.lang.String command, int code, Shell.OnCommandLineListener onCommandLineListener)` Add a command to execute, with a callback.
`void`	`addCommand(java.lang.String command, int code, Shell.OnCommandResultListener onCommandResultListener)` Add a command to execute, with a callback to be called on completion
`void`	`close()` Close shell and clean up all resources.
`protected void`	`finalize()`
`boolean`	`hasHandler()` Are we using a Handler to post callbacks ?
`boolean`	`isIdle()` Have all commands completed executing ?
`boolean`	`isRunning()` Is our shell still running ?
`void`	`kill()` Try to clean up as much as possible from a shell that's gotten itself wedged.
`boolean`	`waitForIdle()` Wait for idle state.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable
  - addCommand
```
public void addCommand(java.lang.String command)
```
    Add a command to execute
    
    Parameters:
    
    command - Command to execute
  - addCommand
```
public void addCommand(java.lang.String command,
                       int code,
                       Shell.OnCommandResultListener onCommandResultListener)
```
    Add a command to execute, with a callback to be called on completion
    
    The thread on which the callback executes is dependent on various factors, see Shell.Interactive for further details
    
    Parameters:
    
    command - Command to execute
    
    code - User-defined value passed back to the callback
    
    onCommandResultListener - Callback to be called on completion
  - addCommand
```
public void addCommand(java.lang.String command,
                       int code,
                       Shell.OnCommandLineListener onCommandLineListener)
```
    Add a command to execute, with a callback. This callback gobbles the output line by line without buffering it and also returns the result code on completion.
    
    The thread on which the callback executes is dependent on various factors, see Shell.Interactive for further details
    
    Parameters:
    
    command - Command to execute
    
    code - User-defined value passed back to the callback
    
    onCommandLineListener - Callback
  - addCommand
```
public void addCommand(java.util.List<java.lang.String> commands)
```
    Add commands to execute
    
    Parameters:
    
    commands - Commands to execute
  - addCommand
```
public void addCommand(java.util.List<java.lang.String> commands,
                       int code,
                       Shell.OnCommandResultListener onCommandResultListener)
```
    Add commands to execute, with a callback to be called on completion (of all commands)
    
    The thread on which the callback executes is dependent on various factors, see Shell.Interactive for further details
    
    Parameters:
    
    commands - Commands to execute
    
    code - User-defined value passed back to the callback
    
    onCommandResultListener - Callback to be called on completion (of all commands)
  - addCommand
```
public void addCommand(java.util.List<java.lang.String> commands,
                       int code,
                       Shell.OnCommandLineListener onCommandLineListener)
```
    Add commands to execute, with a callback. This callback gobbles the output line by line without buffering it and also returns the result code on completion.
    
    The thread on which the callback executes is dependent on various factors, see Shell.Interactive for further details
    
    Parameters:
    
    commands - Commands to execute
    
    code - User-defined value passed back to the callback
    
    onCommandLineListener - Callback
  - addCommand
```
public void addCommand(java.lang.String[] commands)
```
    Add commands to execute
    
    Parameters:
    
    commands - Commands to execute
  - addCommand
```
public void addCommand(java.lang.String[] commands,
                       int code,
                       Shell.OnCommandResultListener onCommandResultListener)
```
    Add commands to execute, with a callback to be called on completion (of all commands)
    
    The thread on which the callback executes is dependent on various factors, see Shell.Interactive for further details
    
    Parameters:
    
    commands - Commands to execute
    
    code - User-defined value passed back to the callback
    
    onCommandResultListener - Callback to be called on completion (of all commands)
  - addCommand
```
public void addCommand(java.lang.String[] commands,
                       int code,
                       Shell.OnCommandLineListener onCommandLineListener)
```
    Add commands to execute, with a callback. This callback gobbles the output line by line without buffering it and also returns the result code on completion.
    
    The thread on which the callback executes is dependent on various factors, see Shell.Interactive for further details
    
    Parameters:
    
    commands - Commands to execute
    
    code - User-defined value passed back to the callback
    
    onCommandLineListener - Callback
  - close
```
public void close()
```
    Close shell and clean up all resources. Call this when you are done with the shell. If the shell is not idle (all commands completed) you should not call this method from the main UI thread because it may block for a long time. This method will intentionally crash your app (if in debug mode) if you try to do this anyway.
  - kill
```
public void kill()
```
    Try to clean up as much as possible from a shell that's gotten itself wedged. Hopefully the StreamGobblers will croak on their own when the other side of the pipe is closed.
  - isRunning
```
public boolean isRunning()
```
    Is our shell still running ?
    
    Returns:
    
    Shell running ?
  - isIdle
```
public boolean isIdle()
```
    Have all commands completed executing ?
    
    Returns:
    
    Shell idle ?
  - waitForIdle
```
public boolean waitForIdle()
```
    Wait for idle state. As this is a blocking call, you should not call it from the main UI thread. If you do so and debug mode is enabled, this method will intentionally crash your app.
    
    If not interrupted, this method will not return until all commands have finished executing. Note that this does not necessarily mean that all the callbacks have fired yet.
    
    If no Handler is used, all callbacks will have been executed when this method returns. If a Handler is used, and this method is called from a different thread than associated with the Handler's Looper, all callbacks will have been executed when this method returns as well. If however a Handler is used but this method is called from the same thread as associated with the Handler's Looper, there is no way to know.
    
    In practice this means that in most simple cases all callbacks will have completed when this method returns, but if you actually depend on this behavior, you should make certain this is indeed the case.
    
    See Shell.Interactive for further details on threading and handlers
    
    Returns:
    
    True if wait complete, false if wait interrupted
  - hasHandler
```
public boolean hasHandler()
```
    Are we using a Handler to post callbacks ?
    
    Returns:
    
    Handler used ?

Class Shell.Interactive

Callbacks, threads and handlers

Method Summary

Methods inherited from class java.lang.Object

Method Detail

finalize

addCommand

addCommand

addCommand

addCommand

addCommand

addCommand

addCommand

addCommand

addCommand

close

kill

isRunning

isIdle

waitForIdle

hasHandler