com.jscape.inet.telnet

Class TelnetSession

java.lang.Object

com.jscape.inet.telnet.TelnetSession

public class TelnetSession
extends java.lang.Object

Convenience class for automating communications with a Telnet server.

Example:

 String hostname = "10.0.0.2";
 String loginPrompt = "login:";
 String passwordPrompt = "Password:"
 String shellPrompt = "$";

 // create new TelnetSession instance providing hostname as argument
 TelnetSession session = new TelnetSession(hostname);

 // set the expected login prompt
 session.setLoginPrompt(loginPrompt);

 // set the expected password prompt
 session.setPasswordPrompt(passwordPrompt);

 // set the expected shell prompt
 session.setShellPrompt(shellPrompt); *

 // connect and login using supplied username and password
 session.connect(username,password);

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

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

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

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

Constructor Summary

Constructors

Constructor and Description
TelnetSession(java.lang.String hostname) Creates a new TelnetSession instance.
TelnetSession(java.lang.String hostname, boolean listener) Creates a new TelnetSession instance.
TelnetSession(java.lang.String hostname, int port) Creates a new TelnetSession instance.
TelnetSession(java.lang.String hostname, int port, boolean listener) Creates a new TelnetSession instance.
TelnetSession(java.lang.String hostname, int port, java.lang.String characterSet) Creates a new TelnetSession instance.
TelnetSession(java.lang.String hostname, int port, java.lang.String characterSet, boolean listener) Creates a new TelnetSession instance.
TelnetSession(java.lang.String hostname, java.lang.String characterSet) Creates a new TelnetSession instance.
TelnetSession(java.lang.String hostname, java.lang.String characterSet, boolean listener) Creates a new TelnetSession instance.

Method Summary

Modifier and Type	Method and Description
void	addTelnetListener(TelnetListener listener) Add telnet event listener.
void	connect(java.lang.String username, java.lang.String password) Establishes connection with telnet server and performs login using specified username and password.
void	connect(java.lang.String username, java.lang.String password, int timeout) Establishes connection with telnet server and performs login using specified username and password.
void	debug(java.lang.String msg) Sends debug message to debug stream.
void	disconnect() Disconnects from telnet server.
java.lang.String	getCommandTerminator() Gets terminator used when sending data to telnet server.
java.io.PrintStream	getDebugStream() Gets PrintStream used in outputting debug information.
java.lang.String	getHostname() Gets the hostname of telnet server.
java.lang.String	getLoginPrompt() Gets login prompt to wait for before sending username.
java.lang.String	getPasswordPrompt() Gets password prompt to wait for before sending password.
int	getPollingInterval() Gets the polling interval used when checking for completion of commands sent using send or sendWait methods.
int	getPort() Gets the port of the telnet server.
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.
Telnet	getTelnet() Gets underlying Telnet instance.
void	interrupt() Interrupts any running command waiting for an expected prompt.
boolean	isDebug() Checks if debugging is enabled.
void	pause(long timeout) Pauses current session for specified timeout.
void	removeTelnetListener(TelnetListener listener) Remove telnet event listener.
java.lang.String	send(java.lang.String command) Sends command to telnet host terminated by command terminator.
java.lang.String	send(java.lang.String command, long timeout) Sends command to telnet host terminated by command terminator.
void	sendNoWait(java.lang.String command) Sends command to telnet host terminated by command terminator.
void	sendRaw(java.lang.String data) Sends data to telnet host without command terminator.
java.lang.String	sendWait(java.lang.String command, java.lang.String prompt) Sends command to telnet host terminated by command terminator.
java.lang.String	sendWait(java.lang.String command, java.lang.String prompt, boolean regex) Sends command to telnet host terminated by command terminator.
java.lang.String	sendWait(java.lang.String command, java.lang.String prompt, boolean regex, long timeout) Sends command to telnet host terminated by command terminator.
java.lang.String	sendWait(java.lang.String command, java.lang.String prompt, long timeout) Sends command to telnet host terminated by command terminator.
void	setCommandTerminator(java.lang.String string) Sets terminator used when sending data to telnet server.
void	setDebug(boolean b) Enables or disables debugging information.
void	setDebugStream(java.io.PrintStream stream) Sets PrintStream used in outputting debug information.
void	setHostname(java.lang.String hostname) Sets the hostname of telnet server.
void	setLoginPrompt(java.lang.String string) Sets login prompt to wait for before sending username.
void	setLoginPrompt(java.lang.String loginPrompt, boolean regex) Sets login prompt to wait for before sending username.
void	setPasswordPrompt(java.lang.String string) Sets password prompt to wait for before sending password.
void	setPasswordPrompt(java.lang.String string, boolean regex) Sets password prompt to wait for before sending password.
void	setPollingInterval(int pollingInterval) Sets the polling interval used when checking for completion of commands sent using send or sendWait methods.
void	setPort(int i) Sets the port of the telnet server.
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

