com.maverick.ssh
Class Shell

java.lang.Object
  com.maverick.ssh.Shell

All Implemented Interfaces:

Client

public class Shell

extends java.lang.Object

implements Client

This class provides an enhanced user shell that enables the user to trap the output of single commands in a ShellProcess.

The basic process of setting up a shell is as follows:

 // Create SshClient instance and authenticate
 ..

 // Create a Shell instance
 Shell shell = new Shell(ssh);
 shell.createSession();
 

If the createSession method fails to determine the remote operating system an exception will be thrown. You can manually set the required fields using the setter methods of this class before calling createSession. This is an example of the settings required to configure a Windows shell.

 Shell shell = new Shell(ssh2);
 // First turn off failing on unknown os type, by default the Shell will
 // throw an exception if the operating system is unknown.
 shell.setFailOnUknownOS(false);

 // Now set the command that sets the prompt on Windows
 shell.setPromptCommand("PROMPT=foo#");

 // Tell the Shell what the actual prompt will be
 shell.setPrompt("foo#");

 // Finally make sure that Windows EOL is used
 shell.setEOL("\r\n");

 // This now executes without hanging.
 shell.createSession();
 

Author:

Lee David Painter

Constructor Summary

Shell(SshClient ssh)

Method Summary

void	carriageReturn() Send a carriage return to the remote shell.
void	createSession() Construct a new scripted session ready for command execution.
void	createSession(java.lang.String term, int cols, int rows) Construct a new scripted session ready for command execution.
ShellProcess	execute(java.lang.String cmd) Execute a command within the shell.
void	exit() Exit the session.
ShellEnvironment	getEnvironment() Get the remote shell's environment.
ShellProcess	getSessionInitProcess()
void	initializePrompt()
void	initializeSession(java.lang.String term, int cols, int rows)
boolean	isAllocatePseudoTerminal()
boolean	isClosed()
void	setAllocatePseudoTerminal(boolean allocatePseudoTerminal)
static void	setDefaultEOL(java.lang.String defaultEOL) Set the default EOL string for unknown operating systems.
void	setEnvironment(ShellEnvironment env)
void	setEOL(java.lang.String eol) Tell the Shell what EOL to use when sending user input to the server.
void	setExitCommand(java.lang.String exitCommand) Tell the Shell what the exit command of the shell is.
void	setFailOnUknownOS(boolean failOnUnknownOS) If the ShellEnvironment class cannot determine the remote shell it defaults to a UNIX type shell.
void	setPrompt(java.lang.String actualPrompt) Tell the Shell what the remote prompt will be.
void	setPromptCommand(java.lang.String promptCommand) Tell the Shell what the command is to set the prompt on the remote shell.
void	setPromptTimeoutPeriod(int waitForPromptTimeoutPeriod) Set the wait for prompt timeout period.
void	setShellInitTimePeriod(int shellInitTimePeriod) Set the shell initialization time period.
void	type(int b) Write a byte of data as input on the remote shell.
void	type(java.lang.String string) Type some characters as input on the remote shell.
void	write(byte[] bytes) Write some data as input on the remote shell.

Methods inherited from class java.lang.Object

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

Constructor Detail

Shell

public Shell(SshClient ssh)

Method Detail

getSessionInitProcess

public ShellProcess getSessionInitProcess()

setEOL

public void setEOL(java.lang.String eol)

Tell the Shell what EOL to use when sending user input to the server. This overrides any setting detected by the ShellEnvironment.

Parameters:

eol - String

setPrompt

public void setPrompt(java.lang.String actualPrompt)

Tell the Shell what the remote prompt will be. This setting MUST be used in conjunction with setPromptCommand and setEOL commands. If the Shell cannot determine the operating system in use then you need to manually configure these methods. This is an example of the settings required to configure a Windows shell.

 Shell shell = new Shell(ssh2);
 // First turn off failing on unknown os type, by default the Shell will
 // throw an exception if the operating system is unknown.
 shell.setFailOnUknownOS(false);

 // Now set the command that sets the prompt on Windows
 shell.setPromptCommand("PROMPT=foo#");

 // Tell the Shell what the actual prompt will be
 shell.setPrompt("foo#");

 // Finally make sure that Windows EOL is used
 shell.setEOL("\r\n");

 // This now executes without hanging.
 shell.createSession();
 

