org.apache.commons.net.telnet
Class TelnetClient

java.lang.Object
  extended by org.apache.commons.net.SocketClient
      extended by org.apache.commons.net.telnet.TelnetClient

public class TelnetClient
extends SocketClient

The TelnetClient class implements the simple network virtual terminal (NVT) for the Telnet protocol according to RFC 854. It does not implement any of the extra Telnet options because it is meant to be used within a Java program providing automated access to Telnet accessible resources.

The class can be used by first connecting to a server using the SocketClient connect method. Then an InputStream and OutputStream for sending and receiving data over the Telnet connection can be obtained by using the getInputStream() and getOutputStream() methods. When you finish using the streams, you must call disconnect rather than simply closing the streams.

Author:
Bruno D'Avanzo

Field Summary
protected  boolean readerThread
           
protected static int TERMINAL_TYPE
          Terminal type option
protected static int TERMINAL_TYPE_IS
          Is (for subnegotiation)
protected static int TERMINAL_TYPE_SEND
          Send (for subnegotiation)
 
Fields inherited from class org.apache.commons.net.SocketClient
_defaultPort_, _input_, _output_, _serverSocketFactory_, _socket_, _socketFactory_, _timeout_, connectTimeout, NETASCII_EOL
 
Constructor Summary
TelnetClient()
          Default TelnetClient constructor, sets terminal-type VT100.
TelnetClient(String termtype)
          Construct an instance with the specified terminal type.
 
Method Summary
protected  void _connectAction_()
          Handles special connection requirements.
 void addOptionHandler(TelnetOptionHandler opthand)
          Registers a new TelnetOptionHandler for this telnet client to use.
 void deleteOptionHandler(int optcode)
          Unregisters a TelnetOptionHandler.
 void disconnect()
          Disconnects the telnet session, closing the input and output streams as well as the socket.
 InputStream getInputStream()
          Returns the telnet connection input stream.
 boolean getLocalOptionState(int option)
          Returns the state of the option on the local side.
 OutputStream getOutputStream()
          Returns the telnet connection output stream.
 boolean getReaderThread()
          Gets the status of the reader thread.
 boolean getRemoteOptionState(int option)
          Returns the state of the option on the remote side.
 void registerInputListener(TelnetInputListener listener)
          Register a listener to be notified when new incoming data is available to be read on the input stream.
 void registerNotifHandler(TelnetNotificationHandler notifhand)
          Registers a notification handler to which will be sent notifications of received telnet option negotiation commands.
 void registerSpyStream(OutputStream spystream)
          Registers an OutputStream for spying what's going on in the TelnetClient session.
 boolean sendAYT(long timeout)
          Sends an Are You There sequence and waits for the result.
 void sendCommand(byte command)
          Sends a command byte to the remote peer, adding the IAC prefix.
 void sendSubnegotiation(int[] message)
          Sends a protocol-specific subnegotiation message to the remote peer.
 void setReaderThread(boolean flag)
          Sets the status of the reader thread.
 void stopSpyStream()
          Stops spying this TelnetClient.
 void unregisterInputListener()
          Unregisters the current TelnetInputListener, if any.
 void unregisterNotifHandler()
          Unregisters the current notification handler.
 
Methods inherited from class org.apache.commons.net.SocketClient
addProtocolCommandListener, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, fireReplyReceived, getCommandSupport, getConnectTimeout, getDefaultPort, getDefaultTimeout, getKeepAlive, getLocalAddress, getLocalPort, getProxy, getReceiveBufferSize, getRemoteAddress, getRemotePort, getSendBufferSize, getServerSocketFactory, getSoLinger, getSoTimeout, getTcpNoDelay, isAvailable, isConnected, removeProtocolCommandListener, setConnectTimeout, setDefaultPort, setDefaultTimeout, setKeepAlive, setProxy, setReceiveBufferSize, setSendBufferSize, setServerSocketFactory, setSocketFactory, setSoLinger, setSoTimeout, setTcpNoDelay, verifyRemote
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

readerThread

protected boolean readerThread

TERMINAL_TYPE

protected static final int TERMINAL_TYPE
Terminal type option

See Also:
Constant Field Values

TERMINAL_TYPE_SEND

protected static final int TERMINAL_TYPE_SEND
Send (for subnegotiation)

See Also:
Constant Field Values

TERMINAL_TYPE_IS

protected static final int TERMINAL_TYPE_IS
Is (for subnegotiation)

See Also:
Constant Field Values
Constructor Detail

TelnetClient

public TelnetClient()
Default TelnetClient constructor, sets terminal-type VT100.


TelnetClient

public TelnetClient(String termtype)
Construct an instance with the specified terminal type.

Parameters:
termtype - the terminal type to use, e.g. VT100
Method Detail

_connectAction_

protected void _connectAction_()
                        throws IOException
Handles special connection requirements.

Throws:
IOException - If an error occurs during connection setup.

disconnect

public void disconnect()
                throws IOException
Disconnects the telnet session, closing the input and output streams as well as the socket. If you have references to the input and output streams of the telnet connection, you should not close them yourself, but rather call disconnect to properly close the connection.

