/*
 * Copyright (C) 2012-2013 Jorrit "Chainfire" Jongma
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package eu.chainfire.libsuperuser;

import java.io.DataOutputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ScheduledThreadPoolExecutor;
import java.util.concurrent.TimeUnit;

import android.os.Handler;
import android.os.Looper;

import eu.chainfire.libsuperuser.StreamGobbler.OnLineListener;

/**
 * Class providing functionality to execute commands in a (root) shell 
 */
public class Shell {    
    /**
     * <p>Runs commands using the supplied shell, and returns the output, or null in
     * case of errors.</p>
     * 
     * <p>This method is deprecated and only provided for backwards compatibility.
     * Use {@link #run(String, String[], String[], boolean)} instead, and see that
     * same method for usage notes.</p> 
     * 
     * @param shell The shell to use for executing the commands
     * @param commands The commands to execute
     * @param wantSTDERR Return STDERR in the output ? 
     * @return Output of the commands, or null in case of an error
     */
    @Deprecated
    public static List<String> run(String shell, String[] commands, boolean wantSTDERR) {
        return run(shell, commands, null, wantSTDERR);
    }

    /**
     * <p>Runs commands using the supplied shell, and returns the output, or null in
     * case of errors.</p> 
     * 
     * <p>Note that 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.</p>
     * 
     * <p>Note as well that this code will intentionally crash when run in debug mode 
     * from the main thread of the application. You should always execute shell 
     * commands from a background thread.</p>
     * 
     * <p>When in debug mode, the code will also excessively log the commands passed to
     * and the output returned from the shell.</p>
     * 
     * <p>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&lt;String&gt;, and as such doing something like <em>'ls -lR /'</em>
     * will probably have you run out of memory.</p>
     * 
     * @param shell The shell to use for executing the commands
     * @param commands The commands to execute
     * @param environment List of all environment variables (in 'key=value' format) or null for defaults
     * @param wantSTDERR Return STDERR in the output ? 
     * @return Output of the commands, or null in case of an error
     */
    public static List<String> run(String shell, String[] commands, String[] environment, boolean wantSTDERR) {
        String shellUpper = shell.toUpperCase(Locale.ENGLISH);

        if (Debug.getSanityChecksEnabledEffective() && Debug.onMainThread()) {
            // check if we're running in the main thread, and if so, crash if we're in debug mode,
            // to let the developer know attention is needed here.

            Debug.log(ShellOnMainThreadException.EXCEPTION_COMMAND);
            throw new ShellOnMainThreadException(ShellOnMainThreadException.EXCEPTION_COMMAND);
        }
        Debug.logCommand(String.format("[%s%%] START", shellUpper));

        List<String> res = Collections.synchronizedList(new ArrayList<String>());

        try {
            // Combine passed environment with system environment
            if (environment != null) {
                Map<String, String> newEnvironment = new HashMap<String, String>();
                newEnvironment.putAll(System.getenv());
                int split;
                for (String entry : environment) {
                    if ((split = entry.indexOf("=")) >= 0) {
                        newEnvironment.put(entry.substring(0, split), entry.substring(split + 1));
                    }
                }
                int i = 0;
                environment = new String[newEnvironment.size()];
                for (Map.Entry<String, String> entry : newEnvironment.entrySet()) {
                    environment[i] = entry.getKey() + "=" + entry.getValue();
                    i++;
                }
            }

            // setup our process, retrieve STDIN stream, and STDOUT/STDERR gobblers
            Process process = Runtime.getRuntime().exec(shell, environment);
            DataOutputStream STDIN = new DataOutputStream(process.getOutputStream());
            StreamGobbler STDOUT = new StreamGobbler(shellUpper + "-", process.getInputStream(), res);
            StreamGobbler STDERR = new StreamGobbler(shellUpper + "*", process.getErrorStream(), wantSTDERR ? res : null);

            // start gobbling and write our commands to the shell
            STDOUT.start();
            STDERR.start();
            for (String write : commands) {
                Debug.logCommand(String.format("[%s+] %s", shellUpper, write));
                STDIN.write((write + "\n").getBytes("UTF-8"));
                STDIN.flush();
            }
            STDIN.write("exit\n".getBytes("UTF-8"));
            STDIN.flush();

            // wait for our process to finish, while we gobble away in the background
            process.waitFor();

            // make sure our threads are done gobbling, our streams are closed, and the process is 
            // destroyed - while the latter two shouldn't be needed in theory, and may even produce 
            // warnings, in "normal" Java they are required for guaranteed cleanup of resources, so
            // lets be safe and do this on Android as well
            try { 
                STDIN.close();
            } catch (IOException e) {
            }
            STDOUT.join();
            STDERR.join();
            process.destroy();

            // in case of su, 255 usually indicates access denied
            if (SU.isSU(shell) && (process.exitValue() == 255)) {
                res = null;
            }			
        } catch (IOException e) {
            // shell probably not found
            res = null;
        } catch (InterruptedException e) {
            // this should really be re-thrown
            res = null;
        }

        Debug.logCommand(String.format("[%s%%] END", shell.toUpperCase(Locale.ENGLISH)));
        return res;
    }

