TelnetClient.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.apache.commons.net.telnet;

  20. import java.io.BufferedInputStream;
  21. import java.io.IOException;
  22. import java.io.InputStream;
  23. import java.io.OutputStream;
  24. import java.time.Duration;

  26. /**
  27.  * 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
  28.  * extra Telnet options because it is meant to be used within a Java program providing automated access to Telnet accessible resources.
  29.  * <p>
  30.  * The class can be used by first connecting to a server using the SocketClient {@link org.apache.commons.net.SocketClient#connect connect} method. Then an
  31.  * InputStream and OutputStream for sending and receiving data over the Telnet connection can be obtained by using the {@link #getInputStream getInputStream() }
  32.  * and {@link #getOutputStream getOutputStream() } methods. When you finish using the streams, you must call {@link #disconnect disconnect } rather than simply
  33.  * closing the streams.
  34.  * </p>
  35.  */
  36. public class TelnetClient extends Telnet {
  37.     private static final int DEFAULT_MAX_SUBNEGOTIATION_LENGTH = 512;

  39.     final int maxSubnegotiationLength;
  40.     private InputStream input;
  41.     private OutputStream output;
  42.     protected boolean readerThread = true;
  43.     private TelnetInputListener inputListener;

  45.     /**
  46.      * Default TelnetClient constructor, sets terminal-type {@code VT100}.
  47.      */
  48.     public TelnetClient() {
  49.         this("VT100", DEFAULT_MAX_SUBNEGOTIATION_LENGTH);
  50.     }

  52.     /**
  53.      * Constructs an instance with the specified max subnegotiation length and the default terminal-type {@code VT100}
  54.      *
  55.      * @param maxSubnegotiationLength the size of the subnegotiation buffer
  56.      */
  57.     public TelnetClient(final int maxSubnegotiationLength) {
  58.         this("VT100", maxSubnegotiationLength);
  59.     }

  61.     /**
  62.      * Constructs an instance with the specified terminal type.
  63.      *
  64.      * @param termtype the terminal type to use, e.g. {@code VT100}
  65.      */
  66.     public TelnetClient(final String termtype) {
  67.         this(termtype, DEFAULT_MAX_SUBNEGOTIATION_LENGTH);
  68.     }

  70.     /**
  71.      * Constructs an instance with the specified terminal type and max subnegotiation length
  72.      *
  73.      * @param termtype                the terminal type to use, e.g. {@code VT100}
  74.      * @param maxSubnegotiationLength the size of the subnegotiation buffer
  75.      */
  76.     public TelnetClient(final String termtype, final int maxSubnegotiationLength) {
  77.         /* TERMINAL-TYPE option (start) */
  78.         super(termtype);
  79.         /* TERMINAL-TYPE option (end) */
  80.         this.input = null;
  81.         this.output = null;
  82.         this.maxSubnegotiationLength = maxSubnegotiationLength;
  83.     }

  85.     /**
  86.      * Handles special connection requirements.
  87.      *
  88.      * @throws IOException If an error occurs during connection setup.
  89.      */
  90.     @Override
  91.     protected void _connectAction_() throws IOException {
  92.         super._connectAction_();
  93.         final TelnetInputStream tmp = new TelnetInputStream(_input_, this, readerThread);
  94.         if (readerThread) {
  95.             tmp.start();
  96.         }
  97.         // __input CANNOT refer to the TelnetInputStream. We run into
  98.         // blocking problems when some classes use TelnetInputStream, so
  99.         // we wrap it with a BufferedInputStream which we know is safe.
  100.         // This blocking behavior requires further investigation, but right
  101.         // now it looks like classes like InputStreamReader are not implemented
  102.         // in a safe manner.
  103.         input = new BufferedInputStream(tmp);
  104.         output = new TelnetOutputStream(this);
  105.     }

  107.     /**
  108.      * Registers a new TelnetOptionHandler for this telnet client to use.
  109.      *
  110.      * @param opthand - option handler to be registered.
  111.      *
  112.      * @throws InvalidTelnetOptionException on error
  113.      * @throws IOException                  on error
  114.      */
  115.     @Override
  116.     public void addOptionHandler(final TelnetOptionHandler opthand) throws InvalidTelnetOptionException, IOException {
  117.         super.addOptionHandler(opthand);
  118.     }
  119.     /* open TelnetOptionHandler functionality (end) */

  121.     void closeOutputStream() throws IOException {
  122.         if (_output_ == null) {
  123.             return;
  124.         }
  125.         try {
  126.             _output_.close();
  127.         } finally {
  128.             _output_ = null;
  129.         }
  130.     }

  132.     /**
  133.      * Unregisters a TelnetOptionHandler.
  134.      *
  135.      * @param optcode - Code of the option to be unregistered.
  136.      *
  137.      * @throws InvalidTelnetOptionException on error
  138.      * @throws IOException                  on error
  139.      */
  140.     @Override
  141.     public void deleteOptionHandler(final int optcode) throws InvalidTelnetOptionException, IOException {
  142.         super.deleteOptionHandler(optcode);
  143.     }

  145.     /**
  146.      * 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
  147.      * telnet connection, you should not close them yourself, but rather call disconnect to properly close the connection.
  148.      */
  149.     @Override
  150.     public void disconnect() throws IOException {
  151.         try {
  152.             if (input != null) {
  153.                 input.close();
  154.             }
  155.             if (output != null) {
  156.                 output.close();
  157.             }
  158.         } finally { // NET-594
  159.             output = null;
  160.             input = null;
  161.             super.disconnect();
  162.         }
  163.     }

  165.     void flushOutputStream() throws IOException {
  166.         if (_output_ == null) {
  167.             throw new IOException("Stream closed");
  168.         }
  169.         _output_.flush();
  170.     }

  172.     /**
  173.      * Returns the telnet connection input stream. You should not close the stream when you finish with it. Rather, you should call {@link #disconnect
  174.      * disconnect }.
  175.      *
  176.      * @return The telnet connection input stream.
  177.      */
  178.     public InputStream getInputStream() {
  179.         return input;
  180.     }

  182.     /**
  183.      * Returns the state of the option on the local side.
  184.      *
  185.      * @param option - Option to be checked.
  186.      *
  187.      * @return The state of the option on the local side.
  188.      */
  189.     public boolean getLocalOptionState(final int option) {
  190.         /* BUG (option active when not already acknowledged) (start) */
  191.         return stateIsWill(option) && requestedWill(option);
  192.         /* BUG (option active when not already acknowledged) (end) */
  193.     }

  195.     /* Code Section added for supporting AYT (start) */

  197.     /**
  198.      * Returns the telnet connection output stream. You should not close the stream when you finish with it. Rather, you should call {@link #disconnect
  199.      * disconnect }.
  200.      *
  201.      * @return The telnet connection output stream.
  202.      */
  203.     public OutputStream getOutputStream() {
  204.         return output;
  205.     }

  207.     /**
  208.      * Gets the status of the reader thread.
  209.      *
  210.      * @return true if the reader thread is enabled, false otherwise
  211.      */
  212.     public boolean getReaderThread() {
  213.         return readerThread;
  214.     }

  216.     /**
  217.      * Returns the state of the option on the remote side.
  218.      *
  219.      * @param option - Option to be checked.
  220.      *
  221.      * @return The state of the option on the remote side.
  222.      */
  223.     public boolean getRemoteOptionState(final int option) {
  224.         /* BUG (option active when not already acknowledged) (start) */
  225.         return stateIsDo(option) && requestedDo(option);
  226.         /* BUG (option active when not already acknowledged) (end) */
  227.     }
  228.     /* open TelnetOptionHandler functionality (end) */

  230.     /* open TelnetOptionHandler functionality (start) */

  232.     // Notify input listener
  233.     void notifyInputListener() {
  234.         final TelnetInputListener listener;
  235.         synchronized (this) {
  236.             listener = this.inputListener;
  237.         }
  238.         if (listener != null) {
  239.             listener.telnetInputAvailable();
  240.         }
  241.     }

  243.     /**
  244.      * Register a listener to be notified when new incoming data is available to be read on the {@link #getInputStream input stream}. Only one listener is
  245.      * supported at a time.
  246.      *
  247.      * <p>
  248.      * More precisely, notifications are issued whenever the number of bytes available for immediate reading (i.e., the value returned by
  249.      * {@link InputStream#available}) transitions from zero to non-zero. Note that (in general) multiple reads may be required to empty the buffer and reset
  250.      * this notification, because incoming bytes are being added to the internal buffer asynchronously.
  251.      * </p>
  252.      *
  253.      * <p>
  254.      * Notifications are only supported when a {@link #setReaderThread reader thread} is enabled for the connection.
  255.      * </p>
  256.      *
  257.      * @param listener listener to be registered; replaces any previous
  258.      * @since 3.0
  259.      */
  260.     public synchronized void registerInputListener(final TelnetInputListener listener) {
  261.         this.inputListener = listener;
  262.     }

  264.     /**
  265.      * Registers a notification handler to which will be sent notifications of received telnet option negotiation commands.
  266.      *
  267.      * @param notifhand - TelnetNotificationHandler to be registered
  268.      */
  269.     @Override
  270.     public void registerNotifHandler(final TelnetNotificationHandler notifhand) {
  271.         super.registerNotifHandler(notifhand);
  272.     }

  274.     /* Code Section added for supporting spystreams (start) */
  275.     /**
  276.      * Registers an OutputStream for spying what's going on in the TelnetClient session.
  277.      *
  278.      * @param spystream - OutputStream on which session activity will be echoed.
  279.      */
  280.     public void registerSpyStream(final OutputStream spystream) {
  281.         super._registerSpyStream(spystream);
  282.     }

  284.     /**
  285.      * Sends an {@code Are You There (AYT)} sequence and waits for the result.
  286.      *
  287.      * @param timeout - Time to wait for a response.
  288.      *
  289.      * @return true if AYT received a response, false otherwise.
  290.      *
  291.      * @throws InterruptedException     on error
  292.      * @throws IllegalArgumentException on error
  293.      * @throws IOException              on error
  294.      * @since 3.10.0
  295.      */
  296.     public boolean sendAYT(final Duration timeout) throws IOException, IllegalArgumentException, InterruptedException {
  297.         return _sendAYT(timeout);
  298.     }

  300.     /**
  301.      * Sends an {@code Are You There (AYT)} sequence and waits for the result.
  302.      *
  303.      * @param timeout - Time to wait for a response (millis.)
  304.      *
  305.      * @return true if AYT received a response, false otherwise
  306.      *
  307.      * @throws InterruptedException     on error
  308.      * @throws IllegalArgumentException on error
  309.      * @throws IOException              on error
  310.      * @deprecated Use {@link #sendAYT(Duration)}.
  311.      */
  312.     @Deprecated
  313.     public boolean sendAYT(final long timeout) throws IOException, IllegalArgumentException, InterruptedException {
  314.         return _sendAYT(Duration.ofMillis(timeout));
  315.     }

  317.     /* Code Section added for supporting AYT (start) */

  319.     /**
  320.      * Sends a command byte to the remote peer, adding the IAC prefix.
  321.      *
  322.      * <p>
  323.      * This method does not wait for any response. Messages sent by the remote end can be handled by registering an approrpriate {@link TelnetOptionHandler}.
  324.      * </p>
  325.      *
  326.      * @param command the code for the command
  327.      * @throws IOException              if an I/O error occurs while writing the message
  328.      * @throws IllegalArgumentException on error
  329.      * @since 3.0
  330.      */
  331.     public void sendCommand(final byte command) throws IOException, IllegalArgumentException {
  332.         _sendCommand(command);
  333.     }

  335.     /**
  336.      * Sends a protocol-specific subnegotiation message to the remote peer. {@link TelnetClient} will add the IAC SB &amp; IAC SE framing bytes; the first byte
  337.      * in {@code message} should be the appropriate telnet option code.
  338.      *
  339.      * <p>
  340.      * This method does not wait for any response. Subnegotiation messages sent by the remote end can be handled by registering an approrpriate
  341.      * {@link TelnetOptionHandler}.
  342.      * </p>
  343.      *
  344.      * @param message option code followed by subnegotiation payload
  345.      * @throws IllegalArgumentException if {@code message} has length zero
  346.      * @throws IOException              if an I/O error occurs while writing the message
  347.      * @since 3.0
  348.      */
  349.     public void sendSubnegotiation(final int[] message) throws IOException, IllegalArgumentException {
  350.         if (message.length < 1) {
  351.             throw new IllegalArgumentException("zero length message");
  352.         }
  353.         _sendSubnegotiation(message);
  354.     }

  356.     /**
  357.      * Sets the status of the reader thread.
  358.      *
  359.      * <p>
  360.      * When enabled, a seaparate internal reader thread is created for new connections to read incoming data as it arrives. This results in immediate handling
  361.      * of option negotiation, notifications, etc. (at least until the fixed-size internal buffer fills up). Otherwise, no thread is created an all negotiation
  362.      * and option handling is deferred until a read() is performed on the {@link #getInputStream input stream}.
  363.      * </p>
  364.      *
  365.      * <p>
  366.      * The reader thread must be enabled for {@link TelnetInputListener} support.
  367.      * </p>
  368.      *
  369.      * <p>
  370.      * When this method is invoked, the reader thread status will apply to all subsequent connections; the current connection (if any) is not affected.
  371.      * </p>
  372.      *
  373.      * @param flag true to enable the reader thread, false to disable
  374.      * @see #registerInputListener
  375.      */
  376.     public void setReaderThread(final boolean flag) {
  377.         readerThread = flag;
  378.     }

  380.     /**
  381.      * Stops spying this TelnetClient.
  382.      */
  383.     public void stopSpyStream() {
  384.         super._stopSpyStream();
  385.     }
  386.     /* Code Section added for supporting spystreams (end) */

  388.     /**
  389.      * Unregisters the current {@link TelnetInputListener}, if any.
  390.      *
  391.      * @since 3.0
  392.      */
  393.     public synchronized void unregisterInputListener() {
  394.         this.inputListener = null;
  395.     }

  397.     /**
  398.      * Unregisters the current notification handler.
  399.      */
  400.     @Override
  401.     public void unregisterNotifHandler() {
  402.         super.unregisterNotifHandler();
  403.     }
  404. }
Created with JaCoCo 0.8.12.202403310830