org.apache.commons.net.telnet

## Class TelnetClient

- java.lang.Object
- - org.apache.commons.net.SocketClient
  - - org.apache.commons.net.telnet.Telnet
    - - org.apache.commons.net.telnet.TelnetClient

-     public class TelnetClient
      extends Telnet

  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.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) int` | `maxSubnegotiationLength` the size of the subnegotiation buffer.
    `protected boolean` | `readerThread` Whether to enable the reader thread.

    - ### Fields inherited from class org.apache.commons.net.telnet.Telnet

      `COMMAND_AYT, COMMAND_DO, COMMAND_DONT, COMMAND_IS, COMMAND_SB, COMMAND_SE, COMMAND_WILL, COMMAND_WONT, debug, debugoptions, DEFAULT_PORT, DO_MASK, NUL, REQUESTED_DO_MASK, REQUESTED_WILL_MASK, TERMINAL_TYPE, TERMINAL_TYPE_IS, TERMINAL_TYPE_SEND, WILL_MASK`

    - ### Fields inherited from class org.apache.commons.net.SocketClient

      `_defaultPort_, _hostname_, _input_, _output_, _serverSocketFactory_, _socket_, _socketFactory_, _timeout_, connectTimeout, NETASCII_EOL, remoteInetSocketAddress`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TelnetClient()` Default TelnetClient constructor, sets terminal-type `VT100`.
    `TelnetClient(int maxSubnegotiationLength)` Constructs an instance with the specified max subnegotiation length and the default terminal-type `VT100`.
    `TelnetClient(String termtype)` Constructs an instance with the specified terminal type.
    `TelnetClient(String termType, int maxSubnegotiationLength)` Constructs an instance with the specified terminal type and max subnegotiation length

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `_connectAction_()` Handles special connection requirements.
    `void` | `addOptionHandler(TelnetOptionHandler opthand)` Registers a new TelnetOptionHandler for this Telnet client to use.
    `(package private) void` | `closeOutputStream()`
    `void` | `deleteOptionHandler(int optcode)` Unregisters a TelnetOptionHandler.
    `void` | `disconnect()` Disconnects the Telnet session, closing the input and output streams as well as the socket.
    `(package private) void` | `flushOutputStream()`
    `InputStream` | `getInputStream()` Gets the Telnet connection input stream.
    `boolean` | `getLocalOptionState(int option)` Gets the state of the option on the local side.
    `OutputStream` | `getOutputStream()` Gets the Telnet connection output stream.
    `boolean` | `getReaderThread()` Gets the status of the reader thread.
    `boolean` | `getRemoteOptionState(int option)` Gets the state of the option on the remote side.
    `(package private) void` | `notifyInputListener()`
    `void` | `registerInputListener(TelnetInputListener listener)` Register a listener to be notified when new incoming data is available to be read on the `input stream`.
    `void` | `registerSpyStream(OutputStream spystream)` Registers an OutputStream for spying what's going on in the TelnetClient session.
    `boolean` | `sendAYT(java.time.Duration timeout)` Sends an `Are You There (AYT)` 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 readerThread)` Sets the status of the reader thread.
    `void` | `stopSpyStream()` Stops spying this TelnetClient.
    `void` | `unregisterInputListener()` Unregisters the current `TelnetInputListener`, if any.

    - ### Methods inherited from class org.apache.commons.net.telnet.Telnet

      `_registerSpyStream, _sendAYT, _sendCommand, _sendSubnegotiation, _stopSpyStream, processAYTResponse, processCommand, processDo, processDont, processSuboption, processWill, processWont, registerNotifHandler, requestDo, requestDont, requestedDo, requestedDont, requestedWill, requestedWont, requestWill, requestWont, sendByte, sendDo, sendDont, sendTerminalType, sendWill, sendWont, setDo, setDont, setWantDo, setWantDont, setWantWill, setWantWont, setWill, setWont, spyRead, spyWrite, stateIsDo, stateIsDont, stateIsWill, stateIsWont, unregisterNotifHandler`

    - ### Methods inherited from class org.apache.commons.net.SocketClient

      `addProtocolCommandListener, applySocketAttributes, checkOpenOutputStream, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, fireReplyReceived, getCharset, getCommandSupport, getConnectTimeout, getDefaultPort, getDefaultTimeout, getHostAddress, getHostAddress, getKeepAlive, getLocalAddress, getLocalPort, getProxy, getReceiveBufferSize, getRemoteAddress, getRemoteInetSocketAddress, getRemotePort, getSendBufferSize, getServerSocketFactory, getSoLinger, getSoTimeout, getTcpNoDelay, isAvailable, isConnected, removeProtocolCommandListener, setCharset, 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

    - #### maxSubnegotiationLength

          final int maxSubnegotiationLength

      the size of the subnegotiation buffer.

    - #### readerThread

          protected boolean readerThread

      Whether to enable the reader thread.

  - ### Constructor Detail

    - #### TelnetClient

          public TelnetClient()

      Default TelnetClient constructor, sets terminal-type `VT100`.

    - #### TelnetClient

          public TelnetClient(int maxSubnegotiationLength)

      Constructs an instance with the specified max subnegotiation length and the default terminal-type `VT100`.
      Parameters:
        `maxSubnegotiationLength` - the size of the subnegotiation buffer.

    - #### TelnetClient

          public TelnetClient(String termtype)

      Constructs an instance with the specified terminal type.
      Parameters:
        `termtype` - the terminal type to use, e.g. `VT100`

    - #### TelnetClient

          public TelnetClient(String termType,
                              int maxSubnegotiationLength)

      Constructs an instance with the specified terminal type and max subnegotiation length
      Parameters:
        `termType` - the terminal type to use, e.g. `VT100`
        `maxSubnegotiationLength` - the size of the subnegotiation buffer

  - ### Method Detail

    - #### _connectAction_

          protected void _connectAction_()
                                  throws IOException

      Handles special connection requirements.
      Overrides:
        `_connectAction_` in class `Telnet`
      Throws:
        `IOException` - If an error occurs during connection setup.

    - #### addOptionHandler

          public void addOptionHandler(TelnetOptionHandler opthand)
                                throws InvalidTelnetOptionException,
                                       IOException

      Registers a new TelnetOptionHandler for this Telnet client to use.
      Overrides:
        `addOptionHandler` in class `Telnet`
      Parameters:
        `opthand` - option handler to be registered.
      Throws:
        `InvalidTelnetOptionException` - on error
        `IOException` - on error

    - #### closeOutputStream

          void closeOutputStream()
                          throws IOException

      Throws:
        `IOException`

    - #### deleteOptionHandler

          public void deleteOptionHandler(int optcode)
                                   throws InvalidTelnetOptionException,
                                          IOException

      Unregisters a TelnetOptionHandler.
      Overrides:
        `deleteOptionHandler` in class `Telnet`
      Parameters:
        `optcode` - Code of the option to be unregistered.
      Throws:
        `InvalidTelnetOptionException` - on error
        `IOException` - on error

    - #### 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` - not thrown, subclasses may throw.

    - #### flushOutputStream

          void flushOutputStream()
                          throws IOException

      Throws:
        `IOException`

    - #### getInputStream

          public InputStream getInputStream()

      Gets 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)

      Gets 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.

    - #### getOutputStream

          public OutputStream getOutputStream()

      Gets 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.

    - #### getReaderThread

          public boolean getReaderThread()

      Gets the status of the reader thread.
      Returns:
        true if the reader thread is enabled, false otherwise

    - #### getRemoteOptionState

          public boolean getRemoteOptionState(int option)

      Gets 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.

    - #### notifyInputListener

          void notifyInputListener()

    - #### 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 listener.

    - #### 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.

    - #### sendAYT

          public boolean sendAYT(java.time.Duration timeout)
                          throws IOException,
                                 IllegalArgumentException,
                                 InterruptedException

      Sends an `Are You There (AYT)` sequence and waits for the result.
      Parameters:
        `timeout` - Time to wait for a response.
      Returns:
        true if AYT received a response, false otherwise.
      Throws:
        `InterruptedException` - on error
        `IllegalArgumentException` - on error
        `IOException` - on error

    - #### 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` - on error

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

    - #### setReaderThread

          public void setReaderThread(boolean readerThread)

      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:
        `readerThread` - true to enable the reader thread, false to disable.
      See Also:
        `registerInputListener(org.apache.commons.net.telnet.TelnetInputListener)`

    - #### stopSpyStream

          public void stopSpyStream()

      Stops spying this TelnetClient.

    - #### unregisterInputListener

          public void unregisterInputListener()

      Unregisters the current `TelnetInputListener`, if any.