edu.nmu.os.shell
Class Shell

java.lang.Object
  |
  +--edu.nmu.os.shell.Shell

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

ShellImpl

public abstract class Shell

extends java.lang.Object

implements java.lang.Runnable

A command shell for the Java Virtual Machine

This is a 'main-style' Java program that allows an actor (usually the user) to run other 'main-style' Java programs. Because of its abstract nature, the Shell will not run without an implementing class to give it substance.

Since:

jdk1.4

Version:

0.1, Jan 24, 2003 8:02:22 PM

Author:

Matt Murphy

See Also:

ShellFactory, Command, CommandLine, ShellException

Field Summary

static java.lang.String	DEFAULT_PROMPT The default user prompt
static java.security.Permission	GET_ERR_PERMISSION The Permission used to check if permissions are sufficeint to get the error PrintStream of the given Shell
static java.security.Permission	GET_IN_PERMISSION The Permission used to check if permissions are sufficeint to get the InputStream of the given Shell
static java.security.Permission	GET_OUT_PERMISSION The Permission used to check if permissions are sufficeint to get the output PrintStream of the given Shell
static java.security.Permission	GET_PARENT_SHELL_PERMISSION The Permission used to check if permissions are sufficeint to get the parent of the given Shell
static java.security.Permission	SET_SECURITY_MANAGER_PERMISSION The Permission used to check if permissions are sufficeint to set the SecurityManager of the given Shell

Constructor Summary

Shell()
The default Shell constructor

Shell(Shell p)
The preffered way to construct a Shell

Method Summary

protected abstract void	doHelp() Used as an alternate run mode for the Shell
protected void	executeCommand(Command cmd) Executes the given Command
protected void	executeCommandLine(CommandLine cmdLine) Executes all Commands given by a CommandLine
protected abstract void	exitMessage(java.lang.String message) Handles an exit message to be given just before the Shell exits
protected abstract CommandLine	getCommandLine() Gets the next CommandLine to be executed
java.util.Properties	getEnv() Gets the environment of this Shell
java.lang.String	getEnv(java.lang.String key) Gets the specified environment variable
java.lang.String	getEnv(java.lang.String key, java.lang.String def) Gets the specified environment variable
protected java.util.Properties	getEnv0() Gets the environment of this Shell
protected java.lang.String	getEnv0(java.lang.String key) Gets the specified environment variable
protected java.lang.String	getEnv0(java.lang.String key, java.lang.String def) Gets the specified environment variable
java.io.PrintStream	getErr() Returns the error PrintStream of this Shell
protected abstract java.io.PrintStream	getErr0() Returns the error PrintStream of this Shell
java.io.InputStream	getIn() Returns the InputStream of this Shell
protected abstract java.io.InputStream	getIn0() Returns the InputStream of this Shell
protected abstract java.util.Properties	getInitialEnv() Returns the initial values of environment variable as they should be set if this Shell has no parent
java.io.PrintStream	getOut() Returns the output PrintStream of this Shell
protected abstract java.io.PrintStream	getOut0() Returns the output PrintStream of this Shell
Shell	getParentShell() Gets the parent Shell of this Shell
java.lang.String	getPrompt() The user prompt
java.lang.SecurityManager	getSecurityManager() Gets this Shell's SecurityManager
static Shell	getShell() Gets the currently running Shell
int	getShellLevel() Returns the depth of this Shell
abstract void	handleThrowable(java.lang.Throwable t) Handles the given Throwable
protected abstract void	handleUnresolved(java.lang.String[] programs) Handles a list of unresolved programs
boolean	isRunning() Returns whether or not this Shell is currently running
abstract boolean	isUser() Returns whether or not the user is typing commands into this Shell
static void	main(java.lang.String[] args) Runs a new Shell in the current SystemThreadGroup
void	run() Runs the Shell
void	setEnv(java.util.Properties env) Sets the environment of this Shell
java.lang.String	setEnv(java.lang.String key, java.lang.String value) Sets the specified environment variable
protected void	setEnv0(java.util.Properties env) Sets the environment of this Shell
protected java.lang.String	setEnv0(java.lang.String key, java.lang.String value) Sets the specified environment variable
void	setSecurityManager(java.lang.SecurityManager s) Sets this Shell's SecurityManager
protected void	setSecurityManager0(java.lang.SecurityManager s) Sets this Shell's SecurityManager
protected abstract boolean	shouldDoHelp() Returns true if the Shell should run the doHelp() instead of running normally

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_PROMPT

