Class Shell


  • public class Shell
    extends java.lang.Object
    A Shell executes commands as if from the command line for the purpose of automating platform-specific tasks.
    Since:
    3.0
    Author:
    Chris Jennings
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Shell.Result
      Captures the result of executing a command.
    • Constructor Summary

      Constructors 
      Constructor Description
      Shell()
      Creates a new Shell for executing commands.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      CommandFormatter commandFormatter()
      Returns the command formatter that is used to parse commands.
      java.io.File directory()
      Returns the working directory for executing commands.
      void directory​(java.io.File dir)
      Changes the working directory that will be used to execute subsequent commands.
      java.util.Map<java.lang.String,​java.lang.String> environment()
      Returns a modifiable map of the environment variables used to execute commands.
      Shell.Result exec​(java.lang.String... commandTokens)
      Executes a command.
      Shell.Result exec​(java.lang.String[] commandTokens, java.lang.String stdin)
      Executes a command.
      Shell.Result exec​(java.util.List<java.lang.String> commandTokens)
      Executes a command.
      Shell.Result exec​(java.util.List<java.lang.String> commandTokens, java.lang.String stdin)
      Executes a command.
      java.lang.String[] lastCommand()
      Returns a copy of the last command that was started, or an empty array if no commands have been executed yet.
      Shell.Result pexec​(java.lang.String command)
      Executes a command by parsing the specified string into a command name and arguments using the built-in CommandFormatter.
      Shell.Result pexec​(java.lang.String command, java.lang.String stdin)
      Executes a command by parsing the specified string into a command name and arguments using the built-in CommandFormatter.
      void popDirectory()
      Sets the directory to the most recently pushed directory, removing it from the directory stack.
      Shell.Result psudo​(java.lang.String command, java.lang.String stdin, java.lang.String password)
      Executes a command by parsing the specified string into a command name and arguments using the built-in CommandFormatter.
      void pushDirectory()
      Pushes the current directory onto a stack for later recall.
      Shell.Result sudo​(java.lang.String[] commandTokens, java.lang.String stdin, java.lang.String password)
      Executes a command as a superuser, if possible.
      Shell.Result sudo​(java.util.List<java.lang.String> commandTokens, java.lang.String stdin, java.lang.String password)
      Executes a command as a superuser, if possible.
      int timeout()
      Returns the current timeout value.
      void timeout​(int timeout)
      Sets a timeout for executing commands, in milliseconds.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Shell

        public Shell()
        Creates a new Shell for executing commands.
    • Method Detail

      • directory

        public java.io.File directory()
        Returns the working directory for executing commands.
        Returns:
        the working directory
      • directory

        public void directory​(java.io.File dir)
        Changes the working directory that will be used to execute subsequent commands.
        Parameters:
        dir - the directory; if null, use the working directory of the parent process
      • pushDirectory

        public void pushDirectory()
        Pushes the current directory onto a stack for later recall.
      • popDirectory

        public void popDirectory()
        Sets the directory to the most recently pushed directory, removing it from the directory stack.
        Throws:
        java.util.NoSuchElementException - if the directory stack is empty
      • environment

        public java.util.Map<java.lang.String,​java.lang.String> environment()
        Returns a modifiable map of the environment variables used to execute commands.
        Returns:
        the shell's environment variables
      • timeout

        public int timeout()
        Returns the current timeout value.
        Returns:
        returns the maximum time, in milliseconds, that a command can execute, or 0 if timeouts are disabled
      • timeout

        public void timeout​(int timeout)
        Sets a timeout for executing commands, in milliseconds. Any command that does not complete within the timeout will be forcibly terminated. Setting the timeout to 0 will disable timeouts.
        Parameters:
        timeout - the timeout value, in milliseconds, or 0 for no timeout
      • lastCommand

        public java.lang.String[] lastCommand()
        Returns a copy of the last command that was started, or an empty array if no commands have been executed yet.
        Returns:
        the last executed command
      • exec

        public Shell.Result exec​(java.lang.String[] commandTokens,
                                 java.lang.String stdin)
                          throws java.io.IOException
        Executes a command. If non-null, the contents of stdin will be used as the input stream for the command.
        Parameters:
        commandTokens - an array of command arguments
        stdin - the standard input stream content, or null
        Returns:
        the outcome of the command, or null if a timeout is set and the command timed out
        Throws:
        java.io.IOException - if an I/O error occurs; typically this occurs if the command is not found
      • exec

        public Shell.Result exec​(java.util.List<java.lang.String> commandTokens,
                                 java.lang.String stdin)
                          throws java.io.IOException
        Executes a command. If non-null, the contents of stdin will be used as the input stream for the command.
        Parameters:
        commandTokens - an list of command arguments
        stdin - the standard input stream content, or null
        Returns:
        the outcome of the command, or null if a timeout is set and the command timed out
        Throws:
        java.io.IOException - if an I/O error occurs; typically this occurs if the command is not found
      • exec

        public Shell.Result exec​(java.util.List<java.lang.String> commandTokens)
                          throws java.io.IOException
        Executes a command.
        Parameters:
        commandTokens - an list of command arguments
        Returns:
        the outcome of the command, or null if a timeout is set and the command timed out
        Throws:
        java.io.IOException - if an I/O error occurs; typically this occurs if the command is not found
      • sudo

        public Shell.Result sudo​(java.lang.String[] commandTokens,
                                 java.lang.String stdin,
                                 java.lang.String password)
                          throws java.io.IOException
        Executes a command as a superuser, if possible. If non-null, the contents of stdin will be used as the input stream for the command.
        Parameters:
        commandTokens - an array of command arguments
        stdin - the standard input stream content, or null
        password - the superuser account password
        Returns:
        the outcome of the command, or null if a timeout is set and the command timed out
        Throws:
        java.io.IOException - if an I/O error occurs; typically this occurs if the command is not found
      • sudo

        public Shell.Result sudo​(java.util.List<java.lang.String> commandTokens,
                                 java.lang.String stdin,
                                 java.lang.String password)
                          throws java.io.IOException
        Executes a command as a superuser, if possible. If non-null, the contents of stdin will be used as the input stream for the command.
        Parameters:
        commandTokens - an array of command arguments
        stdin - the standard input stream content, or null
        password - the superuser account password
        Returns:
        the outcome of the command, or null if a timeout is set and the command timed out
        Throws:
        java.io.IOException - if an I/O error occurs; typically this occurs if the command is not found
      • exec

        public Shell.Result exec​(java.lang.String... commandTokens)
                          throws java.io.IOException
        Executes a command.
        Parameters:
        commandTokens - an array of command arguments
        Returns:
        the outcome of the command, or null if a timeout is set and the command timed out
        Throws:
        java.io.IOException - if an I/O error occurs; typically this occurs if the command is not found
      • pexec

        public Shell.Result pexec​(java.lang.String command,
                                  java.lang.String stdin)
                           throws java.io.IOException
        Executes a command by parsing the specified string into a command name and arguments using the built-in CommandFormatter.
        Parameters:
        command - a command string
        stdin - the standard input stream content, or null
        Returns:
        the outcome of the command, or null if a timeout is set and the command timed out
        Throws:
        java.io.IOException - if an I/O error occurs; typically this occurs if the command is not found
        See Also:
        commandFormatter()
      • pexec

        public Shell.Result pexec​(java.lang.String command)
                           throws java.io.IOException
        Executes a command by parsing the specified string into a command name and arguments using the built-in CommandFormatter.
        Parameters:
        command - a command string
        Returns:
        the outcome of the command, or null if a timeout is set and the command timed out
        Throws:
        java.io.IOException - if an I/O error occurs; typically this occurs if the command is not found
        See Also:
        commandFormatter()
      • psudo

        public Shell.Result psudo​(java.lang.String command,
                                  java.lang.String stdin,
                                  java.lang.String password)
                           throws java.io.IOException
        Executes a command by parsing the specified string into a command name and arguments using the built-in CommandFormatter. The command is executed as a superuser, if possible.
        Parameters:
        command - a command string
        stdin - the standard input stream content, or null
        password - the superuser account password
        Returns:
        the outcome of the command, or null if a timeout is set and the command timed out
        Throws:
        java.io.IOException - if an I/O error occurs; typically this occurs if the command is not found
        See Also:
        commandFormatter()