com.jscape.inet.ssh

Class SshSession

java.lang.Object

com.jscape.inet.ssh.SshSession

public class SshSession
extends java.lang.Object

Convenience class for automating communications with a SSH server.

Example:

 String shellPrompt = "$";

 // creates new SshShession instance providing hostname, username and password arguments
 SshSession session = new SshSession(hostname,username,password);

 // set expected shell prompt from SSH server
 session.setShellPrompt(shellPrompt);

 // establish connection
 session.connect();

 // send command to SSH shell and wait for shell prompt
 session.send("cd /user/logs");

 // send command to SSH shell and wait for shell prompt
 session.send("rm *.log");

 // send command to SSH shell and DO NOT wait for shell prompt
 session.sendNoWait("exit");

 // close connection with SSH server
 session.disconnect();
 

Constructor Summary

Constructors

Constructor and Description
SshSession(SshParameters sshParams) Creates a new SshSession instance.
SshSession(SshParameters sshParams, Ssh ssh) Creates a new SshSession instance.
SshSession(Ssh ssh, java.lang.String promptPattern, boolean promptPatternIsRegex, int regexMatchLength, java.lang.String endOfLine, java.lang.String characterSet, int pollingInterval)
SshSession(java.lang.String hostname, int port, java.lang.String username, java.lang.String password) Creates a new SshSession instance.
SshSession(java.lang.String hostname, java.lang.String username, java.lang.String password) Creates a new SshSession instance.

Method Summary

Modifier and Type	Method and Description
void	addSshListener(SshListener listener) Add Ssh event listener.
void	connect() Establishes connection with SSH server and performs login.
void	connect(int timeout) Establishes connection with SSH server and performs login
void	disconnect() Disconnects from SSH server.
java.lang.String	getCharacterSet() Gets the character set
java.lang.String	getCommandTerminator() Gets terminator used when sending data to SSH server.
boolean	getDebug() Checks if debugging is enabled.
java.io.PrintStream	getDebugStream() Gets PrintStream used in outputting debug information.
boolean	getEcho() Returns echo flag.
int	getPollingInterval() Gets the polling interval used when checking for completion of commands sent using send or sendWait methods.
int	getRegexMatchLength() Gets the number of characters to read from the end of the response buffer when using regular expressions to detect start or end prompts.
java.lang.String	getShellPrompt() Gets shell prompt to wait for before sending commands.
Ssh	getSsh() Gets underlying Ssh instance.
void	interrupt() Interrupts any running command waiting for an expected prompt.
void	removeSshListener(SshListener listener) Remove Ssh event listener.
java.lang.String	send(java.lang.String command) Sends command to SSH host terminated by command terminator.
java.lang.String	send(java.lang.String command, long timeout) Sends command to SSH host terminated by command terminator.
java.lang.String	send(java.lang.String command, java.lang.String prompt) Deprecated. replaced by sendWait(String, String) method
void	sendNoWait(java.lang.String command) Sends command to SSH host terminated by command terminator.
void	sendRaw(java.lang.String data) Sends data to SSH host without command terminator.
java.lang.String	sendWait(java.lang.String command, java.lang.String prompt) Sends command to SSH host terminated by command terminator.
java.lang.String	sendWait(java.lang.String command, java.lang.String prompt, boolean regex) Sends command to SSH host terminated by command terminator.
java.lang.String	sendWait(java.lang.String command, java.lang.String prompt, boolean regex, long timeout) Sends command to SSH host terminated by command terminator.
java.lang.String	sendWait(java.lang.String command, java.lang.String prompt, long timeout) Sends command to SSH host terminated by command terminator.
void	setCharacterSet(java.lang.String value) Sets the session character set
void	setCommandTerminator(java.lang.String value) Sets terminator used when sending data to SSH server.
void	setDebug(boolean value) Enables or disables debugging information.
void	setDebugStream(java.io.PrintStream stream) Sets PrintStream used in outputting debug information.
void	setEcho(boolean value) Sets server echo flag for the next connection.
void	setPollingInterval(int value) Sets the polling interval used when checking for completion of commands sent using send or sendWait methods.
void	setRegexMatchLength(int value) Sets the number of characters to read from the end of the response buffer when using regular expressions to detect start or end prompts.
void	setShellPrompt(java.lang.String string) Sets shell prompt to wait for before sending commands.
void	setShellPrompt(java.lang.String value, boolean isRegex) Sets shell prompt to wait for before sending commands.
void	setSsh(Ssh value) Sets the underlying Ssh instance.