public static final java.lang.String DEFAULT_PROMPT

The default user prompt

See Also:

getPrompt(), Constant Field Values

GET_PARENT_SHELL_PERMISSION

public static final java.security.Permission GET_PARENT_SHELL_PERMISSION

The Permission used to check if permissions are sufficeint to get the parent of the given Shell

See Also:

getParentShell()

SET_SECURITY_MANAGER_PERMISSION

public static final java.security.Permission SET_SECURITY_MANAGER_PERMISSION

The Permission used to check if permissions are sufficeint to set the SecurityManager of the given Shell

See Also:

setSecurityManager(SecurityManager)

GET_IN_PERMISSION

public static final java.security.Permission GET_IN_PERMISSION

The Permission used to check if permissions are sufficeint to get the InputStream of the given Shell

See Also:

getIn()

GET_OUT_PERMISSION

public static final java.security.Permission GET_OUT_PERMISSION

The Permission used to check if permissions are sufficeint to get the output PrintStream of the given Shell

See Also:

getOut()

GET_ERR_PERMISSION

public static final java.security.Permission GET_ERR_PERMISSION

The Permission used to check if permissions are sufficeint to get the error PrintStream of the given Shell

See Also:

getErr()

Constructor Detail

Shell

public Shell()

The default Shell constructor

Constructs a new Shell with the current Shell as its parent

Shell

public Shell(Shell p)

The preffered way to construct a Shell

Constructs a new Shell with the given Shell as its parent

If p is null the environment is set to have default values equal to the values returned by getInitialEnv() and the SecurityManager is set to null. Otherwise, the parent Shell's envirnoment is used for default environment values and the SecurityManager of the parent is the default SecurityManager for this Shell.

It is important to note that if getSecurityManager() is overwritten by extending classes this constructor will not set the default SecurityManager appropriately. Likewise, if getEnv0() is ovewritten, the default environment will not be set appropriately.

Parameters:

p - the parent Shell

Method Detail

getInitialEnv

protected abstract java.util.Properties getInitialEnv()

Returns the initial values of environment variable as they should be set if this Shell has no parent

This method is called by the Shell(Shell) constructor to set the default environment variables of the Shell if its parent is null

Returns:

the environment variables

getShell

public static final Shell getShell()

Gets the currently running Shell

There can only be one Shell running in each Thread at any given time. If no Shell is running, this method returns null

Returns:

the current Shell

handleThrowable

public abstract void handleThrowable(java.lang.Throwable t)

Handles the given Throwable

This method handles the given Throwable in an implementation specific manner.

Parameters:

t - the Throwable

run

public final void run()

Runs the Shell

If there is already a Shell running in this Thread the method returns immediately. Otherwise, the following events occur:

 1) getCommandLine() is called.
 2) CommandLine.getUnresolved() is called on the resulting CommandLine.
 3a) If any programs are unresolved, handleUnresolved(String[]) is called.
 3b) Otherwise, executeCommandLine(CommandLine) is called.
 4) If the CommandLine.isExit() we end, otherwise go to 1.

If at anytime, during execution a ShellException is thrown, the Shell will stop running with an exitMessage(String).

Specified by:

run in interface java.lang.Runnable

executeCommandLine

protected void executeCommandLine(CommandLine cmdLine)

Executes all Commands given by a CommandLine