Parameters:

actualPrompt - String

setExitCommand

public void setExitCommand(java.lang.String exitCommand)

Tell the Shell what the exit command of the shell is. This defaults to "exit"

Parameters:

exitCommand - String

setShellInitTimePeriod

public void setShellInitTimePeriod(int shellInitTimePeriod)

Set the shell initialization time period. The API will wait for this time period before sending any commands to the shell, this is to allow the shell to initilaize and get ready to accept commands. You may need to change this if your shell does not respond to your commands.

Parameters:

shellInitTimePeriod - int milliseconds to wait before sending any commands

setPromptTimeoutPeriod

public void setPromptTimeoutPeriod(int waitForPromptTimeoutPeriod)

Set the wait for prompt timeout period. If the prompt is not received during this period then the API will throw an exception and close the session.

Parameters:

waitForPromptTimeoutPeriod - int

setFailOnUknownOS

public void setFailOnUknownOS(boolean failOnUnknownOS)

If the ShellEnvironment class cannot determine the remote shell it defaults to a UNIX type shell. This default can be overriden with the various methods of this class prior to creating the session. Use this method to tell the Shell not to throw an exception if the remote OS is unknown.

Parameters:

failOnUnknownOS - boolean

setPromptCommand

public void setPromptCommand(java.lang.String promptCommand)

Tell the Shell what the command is to set the prompt on the remote shell.

Parameters:

promptCommand - String

createSession

public void createSession()
                   throws SshException,
                          ChannelOpenException,
                          ShellTimeoutException

Construct a new scripted session ready for command execution.

Throws:

SshException

ChannelOpenException

ShellTimeoutException

initializeSession

public void initializeSession(java.lang.String term,
                              int cols,
                              int rows)
                       throws SshException,
                              ChannelOpenException,
                              ShellTimeoutException

Parameters:

term -

cols -

rows -

Throws:

SshException

ChannelOpenException

ShellTimeoutException

createSession

public void createSession(java.lang.String term,
                          int cols,
                          int rows)
                   throws SshException,
                          ChannelOpenException,
                          ShellTimeoutException

Construct a new scripted session ready for command execution.

Parameters:

term - String

cols - int

rows - int

Throws:

SshException

ChannelOpenException

ShellTimeoutException

initializePrompt

public void initializePrompt()
                      throws SshException,
                             ChannelOpenException,
                             ShellTimeoutException

Throws:

SshException

ChannelOpenException

ShellTimeoutException

isClosed

public boolean isClosed()

execute

public ShellProcess execute(java.lang.String cmd)
                     throws java.io.IOException,
                            ShellTimeoutException

Execute a command within the shell. This method will wait for the shell prompt then execute and return a single ShellProcess object.

Parameters:

cmd - String

Returns:

ShellProcess

Throws:

java.io.IOException

ShellTimeoutException

exit

public void exit()
          throws ShellTimeoutException,
                 java.io.IOException

Exit the session.

This method executes the "exit" command and waits for the session to close before returning.

Specified by:

exit in interface Client

Throws:

java.io.IOException

ShellTimeoutException

type

public void type(java.lang.String string)
          throws java.io.IOException

Type some characters as input on the remote shell.

Parameters:

string - String

Throws:

java.io.IOException

write

public void write(byte[] bytes)
           throws java.io.IOException

Write some data as input on the remote shell.

Parameters:

bytes -

Throws:

java.io.IOException

type

public void type(int b)
          throws java.io.IOException

Write a byte of data as input on the remote shell.

Parameters:

b -

Throws:

java.io.IOException

carriageReturn

public void carriageReturn()
                    throws java.io.IOException

Send a carriage return to the remote shell.

Throws:

java.io.IOException

getEnvironment

public ShellEnvironment getEnvironment()

Get the remote shell's environment.

Returns:

ShellEnvironment

setEnvironment

public void setEnvironment(ShellEnvironment env)

setDefaultEOL

public static void setDefaultEOL(java.lang.String defaultEOL)

Set the default EOL string for unknown operating systems. Defaults to CR

Parameters:

defaultEOL - String

isAllocatePseudoTerminal

public boolean isAllocatePseudoTerminal()

setAllocatePseudoTerminal

public void setAllocatePseudoTerminal(boolean allocatePseudoTerminal)