Methods inherited from class java.lang.Object

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

Constructor Detail

SshSession

public SshSession(Ssh ssh,
                  java.lang.String promptPattern,
                  boolean promptPatternIsRegex,
                  int regexMatchLength,
                  java.lang.String endOfLine,
                  java.lang.String characterSet,
                  int pollingInterval)

SshSession

public SshSession(SshParameters sshParams,
                  Ssh ssh)

Creates a new SshSession instance.

Parameters:

sshParams - - the SshParameters instance.

ssh - - the Ssh instance.

Throws:

SshException - - the exception instance that is thrown if an error occurs.

SshSession

public SshSession(SshParameters sshParams)

Creates a new SshSession instance.

Parameters:

sshParams - an SshParameters instance

Throws:

SshException - if an SSH related exception occurs

SshSession

public SshSession(java.lang.String hostname,
                  int port,
                  java.lang.String username,
                  java.lang.String password)

Creates a new SshSession instance.

Parameters:

hostname - the hostname of SSH server

port - the port of SSH server

username - the SSH username

password - the SSH password

Throws:

SshException - if an SSH related exception occurs

SshSession

public SshSession(java.lang.String hostname,
                  java.lang.String username,
                  java.lang.String password)

Creates a new SshSession instance.

Parameters:

hostname - the hostname of SSH server

username - the SSH username

password - the SSH password

Throws:

SshException - if an SSH related exception occurs

Method Detail

getSsh

public Ssh getSsh()

Gets underlying Ssh instance.

Returns:

underlying Ssh instance

setSsh

public void setSsh(Ssh value)

Sets the underlying Ssh instance.

Parameters:

value -

getShellPrompt

public java.lang.String getShellPrompt()

Gets shell prompt to wait for before sending commands. Default value is "$"

Returns:

the shell prompt

setShellPrompt

public void setShellPrompt(java.lang.String string)

Sets shell prompt to wait for before sending commands. Default value is "$"

Parameters:

string - the shell prompt

setShellPrompt

public void setShellPrompt(java.lang.String value,
                           boolean isRegex)

Sets shell prompt to wait for before sending commands. Default value is "$"

Parameters:

value - the shell prompt

isRegex - true if shell prompt to match is a regular expression, false otherwise

See Also:

setRegexMatchLength(int)

getCommandTerminator

public java.lang.String getCommandTerminator()

Gets terminator used when sending data to SSH server. Default value is LF (Line Feed).

Returns:

the command terminator

setCommandTerminator

public void setCommandTerminator(java.lang.String value)

Sets terminator used when sending data to SSH server. Default value is LF (Line Feed).

Parameters:

value - the command terminator

getEcho

public boolean getEcho()

Returns echo flag.

Returns:

true if server echo is enabled; false otherwise

setEcho

public void setEcho(boolean value)

Sets server echo flag for the next connection.

Parameters:

value - if true server echo will be enabled for the next connection.

getRegexMatchLength

public int getRegexMatchLength()

Gets the number of characters to read from the end of the response buffer when using regular expressions to detect start or end prompts. Default value is 20.

Returns:

match length

setRegexMatchLength

public void setRegexMatchLength(int value)

Sets the number of characters to read from the end of the response buffer when using regular expressions to detect start or end prompts. Default value is 20.

Parameters:

value -