This method calls executeCommand(Command) on each of the Commands returned by CommandLine.getCommands() in the order they are given. If any Exception is thrown during this process, handleThrowable(Throwable) is called.

Parameters:

cmdLine - the CommandLine to execute

handleUnresolved

protected abstract void handleUnresolved(java.lang.String[] programs)

Handles a list of unresolved programs

This method is called when the Shell is running and the CommandLine produces unresolved programs

Parameters:

programs - the unresolved program names

getIn

public java.io.InputStream getIn()

Returns the InputStream of this Shell

If a SecurityManager is present, a permission check of GET_IN_PERMISSION is done first.

Returns:

the InputStream

Throws:

java.lang.SecurityException

getIn0

protected abstract java.io.InputStream getIn0()

Returns the InputStream of this Shell

Returns:

the InputStream

getOut

public java.io.PrintStream getOut()

Returns the output PrintStream of this Shell

If a SecurityManager is present, a permission check of GET_OUT_PERMISSION is done first.

Returns:

the output PrintStream

Throws:

java.lang.SecurityException

getOut0

protected abstract java.io.PrintStream getOut0()

Returns the output PrintStream of this Shell

Returns:

the output PrintStream

getErr

public java.io.PrintStream getErr()

Returns the error PrintStream of this Shell

If a SecurityManager is present, a permission check of GET_ERR_PERMISSION is done first.

Returns:

the error PrintStream

Throws:

java.lang.SecurityException

getErr0

protected abstract java.io.PrintStream getErr0()

Returns the error PrintStream of this Shell

Returns:

the error PrintStream

executeCommand

protected void executeCommand(Command cmd)

Executes the given Command

This method is called by executeCommandLine(CommandLine). If the command is supposed to be run in the current Thread, its Command.run() method is called. Otherwise, a new Thread is started in a new SystemThreadGroup to run the Command. In this case, this method will wait for the Thread to finish unless specified othewise by Command.fork()

Parameters:

cmd - the Command to execute

See Also:

Command.forceCurrentThread()

getCommandLine

protected abstract CommandLine getCommandLine()
                                       throws ShellException

Gets the next CommandLine to be executed

This method should never return null. If there are no CommandLines available, this method should either hang while it waits or throw a ShellException.

Returns:

the next CommandLine

Throws:

ShellException - if an error occurs

exitMessage

protected abstract void exitMessage(java.lang.String message)

Handles an exit message to be given just before the Shell exits

This method is only called during abnormal exit.

Parameters:

message - the exit message to be handled

getPrompt

public java.lang.String getPrompt()

The user prompt

The default implemention returns DEFAULT_PROMPT.

Returns:

the user prompt that should be displayed while waiting for a CommandLine to be entered

getParentShell

public final Shell getParentShell()

Gets the parent Shell of this Shell

If a SecurityManager is present, a permission check of GET_PARENT_SHELL_PERMISSION is done first.

Returns:

the parent of this Shell

Throws:

java.lang.SecurityException

isUser

public abstract boolean isUser()

Returns whether or not the user is typing commands into this Shell

Returns:

true if this Shell's actor is the user, false otherwise

getShellLevel

public final int getShellLevel()

Returns the depth of this Shell

If the Shell has no parent, it has a depth of 0.

Returns:

the Shell level

getEnv

public java.util.Properties getEnv()

Gets the environment of this Shell

If a SecurityManager is present, its checkPropertiesAccess() method is called first.

Returns:

the environment

Throws:

java.lang.SecurityException

getEnv0

protected java.util.Properties getEnv0()

Gets the environment of this Shell

If this method is overridden, the rest of the methods ending in Env0 should be overridden as well.

Returns:

the environment

setEnv

public void setEnv(java.util.Properties env)

Sets the environment of this Shell

If a SecurityManager is present, its checkPropertiesAccess() method is called first.

If env is null the environment is set to have default values of the Properties returned from getInitialEnv().

Parameters:

env - the environment

Throws:

java.lang.SecurityException

setEnv0