Overrides:
disconnect in class SocketClient
Throws:
IOException - If there is an error closing the socket.

getOutputStream

public OutputStream getOutputStream()
Returns the telnet connection output stream. You should not close the stream when you finish with it. Rather, you should call disconnect .

Returns:
The telnet connection output stream.

getInputStream

public InputStream getInputStream()
Returns the telnet connection input stream. You should not close the stream when you finish with it. Rather, you should call disconnect .

Returns:
The telnet connection input stream.

getLocalOptionState

public boolean getLocalOptionState(int option)
Returns the state of the option on the local side.

Parameters:
option - - Option to be checked.

Returns:
The state of the option on the local side.

getRemoteOptionState

public boolean getRemoteOptionState(int option)
Returns the state of the option on the remote side.

Parameters:
option - - Option to be checked.

Returns:
The state of the option on the remote side.

sendAYT

public boolean sendAYT(long timeout)
                throws IOException,
                       IllegalArgumentException,
                       InterruptedException
Sends an Are You There sequence and waits for the result.

Parameters:
timeout - - Time to wait for a response (millis.)

Returns:
true if AYT received a response, false otherwise

Throws:
InterruptedException
IllegalArgumentException
IOException

sendSubnegotiation

public void sendSubnegotiation(int[] message)
                        throws IOException,
                               IllegalArgumentException
Sends a protocol-specific subnegotiation message to the remote peer. TelnetClient will add the IAC SB & IAC SE framing bytes; the first byte in message should be the appropriate telnet option code.

This method does not wait for any response. Subnegotiation messages sent by the remote end can be handled by registering an approrpriate TelnetOptionHandler.

Parameters:
message - option code followed by subnegotiation payload
Throws:
IllegalArgumentException - if message has length zero
IOException - if an I/O error occurs while writing the message
Since:
3.0

sendCommand

public void sendCommand(byte command)
                 throws IOException,
                        IllegalArgumentException
Sends a command byte to the remote peer, adding the IAC prefix.

This method does not wait for any response. Messages sent by the remote end can be handled by registering an approrpriate TelnetOptionHandler.

Parameters:
command - the code for the command
Throws:
IOException - if an I/O error occurs while writing the message
IllegalArgumentException
Since:
3.0

addOptionHandler

public void addOptionHandler(TelnetOptionHandler opthand)
                      throws InvalidTelnetOptionException,
                             IOException
Registers a new TelnetOptionHandler for this telnet client to use.

Parameters:
opthand - - option handler to be registered.

Throws:
InvalidTelnetOptionException
IOException

deleteOptionHandler

public void deleteOptionHandler(int optcode)
                         throws InvalidTelnetOptionException,
                                IOException
Unregisters a TelnetOptionHandler.

Parameters:
optcode - - Code of the option to be unregistered.

Throws:
InvalidTelnetOptionException
IOException

registerSpyStream

public void registerSpyStream(OutputStream spystream)
Registers an OutputStream for spying what's going on in the TelnetClient session.

Parameters:
spystream - - OutputStream on which session activity will be echoed.

stopSpyStream

public void stopSpyStream()
Stops spying this TelnetClient.


registerNotifHandler

public void registerNotifHandler(TelnetNotificationHandler notifhand)
Registers a notification handler to which will be sent notifications of received telnet option negotiation commands.

Parameters:
notifhand - - TelnetNotificationHandler to be registered

unregisterNotifHandler

public void unregisterNotifHandler()
Unregisters the current notification handler.


setReaderThread

public void setReaderThread(boolean flag)
Sets the status of the reader thread.

When enabled, a seaparate internal reader thread is created for new connections to read incoming data as it arrives. This results in immediate handling of option negotiation, notifications, etc. (at least until the fixed-size internal buffer fills up). Otherwise, no thread is created an all negotiation and option handling is deferred until a read() is performed on the input stream.

The reader thread must be enabled for TelnetInputListener support.

When this method is invoked, the reader thread status will apply to all subsequent connections; the current connection (if any) is not affected.

Parameters:
flag - true to enable the reader thread, false to disable
See Also:
registerInputListener(org.apache.commons.net.telnet.TelnetInputListener)

getReaderThread

public boolean getReaderThread()
Gets the status of the reader thread.

Returns:
true if the reader thread is enabled, false otherwise

registerInputListener

public void registerInputListener(TelnetInputListener listener)
Register a listener to be notified when new incoming data is available to be read on the input stream. Only one listener is supported at a time.

More precisely, notifications are issued whenever the number of bytes available for immediate reading (i.e., the value returned by InputStream.available()) transitions from zero to non-zero. Note that (in general) multiple reads may be required to empty the buffer and reset this notification, because incoming bytes are being added to the internal buffer asynchronously.

Notifications are only supported when a reader thread is enabled for the connection.

Parameters:
listener - listener to be registered; replaces any previous
Since:
3.0

unregisterInputListener

public void unregisterInputListener()
Unregisters the current TelnetInputListener, if any.

Since:
3.0


Copyright © 2001-2012 The Apache Software Foundation. All Rights Reserved.