getCharacterSet

public java.lang.String getCharacterSet()

Gets the character set

Returns:

The character set used by the service

setCharacterSet

public void setCharacterSet(java.lang.String value)

Sets the session character set

Parameters:

value - the character set

getPollingInterval

public int getPollingInterval()

Gets the polling interval used when checking for completion of commands sent using send or sendWait methods. Default interval is 100ms.

Returns:

the polling interval in milliseconds.

See Also:

send(java.lang.String, java.lang.String), sendWait(java.lang.String, java.lang.String, boolean, long)

setPollingInterval

public void setPollingInterval(int value)

Sets the polling interval used when checking for completion of commands sent using send or sendWait methods. Default interval is 100ms.

Parameters:

value - the polling interval in milliseconds.

See Also:

send(java.lang.String, java.lang.String), sendWait(java.lang.String, java.lang.String, boolean, long)

getDebug

public boolean getDebug()

Checks if debugging is enabled. Default is disabled.

Returns:

true if debugging enabled, false otherwise

setDebug

public void setDebug(boolean value)

Enables or disables debugging information. In debug enabled mode all data received from SSH server is output to the debug stream. Default is disabled.

Parameters:

value - true to enable debugging, false to disable

See Also:

setDebugStream(java.io.PrintStream)

setDebugStream

public void setDebugStream(java.io.PrintStream stream)

Sets PrintStream used in outputting debug information. Default is System.out

Parameters:

stream - a PrintStream

getDebugStream

public java.io.PrintStream getDebugStream()

Gets PrintStream used in outputting debug information. Default is Sytem.out

Returns:

a PrintStream

See Also:

setDebug(boolean), setDebugStream(java.io.PrintStream)

addSshListener

public void addSshListener(SshListener listener)

Add Ssh event listener.

Parameters:

listener - a SshListener

See Also:

SshListener

removeSshListener

public void removeSshListener(SshListener listener)

Remove Ssh event listener.

Parameters:

listener - a SshListener

See Also:

SshListener

connect

public void connect(int timeout)
             throws SshException

Establishes connection with SSH server and performs login

Parameters:

timeout - timeout in milliseconds for establishing a connection

Throws:

SshException - if an SSH related exception occurs

connect

public void connect()
             throws SshException

Establishes connection with SSH server and performs login.

Throws:

SshException - if an SSH related exception occurs

disconnect

public void disconnect()

Disconnects from SSH server.

sendRaw

public void sendRaw(java.lang.String data)
             throws java.io.IOException

Sends data to SSH host without command terminator. Does not wait for shell prompt to be returned.

Parameters:

data - the data to send

Throws:

java.io.IOException - if an I/O related error occurs

See Also:

setCommandTerminator(java.lang.String)

sendNoWait

public void sendNoWait(java.lang.String command)
                throws java.io.IOException

Sends command to SSH host terminated by command terminator. Does not wait for shell prompt to be returned.

Parameters:

command - the command to send

Throws:

java.io.IOException - if an I/O related error occurs

See Also:

setCommandTerminator(java.lang.String)

sendWait

public java.lang.String sendWait(java.lang.String command,
                                 java.lang.String prompt,
                                 boolean regex,
                                 long timeout)
                          throws SshException

Sends command to SSH host terminated by command terminator. Waits until specified prompt is returned by SSH server buffering response data. If expected prompt is not received within defined timeout then an SshTaskTimeoutException will be thrown.

Parameters:

command - the command to send

prompt - the prompt to wait for

timeout - the timeout to use when waiting for task end prompt

regex - true if the prompt to match is a regular expression, false otherwise

Returns:

the response from telnet server

Throws:

SshException - if regular expression prompts are used and regular expression is invalid

See Also:

setCommandTerminator(java.lang.String), setRegexMatchLength(int), SshTaskTimeoutException, SshException

sendWait

public java.lang.String sendWait(java.lang.String command,
                                 java.lang.String prompt,
                                 long timeout)
                          throws SshException

