View Javadoc
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   */
17  
18  package org.apache.commons.net.telnet;
19  
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;
25  
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;
38  
39      final int maxSubnegotiationLength;
40      private InputStream input;
41      private OutputStream output;
42      protected boolean readerThread = true;
43      private TelnetInputListener inputListener;
44  
45      /**
46       * Default TelnetClient constructor, sets terminal-type {@code VT100}.
47       */
48      public TelnetClient() {
49          this("VT100", DEFAULT_MAX_SUBNEGOTIATION_LENGTH);
50      }
51  
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      }
60  
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      }
69  
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      }
84  
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     }
106 
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) */
120 
121     void closeOutputStream() throws IOException {
122         if (_output_ == null) {
123             return;
124         }
125         try {
126             _output_.close();
127         } finally {
128             _output_ = null;
129         }
130     }
131 
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     }
144 
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     }
164 
165     void flushOutputStream() throws IOException {
166         if (_output_ == null) {
167             throw new IOException("Stream closed");
168         }
169         _output_.flush();
170     }
171 
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     }
181 
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     }
194 
195     /* Code Section added for supporting AYT (start) */
196 
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     }
206 
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     }
215 
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) */
229 
230     /* open TelnetOptionHandler functionality (start) */
231 
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     }
242 
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     }
263 
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     }
273 
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     }
283 
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     }
299 
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     }
316 
317     /* Code Section added for supporting AYT (start) */
318 
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     }
334 
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     }
355 
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     }
379 
380     /**
381      * Stops spying this TelnetClient.
382      */
383     public void stopSpyStream() {
384         super._stopSpyStream();
385     }
386     /* Code Section added for supporting spystreams (end) */
387 
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     }
396 
397     /**
398      * Unregisters the current notification handler.
399      */
400     @Override
401     public void unregisterNotifHandler() {
402         super.unregisterNotifHandler();
403     }
404 }