    protected static String[] availableTestCommands = new String[] {
        "echo -BOC-",
        "id"
    };

    /**
     * See if the shell is alive, and if so, check the UID
     * 
     * @param ret Standard output from running availableTestCommands
     * @param checkForRoot true if we are expecting this shell to be running as root
     * @return true on success, false on error
     */
    protected static boolean parseAvailableResult(List<String> ret, boolean checkForRoot) {
        if (ret == null) return false;

        // this is only one of many ways this can be done
        boolean echo_seen = false;

        for (String line : ret) {
            if (line.contains("uid=")) {
                // id command is working, let's see if we are actually root
                return !checkForRoot || line.contains("uid=0");
            } else if (line.contains("-BOC-")) {
                // if we end up here, at least the su command starts some kind of shell,
                // let's hope it has root privileges - no way to know without additional
                // native binaries
                echo_seen = true;
            }
        }

        return echo_seen;
    }

    /**
     * This class provides utility functions to easily execute commands using SH
     */
    public static class SH {
        /**
         * Runs command and return output
         * 
         * @param command The command to run
         * @return Output of the command, or null in case of an error
         */
        public static List<String> run(String command) {
            return Shell.run("sh", new String[] { command }, null, false);
        }

        /**
         * Runs commands and return output
         * 
         * @param commands The commands to run
         * @return Output of the commands, or null in case of an error
         */
        public static List<String> run(List<String> commands) {
            return Shell.run("sh", commands.toArray(new String[commands.size()]), null, false);
        }

        /**
         * Runs commands and return output
         * 
         * @param commands The commands to run
         * @return Output of the commands, or null in case of an error
         */
        public static List<String> run(String[] commands) {
            return Shell.run("sh", commands, null, false);
        }
    }

    /**
     * This class provides utility functions to easily execute commands using SU
     * (root shell), as well as detecting whether or not root is available, and
     * if so which version.
     */
    public static class SU {
        /**
         * Runs command as root (if available) and return output
         * 
         * @param command The command to run
         * @return Output of the command, or null if root isn't available or in case of an error
         */
        public static List<String> run(String command) {
            return Shell.run("su", new String[] { command }, null, false);
        }

        /**
         * Runs commands as root (if available) and return output
         * 
         * @param commands The commands to run
         * @return Output of the commands, or null if root isn't available or in case of an error
         */
        public static List<String> run(List<String> commands) {
            return Shell.run("su", commands.toArray(new String[commands.size()]), null, false);
        }

        /**
         * Runs commands as root (if available) and return output
         * 
         * @param commands The commands to run
         * @return Output of the commands, or null if root isn't available or in case of an error
         */
        public static List<String> run(String[] commands) {
            return Shell.run("su", commands, null, false);
        }

        /**
         * Detects whether or not superuser access is available, by checking the output
         * of the "id" command if available, checking if a shell runs at all otherwise
         * 
         * @return True if superuser access available
         */
        public static boolean available() {
            // this is only one of many ways this can be done

            List<String> ret = run(Shell.availableTestCommands);
            return Shell.parseAvailableResult(ret, true);
        }

        /**
         * <p>Detects the version of the su binary installed (if any), if supported by the binary.
         * Most binaries support two different version numbers, the public version that is
         * displayed to users, and an internal version number that is used for version number 
         * comparisons. Returns null if su not available or retrieving the version isn't supported.</p>
         * 
         * <p>Note that su binary version and GUI (APK) version can be completely different.</p>
         * 
         * @param internal Request human-readable version or application internal version
         * @return String containing the su version or null
         */
        public static String version(boolean internal) {
            List<String> ret = Shell.run(
                    internal ? "su -V" : "su -v", 
                    new String[] { }, 
                    null,
                    false
            );
            if (ret == null) return null;

            for (String line : ret) {
                if (!internal) {
                    if (line.contains(".")) return line;					
                } else { 
                    try {
                        if (Integer.parseInt(line) > 0) return line;
                    } catch(NumberFormatException e) {					
                    }
                }
            }
            return null;
        }

        /**
         * Attempts to deduce if the shell command refers to a su shell
         *  
         * @param shell Shell command to run
         * @return Shell command appears to be su
         */
        public static boolean isSU(String shell) {
            // Strip parameters
            int pos = shell.indexOf(' ');
            if (pos >= 0) {
                shell = shell.substring(0, pos);
            }

            // Strip path
            pos = shell.lastIndexOf('/');
            if (pos >= 0) {
                shell = shell.substring(pos + 1);
            }

            return shell.equals("su");
        }

