one.world
Class Shell

java.lang.Object
  |
  +--one.world.Shell

public final class Shell

extends Object

Implementation of the root shell. The root shell is a relatively simple shell, which can control any environment in the local environment hierarchy.

By default, the root shell reads from and writes to the local console. However, if the "one.world.shell.pwd" system property is defined and represents a non-empty string, the root shell is accessible via telnet (and not locally). In that case, the root shell accepts a single telnet connection at a time. The port can be specified using the "one.world.shell.port" system property and defaults to the default telnet port (23). Before granting access, the root shell asks for a password, which is the string specified by the "one.world.shell.pwd" system property. Note that terminating a telnet connection does not terminate one.world; executing exit within the root shell does. Further note that if no telnet client is connected to the root shell, console output is re-directed to the local console.

The following commands are implemented by this class and available by default:

• cat to print the contents of a tuple store.
• cd to change the current environment.
• checkpoint to check-point environment(s).
• clean to delete tuples from a tuple store.
• cp to copy environment(s).
• echo to print a message.
• error to exit a script (and all calling scripts).
• exit to exit the shell.
• export to export tuples to the file system.
• gc to invoke the garbage collector.
• help to provide help.
• if for conditional execution.
• import to import data from the file system.
• info to print system information.
• load to load code into an environment.
• ls to list the environment hierarchy.
• mk to create an environment.
• mv to move or rename environment(s).
• pwd to print the current environment.
• ps to print all active threads.
• restore to restore environment(s) from a saved check-point.
• rm to destroy environment(s).
• run to activate an environment.
• set to access system properties.
• source to execute a script.
• stop to terminate an environment.
• unload to unload code from an environment.
• wait to wait for a condition.

Executing help at the shell prompt will print a list of all available commands, specifying the syntax for each command and providing a short description.

The root shell recognizes comments: all characters following a '#' until the end of the line are treated as part of the comment.

The root shell supports arguments to scripts. Tokens of the form "%<number>" are replaced with the actual script argument. The first argument has index 1. Note that substitution for the if command is conditional; the command specified for if is only substituted when it is about to be executed. For example, the "%1" in "if defined 1 echo %1" is only substituted if the corresponding script has been invoked with at least one argument.

Note that both mk and load always pass a string array as the initializer's closure. This array may be empty, but it is never null.

Also note that the root shell is not thread-safe.

Version:

$Revision: 1.56 $

See Also:

Constants.SHELL_PORT

Inner Class Summary

static interface	Shell.Command Definition of a shell command.
static class	Shell.ExitException Implementation of an exit exception.
static class	Shell.UserException Implementation of a user exception.

Field Summary

static PrintStream

console The system console.

Method Summary

void	addCommand(Shell.Command cmd) Add the specified command to this shell.
Collection	commands() Get the commands for this shell.
void	execute(String line, List subst) Execute the specified line.
void	execute(String name, List args, List subst) Execute the command with the specified name on the specified arguments.
void	flush() Flush this shell's console.
Shell.Command	getCommand(String name) Get the specified command.
Environment	getEnvironment() Get the current environment.
static String	getPath(Environment ancestor, Environment descendant) Get the path from the specified ancestor to the specified descendant.
static Shell	getRootShell() Get the root shell.
void	loop() Run the loop for this shell.
void	print() Print a new line to this shell's console.
void	print(Environment env, boolean fullPath) Print a description of the specified environment to this shell's console.
void	print(String msg) Print the specified message to this shell's console.
void	print(Throwable x) Print the specified throwable to this shell's console.
Environment	resolve(String path) Resolve the specified path.
Environment	resolve(String path, Environment env) Resolve the specified path.
void	setEnvironment(Environment env) Set the current environment.
void	source(String name) Source the specified file.
void	source(String name, List subst) Source the specified file.
static void	substitute(List args, List subst) Perform substitution on the specified list of arguments.
static String	substitute(String token, List subst) Perform substitution on the specified token.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

console

public static final PrintStream console

The system console. This stream is already open and ready to accept output data. It replaces Java's System.out and System.err streams and should be used sparringly. Applications can also use SystemUtilities.debug(String) and SystemUtilities.debug(Throwable).

Method Detail

addCommand

public void addCommand(Shell.Command cmd)

Add the specified command to this shell.

Parameters:

cmd - The command to add.

Throws:

NullPointerException - Signals that cmd is null.

IllegalArgumentException - Signals that a command with the same name already exists.

getCommand

public Shell.Command getCommand(String name)

Get the specified command.

Parameters:

name - The name of the command.

Returns:

The command or null if no such command exists.

commands

public Collection commands()

Get the commands for this shell.

Returns:

The commands for this shell.

loop

public void loop()

Run the loop for this shell.

source

public void source(String name)
            throws Throwable

Source the specified file. This method opens the file with the specified name and treats its contents as a script, to be executed line by line.

Parameters:

name - The name of the file to source.

Throws:

Throwable - Signals an exceptional condition while processing the specified script file.

source

public void source(String name,
                   List subst)
            throws Throwable

Source the specified file. This method opens the file with the specified name and treats its contents as a script, to be executed line by line.

The list of substitutions subst specifies the substitutions to be performed while executing the script.

Parameters:

name - The name of the file to source.

subst - The substitutions (to be performed).

Throws:

Throwable - Signals an exceptional condition while processing the specified script file.

execute

public void execute(String line,
                    List subst)
             throws Throwable

Execute the specified line. This method parses the specified line and applies the resulting command on the resulting arguments.

Comments (which start with '#') are stripped during parsing. Effectively empty lines are ignored.

The list of substitutions subst specifies the substitutions to be performed while executing the script.

Parameters:

line - The line to execute.

subst - The substitutions (to be performed).

Throws:

Throwable - Signals an exceptional condition while parsing the specified line or while executing the specified command.

execute

public void execute(String name,
                    List args,
                    List subst)
             throws Throwable

Execute the command with the specified name on the specified arguments. This method resolves the specified name and verifies that the command exists as well as that the specified number of arguments is a legal number for that command. It then applies the command on the specified arguments.

The list of substitutions subst specified the substitutions to be performed while executing the script. This method substitutes the command name before resolving it.

Parameters:

name - The name of the command.

args - The arguments for the command, or null if there are no arguments.

subst - The substitutions.

Throws:

Throwable - Signals an exceptional condition while executing the specified command.

getEnvironment

public Environment getEnvironment()
                           throws UnknownResourceException

Get the current environment.

Returns:

The current environment.

Throws:

UnknownResourceException - Signals that the current environment does not exist anymore, because, for example, it has been deleted or moved.

setEnvironment

public void setEnvironment(Environment env)

Set the current environment.

Parameters:

env - The new current environment.

Throws:

NullPointerException - Signals that env is null.

IllegalArgumentException - Signals that the specified environment is not a valid environment anymore (for example, because it has been deleted).

resolve

public Environment resolve(String path)
                    throws UnknownResourceException

Resolve the specified path. The specified path may be absolute, ID relative, or relative. Relative paths are resolved relative to the current environment for this shell.

Parameters:

path - The path to resolve.

Returns:

The corresponding environment.

Throws:

UnknownResourceException - Signals that the specified environment does not exist.

resolve

public Environment resolve(String path,
                           Environment env)
                    throws UnknownResourceException

Resolve the specified path. The specified path may be absolute, ID relative, or relative. Relative paths are resolved relative to the specified environment.

Parameters:

path - The path to resolve.

env - The environment for relative paths.

Returns:

The corresponding environment.

Throws:

UnknownResourceException - Signals that the specified environment does not exist.

getPath

public static String getPath(Environment ancestor,
                             Environment descendant)

Get the path from the specified ancestor to the specified descendant. If the specified ancestor is not an ancestor of the specified descendant, the returned path is relative to the root environment.

Parameters:

ancestor - The ancestor environment.

descendant - The descendant environment.

Returns:

The path between the environments, excluding the ancestor environment.

Throws:

NullPointerException - Signals that ancestor or descendant is null.

substitute

public static void substitute(List args,
                              List subst)

Perform substitution on the specified list of arguments. If any of the specified arguments starts with '%', the rest of the argument is treated as a number and the argument is replaced by the corresponding actual argument from the specified substitutions. The first substitution index is 1.

Parameters:

args - The arguments.

subst - The substitions.

Throws:

IllegalArgumentException - Signals a malformed substitution token or that no entry with the corresponding number exists in the list of substitutions.

substitute

public static String substitute(String token,
                                List subst)

Perform substitution on the specified token. If the specified token starts with '%', this method treats the rest of the token as a number and returns the corresponding entry from the specified list of substitutions. The first substitution index is 1. If the specified token does not start with '%', it is simply returned.

Parameters:

token - The token to substitute.

subst - The substitutions.

Returns:

The substituted token.

Throws:

IllegalArgumentException - Signals a malformed substitution token or that no entry with the corresponding number exists in the list of substitutions.

print

public void print()

Print a new line to this shell's console.

print

public void print(String msg)

Print the specified message to this shell's console.

Parameters:

msg - The message to print.

print

public void print(Environment env,
                  boolean fullPath)

Print a description of the specified environment to this shell's console.

Parameters:

env - The environment to print.

fullPath - Flag for whether to print the full path of the specified environment.

print

public void print(Throwable x)

Print the specified throwable to this shell's console. A description of the specified throwable is written in a new line.

Parameters:

x - The throwable to print.

flush

public void flush()

Flush this shell's console.

getRootShell

public static Shell getRootShell()

Get the root shell.

Returns:

The root shell.

Throws:

SecurityException - Signals that the caller does not have permission to access the system's console.