Sends command to SSH host terminated by command terminator. Waits until specified prompt is returned by SSH server buffering response data. If expected prompt is not received within defined timeout then an SshTaskTimeoutException will be thrown.

Parameters:

command - the command to send

prompt - the prompt to wait for

timeout - the timeout to use when waiting for task end prompt

Returns:

the response from telnet server

Throws:

SshException - if regular expression prompts are used and regular expression is invalid

See Also:

setCommandTerminator(java.lang.String), SshException, SshTaskTimeoutException

sendWait

public java.lang.String sendWait(java.lang.String command,
                                 java.lang.String prompt,
                                 boolean regex)
                          throws SshException

Sends command to SSH host terminated by command terminator. Waits until specified prompt is returned by SSH server buffering response data. If expected prompt is not received within default timeout of 120 seconds then an SshTaskTimeoutException will be thrown.

Parameters:

command - the command to send

prompt - the prompt to wait for

regex - true if prompt to match is a regular expression, false otherwise

Returns:

the response from telnet server

Throws:

SshException - if regular expression prompts are used and regular expression is invalid

See Also:

setCommandTerminator(java.lang.String), setRegexMatchLength(int), SshTaskTimeoutException, SshException

sendWait

public java.lang.String sendWait(java.lang.String command,
                                 java.lang.String prompt)
                          throws SshException

Sends command to SSH host terminated by command terminator. Waits until specified prompt is returned by SSH server buffering response data. If expected prompt is not received within default timeout of 120 seconds then an SshTaskTimeoutException will be thrown.

Parameters:

command - the command to send

prompt - the prompt to wait for

Returns:

the response from telnet server

Throws:

SshException - if regular expression prompts are used and regular expression is invalid

See Also:

setCommandTerminator(java.lang.String), SshTaskTimeoutException, SshException

send

public java.lang.String send(java.lang.String command,
                             java.lang.String prompt)
                      throws SshException

Deprecated. replaced by sendWait(String, String) method

Sends command to SSH host terminated by command terminator. Waits until the specified prompt is returned by SSH server buffering response data. If shell prompt is not received within default timeout of 120 seconds then an SshTaskTimeoutException will be thrown.

Parameters:

command - the command to send

prompt - the prompt to wait for

Returns:

the response from SSH server

Throws:

SshException - if regular expression prompts are used and regular expression is invalid

See Also:

setCommandTerminator(java.lang.String), sendWait(java.lang.String, java.lang.String, boolean, long), SshTaskTimeoutException

send

public java.lang.String send(java.lang.String command,
                             long timeout)
                      throws SshException

Sends command to SSH host terminated by command terminator. Waits until the shell prompt is returned by SSH server buffering response data. If shell prompt is not received within defined timeout then an SshTaskTimeoutException will be thrown.

Parameters:

command - the command to send

timeout - the timeout to use when waiting for shell prompt

Returns:

the response from SSH server

Throws:

SshException - if regular expression prompts are used and regular expression is invalid

See Also:

setShellPrompt(java.lang.String), setCommandTerminator(java.lang.String), SshTaskTimeoutException

send

public java.lang.String send(java.lang.String command)
                      throws SshException

Sends command to SSH host terminated by command terminator. Waits until the shell prompt is returned by SSH server buffering response data. If shell prompt is not received within default timeout of 120 seconds then an SshTaskTimeoutException will be thrown.

Parameters:

command - the command to send

Returns:

the response from SSH server

Throws:

SshException - if regular expression prompts are used and regular expression is invalid

See Also:

setShellPrompt(java.lang.String), setCommandTerminator(java.lang.String), SshTaskTimeoutException

interrupt

public void interrupt()

Interrupts any running command waiting for an expected prompt. This method does not stop the command from running on the server but instead stops the SshSession from waiting for a response. You should only use this method in the event you wish to interrupt waiting for a response.