        /**
         * Constructs a shell command to start a su shell using the supplied
         * uid and SELinux context. This is can be an expensive operation, 
         * consider caching the result.
         * 
         * @param uid Uid to use (0 == root)
         * @param context (SELinux) context name to use or null
         * @return Shell command
         */
        public static String shell(int uid, String context) {
            // su[ --context <context>][ <uid>]
            String shell = "su";

            // First known firmware with SELinux built-in was a 4.2 (17) leak 
            if ((context != null) && (android.os.Build.VERSION.SDK_INT >= 17)) {
                Boolean enforcing = null;

                // Detect enforcing through sysfs, not always present
                if (enforcing == null) {
                    File f = new File("/sys/fs/selinux/enforce");
                    if (f.exists()) {
                        try {
                            InputStream is = new FileInputStream("/sys/fs/selinux/enforce");
                            try {
                                enforcing = (is.read() == '1');                            
                            } finally {
                                is.close();
                            }
                        } catch (Exception e) {
                        }
                    }
                }

                // 4.4+ builds are enforcing by default, take the gamble
                if (enforcing == null) {
                    enforcing = (android.os.Build.VERSION.SDK_INT >= 19);
                }

                // Switching to a context in permissive mode is not generally 
                // useful aside from audit testing, but we want to avoid
                // switching the context due to the increased chance of issues. 
                if (enforcing) {
                    String display = version(false);
                    String internal = version(true);

                    // We only know the format for SuperSU v1.90+ right now
                    if (
                            (display != null) && 
                            (internal != null) && 
                            (display.endsWith("SUPERSU")) && 
                            (Integer.valueOf(internal) >= 190)
                            ) {
                        shell = String.format(Locale.ENGLISH, "%s --context %s", shell, context);
                    }
                }
            }

            // Most su binaries support the "su <uid>" format, but in case
            // they don't, lets skip it for the default 0 (root) case
            if (uid > 0) {
                shell = String.format(Locale.ENGLISH, "%s %d", shell, uid);
            }

            return shell;
        }
    }

    /**
     * Command result callback, notifies the recipient of the completion of a command
     * block, including the (last) exit code, and the full output
     */
    public interface OnCommandResultListener {
        /**
         * <p>Command result callback</p>
         * 
         * <p>Depending on how and on which thread the shell was created, this callback
         * may be executed on one of the gobbler threads. In that case, it is important
         * the callback returns as quickly as possible, as delays in this callback may 
         * pause the native process or even result in a deadlock</p>
         * 
         * <p>See {@link Shell.Interactive} for threading details</p>
         * 
         * @param commandCode Value previously supplied to addCommand
         * @param exitCode Exit code of the last command in the block
         * @param output All output generated by the command block
         */
        public void onCommandResult(int commandCode, int exitCode, List<String> output);

        // for any onCommandResult callback
        public static final int WATCHDOG_EXIT = -1;
        public static final int SHELL_DIED = -2;

        // for Interactive.open() callbacks only
        public static final int SHELL_EXEC_FAILED = -3;
        public static final int SHELL_WRONG_UID = -4;
        public static final int SHELL_RUNNING = 0;
    }

    /**
     * Internal class to store command block properties
     */
    private static class Command {
        private static int commandCounter = 0;

        private final String[] commands;
        private final int code;
        private final OnCommandResultListener onCommandResultListener;
        private final String marker;

        public Command(String[] commands, int code, OnCommandResultListener onCommandResultListener) {
            this.commands = commands;
            this.code = code;
            this.onCommandResultListener = onCommandResultListener;
            this.marker = UUID.randomUUID().toString() + String.format("-%08x", ++commandCounter);
        }
    }

    /**
     * Builder class for {@link Shell.Interactive}
     */
    public static class Builder {
        private Handler handler = null;
        private boolean autoHandler = true;
        private String shell = "sh";
        private boolean wantSTDERR = false;
        private List<Command> commands = new LinkedList<Command>();
        private Map<String, String> environment = new HashMap<String, String>();
        private OnLineListener onSTDOUTLineListener = null;
        private OnLineListener onSTDERRLineListener = null;
        private int watchdogTimeout = 0;

        /**
         * <p>Set a custom handler that will be used to post all callbacks to</p>
         * 
         * <p>See {@link Shell.Interactive} for further details on threading and handlers</p>
         * 
         * @param handler Handler to use
         * @return This Builder object for method chaining
         */
        public Builder setHandler(Handler handler) { this.handler = handler; return this; }

        /**
         * <p>Automatically create a handler if possible ? Default to true</p>
         * 
         * <p>See {@link Shell.Interactive} for further details on threading and handlers</p>
         * 
         * @param autoHandler Auto-create handler ?
         * @return This Builder object for method chaining
         */
        public Builder setAutoHandler(boolean autoHandler) { this.autoHandler = autoHandler; return this; }

        /**
         * Set shell binary to use. Usually "sh" or "su", do not use a full path
         * unless you have a good reason to
         * 
         * @param shell Shell to use
         * @return This Builder object for method chaining
         */
        public Builder setShell(String shell) { this.shell = shell; return this; }

        /**
         * Convenience function to set "sh" as used shell
         * 
         * @return This Builder object for method chaining
         */
        public Builder useSH() { return setShell("sh"); }

        /**
         * Convenience function to set "su" as used shell
         * 
         * @return This Builder object for method chaining
         */
        public Builder useSU() { return setShell("su"); }

