Package ca.cgjennings.platform
Class Shell
- java.lang.Object
-
- ca.cgjennings.platform.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-inCommandFormatter
.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-inCommandFormatter
.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-inCommandFormatter
.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.
-
-
-
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; ifnull
, 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 ofstdin
will be used as the input stream for the command.- Parameters:
commandTokens
- an array of command argumentsstdin
- the standard input stream content, ornull
- 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 ofstdin
will be used as the input stream for the command.- Parameters:
commandTokens
- an list of command argumentsstdin
- the standard input stream content, ornull
- 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 ofstdin
will be used as the input stream for the command.- Parameters:
commandTokens
- an array of command argumentsstdin
- the standard input stream content, ornull
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 ofstdin
will be used as the input stream for the command.- Parameters:
commandTokens
- an array of command argumentsstdin
- the standard input stream content, ornull
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-inCommandFormatter
.- Parameters:
command
- a command stringstdin
- the standard input stream content, ornull
- 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-inCommandFormatter
.- 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-inCommandFormatter
. The command is executed as a superuser, if possible.- Parameters:
command
- a command stringstdin
- the standard input stream content, ornull
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()
-
commandFormatter
public CommandFormatter commandFormatter()
Returns the command formatter that is used to parse commands. The command formatter is used bypexec(java.lang.String, java.lang.String)
andpsudo(java.lang.String, java.lang.String, java.lang.String)
to split whole command strings into command tokens. By modifying the formatter, you can define custom variables to use during parsing.- Returns:
- the command formatter used by this Shell
-
-