TelnetSession

public TelnetSession(java.lang.String hostname)

Creates a new TelnetSession instance.

Parameters:

hostname - the hostname of telnet server

TelnetSession

public TelnetSession(java.lang.String hostname,
                     boolean listener)

Creates a new TelnetSession instance.

Parameters:

hostname - the hostname of telnet server

listener - automatically register a telnet listener and reject any option negotiation

TelnetSession

public TelnetSession(java.lang.String hostname,
                     java.lang.String characterSet)

Creates a new TelnetSession instance.

Parameters:

hostname - the hostname of telnet server

characterSet - the character set to use when reading data from telnet server

TelnetSession

public TelnetSession(java.lang.String hostname,
                     java.lang.String characterSet,
                     boolean listener)

Creates a new TelnetSession instance.

Parameters:

hostname - the hostname of telnet server

characterSet - the character set to use when reading data from telnet server

listener - automatically register a telnet listener and reject any option negotiation

TelnetSession

public TelnetSession(java.lang.String hostname,
                     int port,
                     boolean listener)

Creates a new TelnetSession instance.

Parameters:

hostname - the hostname of telnet server

port - the port of telnet server

listener - automatically register a telnet listener and reject any option negotiation

TelnetSession

public TelnetSession(java.lang.String hostname,
                     int port)

Creates a new TelnetSession instance.

Parameters:

hostname - the hostname of telnet server

port - the port of telnet server

TelnetSession

public TelnetSession(java.lang.String hostname,
                     int port,
                     java.lang.String characterSet)

Creates a new TelnetSession instance.

Parameters:

hostname - the hostname of the telnet server

port - the port of the telnet server

characterSet - the character set

TelnetSession

public TelnetSession(java.lang.String hostname,
                     int port,
                     java.lang.String characterSet,
                     boolean listener)

Creates a new TelnetSession instance.

Parameters:

hostname - the hostname of the telnet server

port - the port of the telnet server

characterSet - the character set

listener - automatically register a telnet listener and reject any option negotiation

Method Detail

connect

public void connect(java.lang.String username,
                    java.lang.String password,
                    int timeout)
             throws TelnetException

Establishes connection with telnet server and performs login using specified username and password.

Parameters:

username - the username or null if no login prompt is displayed

password - the password or null if no password prompt is displayed

timeout - the timeout in milliseconds for opening connection to telnet server.

Throws:

TelnetException - if a telnet or I/O related error occurs

connect

public void connect(java.lang.String username,
                    java.lang.String password)
             throws TelnetException

Establishes connection with telnet server and performs login using specified username and password.

Parameters:

username - the username or null if no login prompt is displayed

password - the password or null if no password prompt is displayed

Throws:

TelnetException - if a telnet or I/O related error occurs

send

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

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

Parameters:

command - the command to send

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

Returns:

the response from telnet server

Throws:

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

See Also:

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

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 TelnetSession from waiting for a response. You should only use this method in the event you wish to interrupt waiting for a response.

send

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

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

Parameters:

command - the command to send

Returns:

the response from telnet server

Throws:

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

See Also:

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

sendWait

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

Sends command to telnet host terminated by command terminator. Waits until specified prompt is returned by telnet server buffering response data. If shell prompt is not received within defined timeout then a TelnetTaskTimeoutException 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:

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

See Also:

setCommandTerminator(java.lang.String), TelnetTaskTimeoutException

sendWait

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

Sends command to telnet host terminated by command terminator. Waits until specified prompt is returned by telnet server buffering response data. If shell prompt is not received within defined timeout then a TelnetTaskTimeoutException 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

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

Returns:

the response from telnet server

Throws:

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

See Also:

setCommandTerminator(java.lang.String), setRegexMatchLength(int), TelnetTaskTimeoutException

sendWait

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

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

Parameters:

command - the command to send

prompt - the prompt to wait for

Returns:

the response from telnet server

Throws:

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

See Also:

setCommandTerminator(java.lang.String), TelnetTaskTimeoutException

sendWait

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

Sends command to telnet host terminated by command terminator. Waits until specified prompt is returned by telnet server buffering response data. If expected prompt is not received within default timeout of 120 seconds then a TelnetTaskTimeoutException 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:

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

See Also:

setCommandTerminator(java.lang.String), setRegexMatchLength(int), TelnetTaskTimeoutException

sendNoWait

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

Sends command to telnet 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)

sendRaw

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

Sends data to telnet 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()
                throws TelnetException

Disconnects from telnet server.

Throws:

TelnetException - if a telnet or I/O related error occurs

getLoginPrompt

public java.lang.String getLoginPrompt()

Gets login prompt to wait for before sending username. Default value is "login:"

Returns:

the login prompt

getPasswordPrompt

public java.lang.String getPasswordPrompt()

Gets password prompt to wait for before sending password. Default value is "Password:"

Returns:

the password prompt

getShellPrompt

public java.lang.String getShellPrompt()

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

Returns:

the shell prompt

setLoginPrompt

public void setLoginPrompt(java.lang.String string)

Sets login prompt to wait for before sending username. Default value is "login:"

Parameters:

string - the login prompt

setLoginPrompt

public void setLoginPrompt(java.lang.String loginPrompt,
                           boolean regex)

Sets login prompt to wait for before sending username. Default value is "login:"

Parameters:

loginPrompt - the login prompt

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

See Also:

setRegexMatchLength(int)

setPasswordPrompt

public void setPasswordPrompt(java.lang.String string)

Sets password prompt to wait for before sending password. Default value is "Password:"

Parameters:

string - the password prompt

setPasswordPrompt

public void setPasswordPrompt(java.lang.String string,
                              boolean regex)

Sets password prompt to wait for before sending password. Default value is "Password:"

Parameters:

string - the password prompt

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

See Also:

setRegexMatchLength(int)

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 prompt to match is a regular expression, false otherwise

See Also:

setRegexMatchLength(int)

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

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)

isDebug

public boolean isDebug()

Checks if debugging is enabled. Default is disabled.

Returns:

true if debugging enabled, false otherwise

debug

public void debug(java.lang.String msg)

Sends debug message to debug stream.

Parameters:

msg - the debug message to send

See Also:

setDebugStream(java.io.PrintStream)

setDebug

public void setDebug(boolean b)

Enables or disables debugging information. In debug enabled mode all data received from telnet 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 telnet 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 telnet server. Default value is LF (Line Feed).

Parameters:

string - the command terminator

getPort

public int getPort()

Gets the port of the telnet server.

Returns:

the port

getHostname

public java.lang.String getHostname()

Gets the hostname of telnet server.

Returns:

the hostname

setHostname

public void setHostname(java.lang.String hostname)

Sets the hostname of telnet server.

Parameters:

hostname - the hostname

setPort

public void setPort(int i)

Sets the port of the telnet server.

Parameters:

i - the port

addTelnetListener

public void addTelnetListener(TelnetListener listener)

Add telnet event listener.

Parameters:

listener - a TelnetListener

See Also:

TelnetListener

removeTelnetListener

public void removeTelnetListener(TelnetListener listener)

Remove telnet event listener.

Parameters:

listener - a TelnetListener

See Also:

TelnetListener

pause

public void pause(long timeout)

Pauses current session for specified timeout.

Parameters:

timeout - time in milliseconds

getTelnet

public Telnet getTelnet()

Gets underlying Telnet instance.

Returns:

underlying Telnet instance