        /**
         * Set if error output should be appended to command block result output
         * 
         * @param wantSTDERR Want error output ?
         * @return This Builder object for method chaining
         */
        public Builder setWantSTDERR(boolean wantSTDERR) { this.wantSTDERR = wantSTDERR; return this; }

        /**
         * Add or update an environment variable
         * 
         * @param key Key of the environment variable
         * @param value Value of the environment variable
         * @return This Builder object for method chaining
         */
        public Builder addEnvironment(String key, String value) { environment.put(key, value); return this; }

        /**
         * Add or update environment variables
         * 
         * @param addEnvironment Map of environment variables
         * @return This Builder object for method chaining
         */
        public Builder addEnvironment(Map<String, String> addEnvironment) { environment.putAll(addEnvironment); return this; }

        /**
         * Add a command to execute
         * 
         * @param command Command to execute
         * @return This Builder object for method chaining
         */
        public Builder addCommand(String command) { return addCommand(command, 0, null); }

        /**
         * <p>Add a command to execute, with a callback to be called on completion</p>
         * 
         * <p>The thread on which the callback executes is dependent on various factors, see {@link Shell.Interactive} for further details</p>
         * 
         * @param command Command to execute
         * @param code User-defined value passed back to the callback
         * @param onCommandResultListener Callback to be called on completion
         * @return This Builder object for method chaining
         */
        public Builder addCommand(String command, int code, OnCommandResultListener onCommandResultListener) { return addCommand(new String[] { command }, code, onCommandResultListener); }

        /**
         * Add commands to execute
         * 
         * @param commands Commands to execute
         * @return This Builder object for method chaining
         */
        public Builder addCommand(List<String> commands) { return addCommand(commands, 0, null); }

        /**
         * <p>Add commands to execute, with a callback to be called on completion (of all commands)</p>
         * 
         * <p>The thread on which the callback executes is dependent on various factors, see {@link Shell.Interactive} for further details</p>
         * 
         * @param commands Commands to execute
         * @param code User-defined value passed back to the callback
         * @param onCommandResultListener Callback to be called on completion (of all commands)
         * @return This Builder object for method chaining
         */
        public Builder addCommand(List<String> commands, int code, OnCommandResultListener onCommandResultListener) { return addCommand(commands.toArray(new String[commands.size()]), code, onCommandResultListener); } 

        /**
         * Add commands to execute
         * 
         * @param commands Commands to execute
         * @return This Builder object for method chaining
         */
        public Builder addCommand(String[] commands) { return addCommand(commands, 0, null); }

        /**
         * <p>Add commands to execute, with a callback to be called on completion (of all commands)</p>
         * 
         * <p>The thread on which the callback executes is dependent on various factors, see {@link Shell.Interactive} for further details</p>
         * 
         * @param commands Commands to execute
         * @param code User-defined value passed back to the callback
         * @param onCommandResultListener Callback to be called on completion (of all commands)
         * @return This Builder object for method chaining
         */
        public Builder addCommand(String[] commands, int code, OnCommandResultListener onCommandResultListener) { this.commands.add(new Command(commands, code, onCommandResultListener));	return this; }

        /**
         * <p>Set a callback called for every line output to STDOUT by the shell</p>
         * 
         * <p>The thread on which the callback executes is dependent on various factors, see {@link Shell.Interactive} for further details</p>
         * 
         * @param onLineListener Callback to be called for each line
         * @return This Builder object for method chaining
         */
        public Builder setOnSTDOUTLineListener(OnLineListener onLineListener) { this.onSTDOUTLineListener = onLineListener; return this; }

        /**
         * <p>Set a callback called for every line output to STDERR by the shell</p>
         * 
         * <p>The thread on which the callback executes is dependent on various factors, see {@link Shell.Interactive} for further details</p>
         * 
         * @param onLineListener Callback to be called for each line
         * @return This Builder object for method chaining
         */
        public Builder setOnSTDERRLineListener(OnLineListener onLineListener) { this.onSTDERRLineListener = onLineListener; return this; }

        /**
         * <p>Enable command timeout callback</p>
         * 
         * <p>This will invoke the onCommandResult() callback with exitCode WATCHDOG_EXIT if a command takes longer than watchdogTimeout
         * seconds to complete.</p>
         * 
         * <p>If a watchdog timeout occurs, it generally means that the Interactive session is out of sync with the shell process.  The
         * caller should close the current session and open a new one.</p> 
         * 
         * @param watchdogTimeout Timeout, in seconds; 0 to disable
         * @return This Builder object for method chaining
         */
        public Builder setWatchdogTimeout(int watchdogTimeout) { this.watchdogTimeout = watchdogTimeout; return this; }

        /**
         * <p>Enable/disable reduced logcat output</p>
         * 
         * <p>Note that this is a global setting</p>
         * 
         * @param useMinimal true for reduced output, false for full output
         * @return This Builder object for method chaining
         */
        public Builder setMinimalLogging(boolean useMinimal) {
            Debug.setLogTypeEnabled(Debug.LOG_COMMAND | Debug.LOG_OUTPUT, !useMinimal);
            return this;
        }