protected void setEnv0(java.util.Properties env)

Sets the environment of this Shell

If this method is overridden, the rest of the methods ending in Env0 should be overridden as well.

Parameters:

env - the environment

getEnv

public java.lang.String getEnv(java.lang.String key)

Gets the specified environment variable

If a SecurityManager is present, its checkPropertyAccess() method is called with the key as its parameter.

Parameters:

key - the name of the variable

Returns:

the value of the variable

Throws:

java.lang.SecurityException

java.lang.NullPointerException - if key is null

java.lang.IllegalArgumentException - if key is the empty String

getEnv0

protected java.lang.String getEnv0(java.lang.String key)

Gets the specified environment variable

If this method is overridden, the rest of the methods ending in Env0 should be overridden as well.

Parameters:

key - the name of the variable

Returns:

the value of the variable

getEnv

public java.lang.String getEnv(java.lang.String key,
                               java.lang.String def)

Gets the specified environment variable

If a SecurityManager is present, its checkPropertyAccess() method is called with the key as its parameter.

Parameters:

key - the name of the variable

def - the default value of the variable

Returns:

the value of the variable

Throws:

java.lang.SecurityException

java.lang.NullPointerException - if key is null

java.lang.IllegalArgumentException - if key is the empty String

getEnv0

protected java.lang.String getEnv0(java.lang.String key,
                                   java.lang.String def)

Gets the specified environment variable

If this method is overridden, the rest of the methods ending in Env0 should be overridden as well.

Parameters:

key - the name of the variable

def - the default value of the variable

Returns:

the value of the variable

setEnv

public java.lang.String setEnv(java.lang.String key,
                               java.lang.String value)

Sets the specified environment variable

If a SecurityManager is present, its checkPermission() method is called with a PropertyPermission(key, "write") as its argument.

Parameters:

key - the name of the variable

value - the value of the variable

Returns:

the old value of the variable

Throws:

java.lang.SecurityException

java.lang.NullPointerException - if key is null

java.lang.IllegalArgumentException - if key is the empty String

setEnv0

protected java.lang.String setEnv0(java.lang.String key,
                                   java.lang.String value)

Sets the specified environment variable

If this method is overridden, the rest of the methods ending in Env0 should be overridden as well.

Parameters:

key - the name of the variable

value - the value of the variable

Returns:

the old value of the variable

getSecurityManager

public java.lang.SecurityManager getSecurityManager()

Gets this Shell's SecurityManager

If this method is overridden, setSecurityManager0(SecurityManager) should be overridden as well.

Returns:

the SecurityManager or null if one is not present

setSecurityManager

public void setSecurityManager(java.lang.SecurityManager s)

Sets this Shell's SecurityManager

If there is already a SecurityManager present, its checkPermission() method is called with SET_SECURITY_MANAGER_PERMISSION as its argument first.

Parameters:

s - the SecurityManager

Throws:

java.lang.SecurityException

setSecurityManager0

protected void setSecurityManager0(java.lang.SecurityManager s)

Sets this Shell's SecurityManager

If this method is overridden,bgetSecurityManager() should be overridden as well.

Parameters:

s - the SecurityManager

main

public static final void main(java.lang.String[] args)

Runs a new Shell in the current SystemThreadGroup

The ShellFactory returned by ShellFactory#getFactory(String[]) is used to create the new Shell.

Parameters:

args - the args defining which ShellFactory to use

isRunning

public final boolean isRunning()

Returns whether or not this Shell is currently running

Returns:

true if the Shell is running, false otherwise

shouldDoHelp

protected abstract boolean shouldDoHelp()

Returns true if the Shell should run the doHelp() instead of running normally

This method is used by main(String[])

Returns:

true if the Shell should run the doHelp(), false if it should run normally

doHelp

protected abstract void doHelp()

Used as an alternate run mode for the Shell

It is expected that this method would print some sort of help screen to the user, though that is not the required behavior.

See Also:

shouldDoHelp()