com.maverick.ssh
Class Shell

java.lang.Object
  extended bycom.maverick.ssh.Shell

public class Shell
extends java.lang.Object

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 now
 // 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 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.
 boolean isClosed()
           
static void setDefaultEOL(java.lang.String defaultEOL)
          Set the deafult EOL string for unknown operating systems.
 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 determin 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.
 
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

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 now
 // 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 determin 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

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

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.

Throws:
java.io.IOException
ShellTimeoutException

getEnvironment

public ShellEnvironment getEnvironment()
Get the remote shell's environment.

Returns:
ShellEnvironment

setDefaultEOL

public static void setDefaultEOL(java.lang.String defaultEOL)
Set the deafult EOL string for unknown operating systems. Defaults to CR

Parameters:
defaultEOL - String


Copyright © 2003 3SP LTD. All Rights Reserved.