        /**
         * Construct a {@link Shell.Interactive} instance, and start the shell
         */
        public Interactive open() { return new Interactive(this, null); }

        /**
         * Construct a {@link Shell.Interactive} instance, try to start the shell, and
         * call onCommandResultListener to report success or failure
         * 
         * @param onCommandResultListener Callback to return shell open status
         */
        public Interactive open(OnCommandResultListener onCommandResultListener) {
            return new Interactive(this, onCommandResultListener);
        }
    }

    /**
     * <p>An interactive shell - initially created with {@link Shell.Builder} - that 
     * executes blocks of commands you supply in the background, optionally calling
     * callbacks as each block completes.</p> 
     * 
     * <p>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.</p>
     * 
     * <p>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.</p>
     * 
     * <p>When in debug mode, the code will also excessively log the commands passed to
     * and the output returned from the shell.</p>
     * 
     * <p>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&lt;String&gt;, and as such doing something like <em>'ls -lR /'</em>
     * will probably have you run out of memory when using a 
     * {@link Shell.OnCommandResultListener}. A work-around is to not supply this callback,
     * but using (only) {@link Shell.Builder#setOnSTDOUTLineListener(OnLineListener)}. This
     * way, an internal buffer will not be created and wasting your memory.</p>
     * 
     * <h3>Callbacks, threads and handlers</h3>
     * 
     * <p>On which thread the callbacks execute is dependent on your initialization. You can 
     * supply a custom Handler using {@link Shell.Builder#setHandler(Handler)} if needed.
     * If you do not supply a custom Handler - unless you set {@link Shell.Builder#setAutoHandler(boolean)}
     * to false - a Handler will be auto-created if the thread used for instantiation
     * of the object has a Looper.</p>
     * 
     * <p>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.</p>
     * 
     * <p>The main thread must certainly have a Looper, thus if you call {@link 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.</p>
     * 
     * <p>Background threads usually do <em>not</em> have a Looper, so calling {@link 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.</p>
     */
    public static class Interactive {		
        private final Handler handler;
        private final boolean autoHandler;
        private final String shell;
        private final boolean wantSTDERR;
        private final List<Command> commands;
        private final Map<String, String> environment;
        private final OnLineListener onSTDOUTLineListener;
        private final OnLineListener onSTDERRLineListener;
        private int watchdogTimeout;

        private Process process = null;
        private DataOutputStream STDIN = null;
        private StreamGobbler STDOUT = null;
        private StreamGobbler STDERR = null;	
        private ScheduledThreadPoolExecutor watchdog = null;

        private volatile boolean running = false;
        private volatile boolean idle = true; // read/write only synchronized
        private volatile boolean closed = true;
        private volatile int callbacks = 0;
        private volatile int watchdogCount;

        private Object idleSync = new Object();
        private Object callbackSync = new Object();

        private volatile int lastExitCode = 0;
        private volatile String lastMarkerSTDOUT = null;
        private volatile String lastMarkerSTDERR = null;
        private volatile Command command = null;
        private volatile List<String> buffer = null;

        /**
         * The only way to create an instance: Shell.Builder::open()
         * 
         * @param builder Builder class to take values from
         */
        private Interactive(final Builder builder, final OnCommandResultListener onCommandResultListener) {
            autoHandler = builder.autoHandler;
            shell = builder.shell;
            wantSTDERR = builder.wantSTDERR;
            commands = builder.commands;
            environment = builder.environment;
            onSTDOUTLineListener = builder.onSTDOUTLineListener;
            onSTDERRLineListener = builder.onSTDERRLineListener;
            watchdogTimeout = builder.watchdogTimeout;

            // If a looper is available, we offload the callbacks from the gobbling threads
            // to whichever thread created us. Would normally do this in open(),
            // but then we could not declare handler as final
            if ((Looper.myLooper() != null) && (builder.handler == null) && autoHandler) {
                handler = new Handler();
            } else {
                handler = builder.handler;
            }

            boolean ret = open();
            if (onCommandResultListener == null) {
                return;
            } else if (ret == false) {
                onCommandResultListener.onCommandResult(0, OnCommandResultListener.SHELL_EXEC_FAILED, null);
                return;
            }

            // Allow up to 60 seconds for SuperSU/Superuser dialog, then enable the user-specified
            // timeout for all subsequent operations
            watchdogTimeout = 60;
            addCommand(Shell.availableTestCommands, 0, new OnCommandResultListener() {
                public void onCommandResult(int commandCode, int exitCode, List<String> output) {
                    if (exitCode == OnCommandResultListener.SHELL_RUNNING &&
                            Shell.parseAvailableResult(output, Shell.SU.isSU(shell)) != true) {
                        // shell is up, but it's brain-damaged
                        exitCode = OnCommandResultListener.SHELL_WRONG_UID;
                    }
                    watchdogTimeout = builder.watchdogTimeout;
                    onCommandResultListener.onCommandResult(0, exitCode, output);
                }
            });
        }

