Secure iNet Factory

com.jscape.inet.ssh
Class SshSession

java.lang.Object
  extended by 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
SshSession(SshParameters sshParams)
          Creates a new SshSession instance.
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
 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 debug(java.lang.String msg)
          Sends debug message to debug stream.
 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 pause(long timeout)
          Pauses current session for specified timeout
 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 characterSet)
          Sets the session character set
 void setCommandTerminator(java.lang.String string)
          Sets terminator used when sending data to SSH server.
 void setDebug(boolean b)
          Enables or disables debugging information.
 void setDebugStream(java.io.PrintStream stream)
          Sets PrintStream used in outputting debug information.
 void setEcho(boolean echo)
          Sets server echo flag for the next connection.
 void setPollingInterval(int pollingInterval)
          Sets the polling interval used when checking for completion of commands sent using send or sendWait methods.
 void setRegexMatchLength(int regexMatchLength)
          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 string, boolean regex)
          Sets shell prompt to wait for before sending commands.
 void setSsh(Ssh ssh)
          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(SshParameters sshParams)
           throws SshException
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)
           throws SshException
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)
           throws SshException
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

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

getSsh

public Ssh getSsh()
Gets underlying Ssh instance.

Returns:
underlying Ssh instance

setSsh

public void setSsh(Ssh ssh)
Sets the underlying Ssh instance.

Parameters:
ssh -

connect

public void connect()
             throws SshException
Establishes connection with SSH server and performs login.

Throws:
SshException - if an SSH related exception occurs

getEcho

public boolean getEcho()
Returns echo flag.

Returns:
true if server echo is enabled; false otherwise

setEcho

public void setEcho(boolean echo)
Sets server echo flag for the next connection.

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

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

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, long), SshTaskTimeoutException

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,
                                 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,
                                 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

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.


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

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

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)

disconnect

public void disconnect()
Disconnects from SSH server.


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 string,
                           boolean regex)
Sets shell prompt to wait for before sending commands. Default value is "$"

Parameters:
string - the shell prompt
regex - true if shell prompt to match is a regular expression, false otherwise
See Also:
setRegexMatchLength(int)

getDebug

public boolean getDebug()
Checks if debugging is enabled. Default is disabled.

Returns:
true if debugging enabled, false otherwise

setDebug

public void setDebug(boolean b)
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:
b - 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)

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 string)
Sets terminator used when sending data to SSH server. Default value is LF (Line Feed).

Parameters:
string - the command terminator

debug

public void debug(java.lang.String msg)
Sends debug message to debug stream.

Parameters:
msg -

pause

public void pause(long timeout)
Pauses current session for specified timeout

Parameters:
timeout - time in milliseconds

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

setPollingInterval

public void setPollingInterval(int pollingInterval)
Sets the polling interval used when checking for completion of commands sent using send or sendWait methods. Default interval is 100ms.

Parameters:
pollingInterval - the polling interval in milliseconds.
See Also:
send(java.lang.String, long), sendWait(java.lang.String, java.lang.String, long)

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, long), sendWait(java.lang.String, java.lang.String, long)

setRegexMatchLength

public void setRegexMatchLength(int regexMatchLength)
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:
regexMatchLength -

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

setCharacterSet

public void setCharacterSet(java.lang.String characterSet)
Sets the session character set

Parameters:
characterSet - the character set

getCharacterSet

public java.lang.String getCharacterSet()
Gets the character set

Returns:
The character set used by the service

Secure iNet Factory

Copyright © JSCAPE LLC. 1999-2011. All Rights Reserved