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

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()

commandFormatter

public CommandFormatter commandFormatter()

Returns the command formatter that is used to parse commands. The command formatter is used by pexec(java.lang.String, java.lang.String) and psudo(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