        @Override
        protected void finalize() throws Throwable {			
            if (!closed && Debug.getSanityChecksEnabledEffective()) {
                // waste of resources
                Debug.log(ShellNotClosedException.EXCEPTION_NOT_CLOSED);
                throw new ShellNotClosedException();												
            }
            super.finalize();
        }

        /**
         * Add a command to execute
         * 
         * @param command Command to execute
         */
        public void addCommand(String command) { addCommand(command, 0, null); }

        /**
         * <p>Add a command to execute, with a callback to be called on completion</p>
         * 
         * <p>The thread on which the callback executes is dependent on various factors, see {@link Shell.Interactive} for further details</p>
         * 
         * @param command Command to execute
         * @param code User-defined value passed back to the callback
         * @param onCommandResultListener Callback to be called on completion
         */
        public void addCommand(String command, int code, OnCommandResultListener onCommandResultListener) { addCommand(new String[] { command }, code, onCommandResultListener); }

        /**
         * Add commands to execute
         * 
         * @param commands Commands to execute
         */
        public void addCommand(List<String> commands) { addCommand(commands, 0, null); }

        /**
         * <p>Add commands to execute, with a callback to be called on completion (of all commands)</p>
         * 
         * <p>The thread on which the callback executes is dependent on various factors, see {@link Shell.Interactive} for further details</p>
         * 
         * @param commands Commands to execute
         * @param code User-defined value passed back to the callback
         * @param onCommandResultListener Callback to be called on completion (of all commands)
         */
        public void addCommand(List<String> commands, int code, OnCommandResultListener onCommandResultListener) { addCommand(commands.toArray(new String[commands.size()]), code, onCommandResultListener); } 

        /**
         * Add commands to execute
         * 
         * @param commands Commands to execute
         */
        public void addCommand(String[] commands) { addCommand(commands, 0, null); }

        /**
         * <p>Add commands to execute, with a callback to be called on completion (of all commands)</p>
         * 
         * <p>The thread on which the callback executes is dependent on various factors, see {@link Shell.Interactive} for further details</p>
         * 
         * @param commands Commands to execute
         * @param code User-defined value passed back to the callback
         * @param onCommandResultListener Callback to be called on completion (of all commands)
         */
        public synchronized void addCommand(String[] commands, int code, OnCommandResultListener onCommandResultListener) {
            this.commands.add(new Command(commands, code, onCommandResultListener));
            runNextCommand();
        }

        /**
         * Run the next command if any and if ready, signals idle state if no commands left
         */
        private void runNextCommand() {
            runNextCommand(true);			
        }

        /**
         * Called from a ScheduledThreadPoolExecutor timer thread every second when there is an outstanding command
         */
        private synchronized void handleWatchdog() {
            final int exitCode;

            if (watchdog == null) return;
            if (watchdogTimeout == 0) return;

            if (!isRunning()) {
                exitCode = OnCommandResultListener.SHELL_DIED;
                Debug.log(String.format("[%s%%] SHELL_DIED", shell.toUpperCase(Locale.ENGLISH)));
            } else if (watchdogCount++ < watchdogTimeout) {
                return;
            } else {
                exitCode = OnCommandResultListener.WATCHDOG_EXIT;
                Debug.log(String.format("[%s%%] WATCHDOG_EXIT", shell.toUpperCase(Locale.ENGLISH)));
            }

            if (handler != null) {
                postCallback(command, exitCode, buffer);
            }

            // prevent multiple callbacks for the same command
            command = null;
            buffer = null;
            idle = true;

            watchdog.shutdown();
            watchdog = null;
            kill();
        }

        /**
         * Start the periodic timer when a command is submitted
         */
        private void startWatchdog() {
            if (watchdogTimeout == 0) {
                return;
            }
            watchdogCount = 0;
            watchdog = new ScheduledThreadPoolExecutor(1);
            watchdog.scheduleAtFixedRate(new Runnable() {
                @Override
                public void run() {
                    handleWatchdog();
                }
            }, 1, 1, TimeUnit.SECONDS);
        }

        /**
         * Disable the watchdog timer upon command completion
         */
        private void stopWatchdog() {
            if (watchdog != null) {
                watchdog.shutdownNow();
                watchdog = null;
            }
        }

        /**
         * Run the next command if any and if ready
         * 
         * @param notifyIdle signals idle state if no commands left ? 
         */
        private void runNextCommand(boolean notifyIdle) {
            // must always be called from a synchronized method

            boolean running = isRunning();
            if (!running) idle = true;

            if (running && idle && (commands.size() > 0)) {
                Command command = commands.get(0);
                commands.remove(0);

                buffer = null;
                lastExitCode = 0;
                lastMarkerSTDOUT = null;
                lastMarkerSTDERR = null;				

                if (command.commands.length > 0) {
                    try {
                        if (command.onCommandResultListener != null) {
                            // no reason to store the output if we don't have an OnCommandResultListener 
                            // user should catch the output with an OnLineListener in this case
                            buffer = Collections.synchronizedList(new ArrayList<String>());							
                        }

                        idle = false;
                        this.command = command;
                        startWatchdog();
                        for (String write : command.commands) {
                            Debug.logCommand(String.format("[%s+] %s", shell.toUpperCase(Locale.ENGLISH), write));
                            STDIN.write((write + "\n").getBytes("UTF-8"));						
                        }
                        STDIN.write(("echo " + command.marker + " $?\n").getBytes("UTF-8"));
                        STDIN.write(("echo " + command.marker + " >&2\n").getBytes("UTF-8"));
                        STDIN.flush();
                    } catch (IOException e) {
                    }
                } else {
                    runNextCommand(false);
                }				
            } else if (!running) {
                // our shell died for unknown reasons - abort all submissions
                while (commands.size() > 0) {
                    postCallback(commands.remove(0), OnCommandResultListener.SHELL_DIED, null);
                }
            }

            if (idle && notifyIdle) {
                synchronized(idleSync) {
                    idleSync.notifyAll();
                }
            }
        }

        /**
         * Processes a STDOUT/STDERR line containing an end/exitCode marker
         */
        private synchronized void processMarker() {
            if (command.marker.equals(lastMarkerSTDOUT) && (command.marker.equals(lastMarkerSTDERR))) {				
                if (buffer != null) {
                    postCallback(command, lastExitCode, buffer);
                }

                stopWatchdog();
                command = null;
                buffer = null;
                idle = true;
                runNextCommand();				
            }			
        }

        /**
         * Process a normal STDOUT/STDERR line
         * 
         * @param line Line to process
         * @param listener Callback to call or null
         */
        private synchronized void processLine(String line, OnLineListener listener) {
            if (listener != null) {
                if (handler != null) {
                    final String fLine = line;
                    final OnLineListener fListener = listener;

                    startCallback();
                    handler.post(new Runnable() {								
                        @Override
                        public void run() {
                            try {
                                fListener.onLine(fLine);
                            } finally {
                                endCallback();
                            }
                        }
                    });
                } else {
                    listener.onLine(line);
                }
            }			
        }

        /**
         * Add line to internal buffer
         * 
         * @param line Line to add
         */
        private synchronized void addBuffer(String line) {
            if (buffer != null) {			
                buffer.add(line);
            }
        }

        /**
         * Increase callback counter
         */
        private void startCallback() {
            synchronized (callbackSync) {
                callbacks++;
            }
        }

        /**
         * Schedule a callback to run on the appropriate thread
         */
        private void postCallback(final Command fCommand, final int fExitCode, final List<String> fOutput) {
            if (fCommand.onCommandResultListener == null) {
                return;
            }
            if (handler == null) {
                fCommand.onCommandResultListener.onCommandResult(fCommand.code, fExitCode, fOutput);
                return;
            }
            startCallback();
            handler.post(new Runnable() {
                @Override
                public void run() {
                    try {
                        fCommand.onCommandResultListener.onCommandResult(fCommand.code, fExitCode, fOutput);
                    } finally {
                        endCallback();
                    }
                }
            });
        }

        /**
         * Decrease callback counter, signals callback complete state when dropped to 0
         */
        private void endCallback() {
            synchronized (callbackSync) {
                callbacks--;
                if (callbacks == 0) {
                    callbackSync.notifyAll();
                }
            }
        }

        /**
         * Internal call that launches the shell, starts gobbling, and starts executing commands.
         * See {@link Shell.Interactive}
         * 
         * @return Opened successfully ?
         */
        private synchronized boolean open() {
            Debug.log(String.format("[%s%%] START", shell.toUpperCase(Locale.ENGLISH)));

            try {
                // setup our process, retrieve STDIN stream, and STDOUT/STDERR gobblers
                if (environment.size() == 0) {
                    process = Runtime.getRuntime().exec(shell);
                } else {
                    Map<String, String> newEnvironment = new HashMap<String, String>();
                    newEnvironment.putAll(System.getenv());
                    newEnvironment.putAll(environment);
                    int i = 0;
                    String[] env = new String[newEnvironment.size()];
                    for (Map.Entry<String, String> entry : newEnvironment.entrySet()) {
                        env[i] = entry.getKey() + "=" + entry.getValue();
                        i++;		            
                    }
                    process = Runtime.getRuntime().exec(shell, env);
                }

                STDIN = new DataOutputStream(process.getOutputStream());
                STDOUT = new StreamGobbler(shell.toUpperCase(Locale.ENGLISH) + "-", process.getInputStream(), new OnLineListener() {					
                    @Override
                    public void onLine(String line) {
                        synchronized (Interactive.this) {
                            if (command == null) {
                                return;
                            }
                            if (line.startsWith(command.marker)) {
                                try {
                                    lastExitCode = Integer.valueOf(line.substring(command.marker.length() + 1), 10);
                                } catch (Exception e) {
                                }
                                lastMarkerSTDOUT = command.marker;
                                processMarker();
                            } else {
                                addBuffer(line);
                                processLine(line, onSTDOUTLineListener);
                            }
                        }
                    }
                });
                STDERR = new StreamGobbler(shell.toUpperCase(Locale.ENGLISH) + "*", process.getErrorStream(), new OnLineListener() {					
                    @Override
                    public void onLine(String line) {
                        synchronized (Interactive.this) {
                            if (command == null) {
                                return;
                            }
                            if (line.startsWith(command.marker)) {
                                lastMarkerSTDERR = command.marker;
                                processMarker();
                            } else {
                                if (wantSTDERR) addBuffer(line);
                                processLine(line, onSTDERRLineListener);
                            }
                        }
                    }
                });

                // start gobbling and write our commands to the shell
                STDOUT.start();
                STDERR.start();

                running = true;
                closed = false;

                runNextCommand();

                return true;
            } catch (IOException e) {
                // shell probably not found
                return false;
            }
        }

        /**
         * 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.
         */
        public void close() {
            boolean _idle = isIdle(); // idle must be checked synchronized

            synchronized (this) {
                if (!running) return;
                running = false;
                closed = true;
            }

            // This method should not be called from the main thread unless the shell is idle
            // and can be cleaned up with (minimal) waiting. Only throw in debug mode.
            if (!_idle && Debug.getSanityChecksEnabledEffective() && Debug.onMainThread()) {
                Debug.log(ShellOnMainThreadException.EXCEPTION_NOT_IDLE);
                throw new ShellOnMainThreadException(ShellOnMainThreadException.EXCEPTION_NOT_IDLE);
            }

            if (!_idle) waitForIdle();

            try {
                STDIN.write(("exit\n").getBytes("UTF-8"));
                STDIN.flush();

                // wait for our process to finish, while we gobble away in the background
                process.waitFor();

                // make sure our threads are done gobbling, our streams are closed, and the process is 
                // destroyed - while the latter two shouldn't be needed in theory, and may even produce 
                // warnings, in "normal" Java they are required for guaranteed cleanup of resources, so
                // lets be safe and do this on Android as well
                try { 
                    STDIN.close();
                } catch (IOException e) { 				
                }
                STDOUT.join();
                STDERR.join();
                stopWatchdog();
                process.destroy();
            } catch (IOException e) {
                // shell probably not found
            } catch (InterruptedException e) {
                // this should really be re-thrown
            }

            Debug.log(String.format("[%s%%] END", shell.toUpperCase(Locale.ENGLISH)));
        }

        /**
         * 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.
         */
        public synchronized void kill() {
            running = false;
            closed = true;

            try { 
                STDIN.close();
            } catch (IOException e) {
            }
            try {
                process.destroy();
            } catch (Exception e) {				
            }
        }

        /**
         * Is our shell still running ?
         * 
         * @return Shell running ?
         */
        public boolean isRunning() {
            try {
                // if this throws, we're still running
                process.exitValue();				
                return false;
            } catch (IllegalThreadStateException e) {				
            }			
            return true;
        }

        /**
         * Have all commands completed executing ?
         * 
         * @return Shell idle ?
         */
        public synchronized boolean isIdle() {
            if (!isRunning()) {
                idle = true;
                synchronized(idleSync) {
                    idleSync.notifyAll();
                }				
            }
            return idle;
        }

        /**
         * <p>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.</p>
         * 
         * <p>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.</p>
         * 
         * <p>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.</p>
         * 
         * <p>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.</p> 
         * 
         * <p>See {@link Shell.Interactive} for further details on threading and handlers</p>
         * 
         * @return True if wait complete, false if wait interrupted
         */
        public boolean waitForIdle() {
            if (Debug.getSanityChecksEnabledEffective() && Debug.onMainThread()) {
                Debug.log(ShellOnMainThreadException.EXCEPTION_WAIT_IDLE);
                throw new ShellOnMainThreadException(ShellOnMainThreadException.EXCEPTION_WAIT_IDLE);
            }

            if (isRunning()) {
                synchronized (idleSync) {
                    while (!idle) {
                        try {
                            idleSync.wait();						
                        } catch (InterruptedException e) {
                            return false;
                        }
                    }
                }

                if (
                        (handler != null) && 
                        (handler.getLooper() != null) && 
                        (handler.getLooper() != Looper.myLooper())
                        ) {
                    // If the callbacks are posted to a different thread than this one, we can wait until
                    // all callbacks have called before returning. If we don't use a Handler at all, 
                    // the callbacks are already called before we get here. If we do use a Handler but
                    // we use the same Looper, waiting here would actually block the callbacks from being
                    // called

                    synchronized (callbackSync) {
                        while (callbacks > 0) {
                            try {
                                callbackSync.wait();						
                            } catch (InterruptedException e) {
                                return false;
                            }
                        }
                    }
                }
            }

            return true;
        }

        /**
         * Are we using a Handler to post callbacks ?
         * 
         * @return Handler used ?
         */
        public boolean hasHandler() {
            return (handler != null);			
        }
    }
}
