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  package org.apache.commons.net.ftp;
18  
19  import java.io.BufferedInputStream;
20  import java.io.BufferedOutputStream;
21  import java.io.BufferedReader;
22  import java.io.BufferedWriter;
23  import java.io.IOException;
24  import java.io.InputStream;
25  import java.io.InputStreamReader;
26  import java.io.OutputStream;
27  import java.io.OutputStreamWriter;
28  import java.io.Reader;
29  import java.net.Inet6Address;
30  import java.net.InetAddress;
31  import java.net.InetSocketAddress;
32  import java.net.ServerSocket;
33  import java.net.Socket;
34  import java.net.SocketException;
35  import java.net.SocketTimeoutException;
36  import java.net.UnknownHostException;
37  import java.nio.charset.StandardCharsets;
38  import java.time.Duration;
39  import java.time.Instant;
40  import java.util.ArrayList;
41  import java.util.Calendar;
42  import java.util.HashMap;
43  import java.util.HashSet;
44  import java.util.Locale;
45  import java.util.Properties;
46  import java.util.Random;
47  import java.util.Set;
48  import java.util.regex.Matcher;
49  
50  import org.apache.commons.net.MalformedServerReplyException;
51  import org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory;
52  import org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory;
53  import org.apache.commons.net.ftp.parser.MLSxEntryParser;
54  import org.apache.commons.net.io.CRLFLineReader;
55  import org.apache.commons.net.io.CopyStreamAdapter;
56  import org.apache.commons.net.io.CopyStreamEvent;
57  import org.apache.commons.net.io.CopyStreamListener;
58  import org.apache.commons.net.io.FromNetASCIIInputStream;
59  import org.apache.commons.net.io.SocketOutputStream;
60  import org.apache.commons.net.io.ToNetASCIIOutputStream;
61  import org.apache.commons.net.io.Util;
62  import org.apache.commons.net.util.NetConstants;
63  
64  /**
65   * FTPClient encapsulates all the functionality necessary to store and retrieve files from an FTP server. This class takes care of all low level details of
66   * interacting with an FTP server and provides a convenient higher level interface. As with all classes derived from
67   * {@link org.apache.commons.net.SocketClient}, you must first connect to the server with {@link org.apache.commons.net.SocketClient#connect connect } before
68   * doing anything, and finally {@link org.apache.commons.net.SocketClient#disconnect() disconnect} after you're completely finished interacting with the server.
69   * Then you need to check the FTP reply code to see if the connection was successful. For example:
70   *
71   * <pre>
72   *    FTPClient ftp = new FTPClient();
73   *    FTPClientConfig config = new FTPClientConfig();
74   *    config.setXXX(YYY); // change required options
75   *    // for example config.setServerTimeZoneId("Pacific/Pitcairn")
76   *    ftp.configure(config );
77   *    boolean error = false;
78   *    try {
79   *      int reply;
80   *      String server = "ftp.example.com";
81   *      ftp.connect(server);
82   *      System.out.println("Connected to " + server + ".");
83   *      System.out.print(ftp.getReplyString());
84   *
85   *      // After connection attempt, you should check the reply code to verify
86   *      // success.
87   *      reply = ftp.getReplyCode();
88   *
89   *      if (!FTPReply.isPositiveCompletion(reply)) {
90   *        ftp.disconnect();
91   *        System.err.println("FTP server refused connection.");
92   *        System.exit(1);
93   *      }
94   *      ... // transfer files
95   *      ftp.logout();
96   *    } catch (IOException e) {
97   *      error = true;
98   *      e.printStackTrace();
99   *    } finally {
100  *      if (ftp.isConnected()) {
101  *        try {
102  *          ftp.disconnect();
103  *        } catch (IOException ioe) {
104  *          // do nothing
105  *        }
106  *      }
107  *      System.exit(error ? 1 : 0);
108  *    }
109  * </pre>
110  * <p>
111  * Immediately after connecting is the only real time you need to check the reply code (because connect is of type void). The convention for all the FTP command
112  * methods in FTPClient is such that they either return a boolean value or some other value. The boolean methods return true on a successful completion reply
113  * from the FTP server and false on a reply resulting in an error condition or failure. The methods returning a value other than boolean return a value
114  * containing the higher level data produced by the FTP command, or null if a reply resulted in an error condition or failure. If you want to access the exact
115  * FTP reply code causing a success or failure, you must call {@link org.apache.commons.net.ftp.FTP#getReplyCode getReplyCode } after a success or failure.
116  * </p>
117  * <p>
118  * The default settings for FTPClient are for it to use <code>FTP.ASCII_FILE_TYPE</code>, <code>FTP.NON_PRINT_TEXT_FORMAT</code>,
119  * <code>FTP.STREAM_TRANSFER_MODE</code>, and <code>FTP.FILE_STRUCTURE</code>. The only file types directly supported are <code>FTP.ASCII_FILE_TYPE</code>
120  * and <code>FTP.BINARY_FILE_TYPE</code>. Because there are at least 4 different EBCDIC encodings, we have opted not to provide direct support for EBCDIC. To
121  * transfer EBCDIC and other unsupported file types you must create your own filter InputStreams and OutputStreams and wrap them around the streams returned or
122  * required by the FTPClient methods. FTPClient uses the {@link ToNetASCIIOutputStream NetASCII} filter streams to provide transparent handling of ASCII files.
123  * We will consider incorporating EBCDIC support if there is enough demand.
124  * </p>
125  * <p>
126  * <code>FTP.NON_PRINT_TEXT_FORMAT</code>, <code>FTP.STREAM_TRANSFER_MODE</code>, and <code>FTP.FILE_STRUCTURE</code> are the only supported formats,
127  * transfer modes, and file structures.
128  * </p>
129  * <p>
130  * Because the handling of sockets on different platforms can differ significantly, the FTPClient automatically issues a new PORT (or EPRT) command prior to
131  * every transfer requiring that the server connect to the client's data port. This ensures identical problem-free behavior on Windows, Unix, and Macintosh
132  * platforms. Additionally, it relieves programmers from having to issue the PORT (or EPRT) command themselves and dealing with platform dependent issues.
133  * </p>
134  * <p>
135  * Additionally, for security purposes, all data connections to the client are verified to ensure that they originated from the intended party (host and port).
136  * If a data connection is initiated by an unexpected party, the command will close the socket and throw an IOException. You may disable this behavior with
137  * {@link #setRemoteVerificationEnabled setRemoteVerificationEnabled()}.
138  * </p>
139  * <p>
140  * You should keep in mind that the FTP server may choose to prematurely close a connection if the client has been idle for longer than a given time period
141  * (usually 900 seconds). The FTPClient class will detect a premature FTP server connection closing when it receives a
142  * {@link org.apache.commons.net.ftp.FTPReply#SERVICE_NOT_AVAILABLE FTPReply.SERVICE_NOT_AVAILABLE } response to a command. When that occurs, the FTP class
143  * method encountering that reply will throw an {@link org.apache.commons.net.ftp.FTPConnectionClosedException} . <code>FTPConnectionClosedException</code> is a
144  * subclass of <code>IOException</code> and therefore need not be caught separately, but if you are going to catch it separately, its catch block must appear
145  * before the more general <code>IOException</code> catch block. When you encounter an {@link org.apache.commons.net.ftp.FTPConnectionClosedException} , you
146  * must disconnect the connection with {@link #disconnect disconnect() } to properly clean up the system resources used by FTPClient. Before disconnecting, you
147  * may check the last reply code and text with {@link org.apache.commons.net.ftp.FTP#getReplyCode getReplyCode },
148  * {@link org.apache.commons.net.ftp.FTP#getReplyString getReplyString }, and {@link org.apache.commons.net.ftp.FTP#getReplyStrings getReplyStrings}. You may
149  * avoid server disconnections while the client is idle by periodically sending NOOP commands to the server.
150  * </p>
151  * <p>
152  * Rather than list it separately for each method, we mention here that every method communicating with the server and throwing an IOException can also throw a
153  * {@link org.apache.commons.net.MalformedServerReplyException} , which is a subclass of IOException. A MalformedServerReplyException will be thrown when the
154  * reply received from the server deviates enough from the protocol specification that it cannot be interpreted in a useful manner despite attempts to be as
155  * lenient as possible.
156  * </p>
157  * <p>
158  * Listing API Examples Both paged and unpaged examples of directory listings are available, as follows:
159  * </p>
160  * <p>
161  * Unpaged (whole list) access, using a parser accessible by auto-detect:
162  * </p>
163  *
164  * <pre>
165  * FTPClient f = new FTPClient();
166  * f.connect(server);
167  * f.login(user, password);
168  * FTPFile[] files = f.listFiles(directory);
169  * </pre>
170  * <p>
171  * Paged access, using a parser not accessible by auto-detect. The class defined in the first parameter of initateListParsing should be derived from
172  * org.apache.commons.net.FTPFileEntryParser:
173  * </p>
174  *
175  * <pre>
176  * FTPClient f = new FTPClient();
177  * f.connect(server);
178  * f.login(user, password);
179  * FTPListParseEngine engine = f.initiateListParsing("com.whatever.YourOwnParser", directory);
180  *
181  * while (engine.hasNext()) {
182  *     FTPFile[] files = engine.getNext(25); // "page size" you want
183  *     // do whatever you want with these files, display them, etc.
184  *     // expensive FTPFile objects not created until needed.
185  * }
186  * </pre>
187  * <p>
188  * Paged access, using a parser accessible by auto-detect:
189  * </p>
190  *
191  * <pre>
192  * FTPClient f = new FTPClient();
193  * f.connect(server);
194  * f.login(user, password);
195  * FTPListParseEngine engine = f.initiateListParsing(directory);
196  *
197  * while (engine.hasNext()) {
198  *     FTPFile[] files = engine.getNext(25); // "page size" you want
199  *     // do whatever you want with these files, display them, etc.
200  *     // expensive FTPFile objects not created until needed.
201  * }
202  * </pre>
203  * <p>
204  * For examples of using FTPClient on servers whose directory listings
205  * </p>
206  * <ul>
207  * <li>use languages other than English</li>
208  * <li>use date formats other than the American English "standard" <code>MM d yyyy</code></li>
209  * <li>are in different time zones and you need accurate timestamps for dependency checking as in Ant</li>
210  * </ul>
211  * see {@link FTPClientConfig FTPClientConfig}.
212  * <p>
213  * <b>Control channel keep-alive feature</b>:
214  * </p>
215  * <p>
216  * <b>Please note:</b> this does not apply to the methods where the user is responsible for writing or reading the data stream, i.e.
217  * {@link #retrieveFileStream(String)} , {@link #storeFileStream(String)} and the other xxxFileStream methods
218  * </p>
219  * <p>
220  * During file transfers, the data connection is busy, but the control connection is idle. FTP servers know that the control connection is in use, so won't
221  * close it through lack of activity, but it's a lot harder for network routers to know that the control and data connections are associated with each other.
222  * Some routers may treat the control connection as idle, and disconnect it if the transfer over the data connection takes longer than the allowable idle time
223  * for the router.
224  * <p>
225  * One solution to this is to send a safe command (i.e. NOOP) over the control connection to reset the router's idle timer. This is enabled as follows:
226  * </p>
227  *
228  * <pre>
229  * // Set timeout to 5 minutes
230  * ftpClient.setControlKeepAliveTimeout(Duration.ofMinutes(5));
231  * </pre>
232  *
233  * <p>
234  * This will cause the file upload/download methods to send a NOOP approximately every 5 minutes. The following public methods support this:
235  * </p>
236  * <ul>
237  * <li>{@link #retrieveFile(String, OutputStream)}</li>
238  * <li>{@link #appendFile(String, InputStream)}</li>
239  * <li>{@link #storeFile(String, InputStream)}</li>
240  * <li>{@link #storeUniqueFile(InputStream)}</li>
241  * <li>{@link #storeUniqueFileStream(String)}</li>
242  * </ul>
243  * <p>
244  * This feature does not apply to the methods where the user is responsible for writing or reading the data stream, i.e. {@link #retrieveFileStream(String)} ,
245  * {@link #storeFileStream(String)} and the other xxxFileStream methods. In such cases, the user is responsible for keeping the control connection alive if
246  * necessary.
247  * </p>
248  * <p>
249  * The implementation currently uses a {@link CopyStreamListener} which is passed to the
250  * {@link Util#copyStream(InputStream, OutputStream, int, long, CopyStreamListener, boolean)} method, so the timing is partially dependent on how long each
251  * block transfer takes.
252  * </p>
253  * <p>
254  * <b>This keep-alive feature is optional; if it does not help or causes problems then don't use it.</b>
255  * </p>
256  *
257  * @see #FTP_SYSTEM_TYPE
258  * @see #SYSTEM_TYPE_PROPERTIES
259  * @see FTP
260  * @see FTPConnectionClosedException
261  * @see FTPFileEntryParser
262  * @see FTPFileEntryParserFactory
263  * @see DefaultFTPFileEntryParserFactory
264  * @see FTPClientConfig
265  * @see org.apache.commons.net.MalformedServerReplyException
266  */
267 public class FTPClient extends FTP implements Configurable {
268 
269     // @since 3.0
270     private static final class CSL implements CopyStreamListener {
271 
272         private final FTPClient parent;
273         private final long idleMillis;
274         private final int currentSoTimeoutMillis;
275 
276         private long lastIdleTimeMillis = System.currentTimeMillis();
277         private int notAcked;
278         private int acksAcked;
279         private int ioErrors;
280 
281         CSL(final FTPClient parent, final Duration idleDuration, final Duration maxWaitDuration) throws SocketException {
282             this.idleMillis = idleDuration.toMillis();
283             this.parent = parent;
284             this.currentSoTimeoutMillis = parent.getSoTimeout();
285             parent.setSoTimeout(DurationUtils.toMillisInt(maxWaitDuration));
286         }
287 
288         @Override
289         public void bytesTransferred(final CopyStreamEvent event) {
290             bytesTransferred(event.getTotalBytesTransferred(), event.getBytesTransferred(), event.getStreamSize());
291         }
292 
293         @Override
294         public void bytesTransferred(final long totalBytesTransferred, final int bytesTransferred, final long streamSize) {
295             final long nowMillis = System.currentTimeMillis();
296             if (nowMillis - lastIdleTimeMillis > idleMillis) {
297                 try {
298                     parent.__noop();
299                     acksAcked++;
300                 } catch (final SocketTimeoutException e) {
301                     notAcked++;
302                 } catch (final IOException e) {
303                     ioErrors++;
304                     // Ignored
305                 }
306                 lastIdleTimeMillis = nowMillis;
307             }
308         }
309 
310         int[] cleanUp() throws IOException {
311             final int remain = notAcked;
312             try {
313                 while (notAcked > 0) {
314                     parent.getReply(); // we do want to see these
315                     notAcked--; // only decrement if actually received
316                 }
317             } catch (final SocketTimeoutException e) { // NET-584
318                 // ignored
319             } finally {
320                 parent.setSoTimeout(currentSoTimeoutMillis);
321             }
322             return new int[] { acksAcked, remain, notAcked, ioErrors }; // debug counts
323         }
324 
325     }
326 
327     /**
328      * Strategy interface for updating host names received from FTP server for passive NAT workaround.
329      *
330      * @since 3.6
331      */
332     public interface HostnameResolver {
333         String resolve(String hostname) throws UnknownHostException;
334     }
335 
336     /**
337      * Default strategy for passive NAT workaround (site-local replies are replaced.)
338      *
339      * @since 3.6
340      */
341     public static class NatServerResolverImpl implements HostnameResolver {
342         private final FTPClient client;
343 
344         public NatServerResolverImpl(final FTPClient client) {
345             this.client = client;
346         }
347 
348         @Override
349         public String resolve(final String hostname) throws UnknownHostException {
350             String newHostname = hostname;
351             final InetAddress host = InetAddress.getByName(newHostname);
352             // reply is a local address, but target is not - assume NAT box changed the PASV reply
353             if (host.isSiteLocalAddress()) {
354                 final InetAddress remote = this.client.getRemoteAddress();
355                 if (!remote.isSiteLocalAddress()) {
356                     newHostname = remote.getHostAddress();
357                 }
358             }
359             return newHostname;
360         }
361     }
362 
363     private static final class PropertiesSingleton {
364 
365         static final Properties PROPERTIES;
366 
367         static {
368             final InputStream resourceAsStream = FTPClient.class.getResourceAsStream(SYSTEM_TYPE_PROPERTIES);
369             Properties p = null;
370             if (resourceAsStream != null) {
371                 p = new Properties();
372                 try {
373                     p.load(resourceAsStream);
374                 } catch (final IOException e) {
375                     // Ignored
376                 } finally {
377                     try {
378                         resourceAsStream.close();
379                     } catch (final IOException e) {
380                         // Ignored
381                     }
382                 }
383             }
384             PROPERTIES = p;
385         }
386 
387     }
388 
389     /**
390      * The system property ({@value}) which can be used to override the system type.<br>
391      * If defined, the value will be used to create any automatically created parsers.
392      *
393      * @since 3.0
394      */
395     public static final String FTP_SYSTEM_TYPE = "org.apache.commons.net.ftp.systemType";
396 
397     /**
398      * The system property ({@value}) which can be used as the default system type.<br>
399      * If defined, the value will be used if the SYST command fails.
400      *
401      * @since 3.1
402      */
403     public static final String FTP_SYSTEM_TYPE_DEFAULT = "org.apache.commons.net.ftp.systemType.default";
404 
405     /**
406      * The system property that defines the default for {@link #isIpAddressFromPasvResponse()}. This property, if present, configures the default for the
407      * following: If the client receives the servers response for a PASV request, then that response will contain an IP address. If this property is true, then
408      * the client will use that IP address, as requested by the server. This is compatible to version {@code 3.8.0}, and before. If this property is false, or
409      * absent, then the client will ignore that IP address, and instead use the remote address of the control connection.
410      *
411      * @see #isIpAddressFromPasvResponse()
412      * @see #setIpAddressFromPasvResponse(boolean)
413      * @since 3.9.0
414      */
415     public static final String FTP_IP_ADDRESS_FROM_PASV_RESPONSE = "org.apache.commons.net.ftp.ipAddressFromPasvResponse";
416 
417     /**
418      * The name of an optional systemType properties file ({@value}), which is loaded using {@link Class#getResourceAsStream(String)}.<br>
419      * The entries are the systemType (as determined by {@link FTPClient#getSystemType}) and the values are the replacement type or parserClass, which is passed
420      * to {@link FTPFileEntryParserFactory#createFileEntryParser(String)}.<br>
421      * For example:
422      *
423      * <pre>
424      * Plan 9=Unix
425      * OS410=org.apache.commons.net.ftp.parser.OS400FTPEntryParser
426      * </pre>
427      *
428      * @since 3.0
429      */
430     public static final String SYSTEM_TYPE_PROPERTIES = "/systemType.properties";
431 
432     /**
433      * A constant indicating the FTP session is expecting all transfers to occur between the client (local) and server and that the server should connect to the
434      * client's data port to initiate a data transfer. This is the default data connection mode when and FTPClient instance is created.
435      */
436     public static final int ACTIVE_LOCAL_DATA_CONNECTION_MODE = 0;
437 
438     /**
439      * A constant indicating the FTP session is expecting all transfers to occur between two remote servers and that the server the client is connected to
440      * should connect to the other server's data port to initiate a data transfer.
441      */
442     public static final int ACTIVE_REMOTE_DATA_CONNECTION_MODE = 1;
443 
444     /**
445      * A constant indicating the FTP session is expecting all transfers to occur between the client (local) and server and that the server is in passive mode,
446      * requiring the client to connect to the server's data port to initiate a transfer.
447      */
448     public static final int PASSIVE_LOCAL_DATA_CONNECTION_MODE = 2;
449 
450     /**
451      * A constant indicating the FTP session is expecting all transfers to occur between two remote servers and that the server the client is connected to is in
452      * passive mode, requiring the other server to connect to the first server's data port to initiate a data transfer.
453      */
454     public static final int PASSIVE_REMOTE_DATA_CONNECTION_MODE = 3;
455 
456     /** Pattern for PASV mode responses. Groups: (n,n,n,n),(n),(n) */
457     private static final java.util.regex.Pattern PARMS_PAT;
458 
459     static {
460         PARMS_PAT = java.util.regex.Pattern.compile("(\\d{1,3},\\d{1,3},\\d{1,3},\\d{1,3}),(\\d{1,3}),(\\d{1,3})");
461     }
462 
463     private static Properties getOverrideProperties() {
464         return PropertiesSingleton.PROPERTIES;
465     }
466 
467     /**
468      * Parse the pathname from a CWD reply.
469      * <p>
470      * According to <a href="http://www.ietf.org/rfc/rfc959.txt">RFC959</a>, it should be the same as for MKD i.e.
471      * {@code 257<space>"<directory-name>"[<space>commentary]} where any double-quotes in {@code <directory-name>} are doubled. Unlike MKD, the commentary is
472      * optional.
473      * </p>
474      * <p>
475      * However, see NET-442 for an exception.
476      * </p>
477      *
478      * @param reply
479      * @return the pathname, without enclosing quotes, or the full string after the reply code and space if the syntax is invalid (i.e. enclosing quotes are
480      *         missing or embedded quotes are not doubled)
481      */
482     // package protected for access by test cases
483     static String parsePathname(final String reply) {
484         final String param = reply.substring(REPLY_CODE_LEN + 1);
485         if (param.startsWith("\"")) {
486             final StringBuilder sb = new StringBuilder();
487             boolean quoteSeen = false;
488             // start after initial quote
489             for (int i = 1; i < param.length(); i++) {
490                 final char ch = param.charAt(i);
491                 if (ch == '"') {
492                     if (quoteSeen) {
493                         sb.append(ch);
494                         quoteSeen = false;
495                     } else {
496                         // don't output yet, in case doubled
497                         quoteSeen = true;
498                     }
499                 } else {
500                     if (quoteSeen) { // found lone trailing quote within string
501                         return sb.toString();
502                     }
503                     sb.append(ch); // just another character
504                 }
505             }
506             if (quoteSeen) { // found lone trailing quote at end of string
507                 return sb.toString();
508             }
509         }
510         // malformed reply, return all after reply code and space
511         return param;
512     }
513 
514     private int dataConnectionMode;
515     private Duration dataTimeout;
516 
517     private int passivePort;
518     private String passiveHost;
519     private final Random random;
520     private int activeMinPort;
521     private int activeMaxPort;
522     private InetAddress activeExternalHost;
523 
524     /** Overrides __activeExternalHost in EPRT/PORT commands. */
525     private InetAddress reportActiveExternalHost;
526 
527     /** The address to bind to on passive connections, if necessary. */
528     private InetAddress passiveLocalHost;
529     private int fileType;
530     @SuppressWarnings("unused") // fields are written, but currently not read
531     private int fileFormat;
532     @SuppressWarnings("unused") // field is written, but currently not read
533     private int fileStructure;
534     private int fileTransferMode;
535 
536     private boolean remoteVerificationEnabled;
537 
538     private long restartOffset;
539 
540     private FTPFileEntryParserFactory parserFactory;
541 
542     private int bufferSize; // for buffered data streams
543 
544     private int sendDataSocketBufferSize;
545 
546     private int receiveDataSocketBufferSize;
547 
548     private boolean listHiddenFiles;
549 
550     private boolean useEPSVwithIPv4; // whether to attempt EPSV with an IPv4 connection
551 
552     // __systemName is a cached value that should not be referenced directly
553     // except when assigned in getSystemName and __initDefaults.
554     private String systemName;
555 
556     // __entryParser is a cached value that should not be referenced directly
557     // except when assigned in listFiles(String, String) and __initDefaults.
558     private FTPFileEntryParser entryParser;
559 
560     // Key used to create the parser; necessary to ensure that the parser type is not ignored
561     private String entryParserKey;
562 
563     private FTPClientConfig configuration;
564 
565     // Listener used by store/retrieve methods to handle keepalive
566     private CopyStreamListener copyStreamListener;
567 
568     // How long to wait before sending another control keep-alive message
569     private Duration controlKeepAliveTimeout = Duration.ZERO;
570 
571     // How long to wait for keepalive message replies before continuing
572     // Most FTP servers don't seem to support concurrent control and data connection usage
573     private Duration controlKeepAliveReplyTimeout = Duration.ofSeconds(1);
574 
575     // Debug counts for NOOP acks
576     private int[] cslDebug;
577 
578     /**
579      * Enable or disable replacement of internal IP in passive mode. Default enabled using {code NatServerResolverImpl}.
580      */
581     private HostnameResolver passiveNatWorkaroundStrategy = new NatServerResolverImpl(this);
582 
583     /** Controls the automatic server encoding detection (only UTF-8 supported). */
584     private boolean autodetectEncoding;
585 
586     /** Map of FEAT responses. If null, has not been initialized. */
587     private HashMap<String, Set<String>> featuresMap;
588 
589     private boolean ipAddressFromPasvResponse = Boolean.getBoolean(FTPClient.FTP_IP_ADDRESS_FROM_PASV_RESPONSE);
590 
591     /**
592      * Default FTPClient constructor. Creates a new FTPClient instance with the data connection mode set to <code>ACTIVE_LOCAL_DATA_CONNECTION_MODE</code>,
593      * the file type set to <code>FTP.ASCII_FILE_TYPE</code>, the file format set to <code>FTP.NON_PRINT_TEXT_FORMAT</code>, the file structure set to
594      * <code>FTP.FILE_STRUCTURE</code>, and the transfer mode set to <code>FTP.STREAM_TRANSFER_MODE</code>.
595      * <p>
596      * The list parsing auto-detect feature can be configured to use lenient future dates (short dates may be up to one day in the future) as follows:
597      * </p>
598      *
599      * <pre>
600      * FTPClient ftp = new FTPClient();
601      * FTPClientConfig config = new FTPClientConfig();
602      * config.setLenientFutureDates(true);
603      * ftp.configure(config);
604      * </pre>
605      */
606     public FTPClient() {
607         initDefaults();
608         dataTimeout = Duration.ofMillis(-1);
609         remoteVerificationEnabled = true;
610         parserFactory = new DefaultFTPFileEntryParserFactory();
611         configuration = null;
612         listHiddenFiles = false;
613         useEPSVwithIPv4 = false;
614         random = new Random();
615         passiveLocalHost = null;
616     }
617 
618     @Override
619     protected void _connectAction_() throws IOException {
620         _connectAction_(null);
621     }
622 
623     /**
624      * @param socketIsReader the reader to reuse (if non-null)
625      * @throws IOException on error
626      * @since 3.4
627      */
628     @Override
629     protected void _connectAction_(final Reader socketIsReader) throws IOException {
630         super._connectAction_(socketIsReader); // sets up _input_ and _output_
631         initDefaults();
632         // must be after super._connectAction_(), because otherwise we get an
633         // Exception claiming we're not connected
634         if (autodetectEncoding) {
635             final ArrayList<String> oldReplyLines = new ArrayList<>(_replyLines);
636             final int oldReplyCode = _replyCode;
637             // UTF-8 appears to be the default
638             if (hasFeature("UTF8") || hasFeature(StandardCharsets.UTF_8.name())) {
639                 setControlEncoding(StandardCharsets.UTF_8.name());
640                 _controlInput_ = new CRLFLineReader(new InputStreamReader(_input_, getControlEncoding()));
641                 _controlOutput_ = new BufferedWriter(new OutputStreamWriter(_output_, getControlEncoding()));
642             }
643             // restore the original reply (server greeting)
644             _replyLines.clear();
645             _replyLines.addAll(oldReplyLines);
646             _replyCode = oldReplyCode;
647             _newReplyString = true;
648         }
649     }
650 
651     /**
652      * Establishes a data connection with the FTP server, returning a Socket for the connection if successful. If a restart offset has been set with
653      * {@link #setRestartOffset(long)}, a REST command is issued to the server with the offset as an argument before establishing the data connection. Active
654      * mode connections also cause a local PORT command to be issued.
655      *
656      * @param command The int representation of the FTP command to send.
657      * @param arg     The arguments to the FTP command. If this parameter is set to null, then the command is sent with no argument.
658      * @return A Socket corresponding to the established data connection. Null is returned if an FTP protocol error is reported at any point during the
659      *         establishment and initialization of the connection.
660      * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
661      * @since 3.3
662      */
663     protected Socket _openDataConnection_(final FTPCmd command, final String arg) throws IOException {
664         return _openDataConnection_(command.getCommand(), arg);
665     }
666 
667     /**
668      * Establishes a data connection with the FTP server, returning a Socket for the connection if successful. If a restart offset has been set with
669      * {@link #setRestartOffset(long)}, a REST command is issued to the server with the offset as an argument before establishing the data connection. Active
670      * mode connections also cause a local PORT command to be issued.
671      *
672      * @deprecated (3.3) Use {@link #_openDataConnection_(FTPCmd, String)} instead
673      * @param command The int representation of the FTP command to send.
674      * @param arg     The arguments to the FTP command. If this parameter is set to null, then the command is sent with no argument.
675      * @return A Socket corresponding to the established data connection. Null is returned if an FTP protocol error is reported at any point during the
676      *         establishment and initialization of the connection.
677      * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
678      */
679     @Deprecated
680     protected Socket _openDataConnection_(final int command, final String arg) throws IOException {
681         return _openDataConnection_(FTPCommand.getCommand(command), arg);
682     }
683 
684     /**
685      * Establishes a data connection with the FTP server, returning a Socket for the connection if successful. If a restart offset has been set with
686      * {@link #setRestartOffset(long)}, a REST command is issued to the server with the offset as an argument before establishing the data connection. Active
687      * mode connections also cause a local PORT command to be issued.
688      *
689      * @param command The text representation of the FTP command to send.
690      * @param arg     The arguments to the FTP command. If this parameter is set to null, then the command is sent with no argument.
691      * @return A Socket corresponding to the established data connection. Null is returned if an FTP protocol error is reported at any point during the
692      *         establishment and initialization of the connection.
693      * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
694      * @since 3.1
695      */
696     protected Socket _openDataConnection_(final String command, final String arg) throws IOException {
697         if (dataConnectionMode != ACTIVE_LOCAL_DATA_CONNECTION_MODE && dataConnectionMode != PASSIVE_LOCAL_DATA_CONNECTION_MODE) {
698             return null;
699         }
700         final boolean isInet6Address = getRemoteAddress() instanceof Inet6Address;
701         final Socket socket;
702         final int soTimeoutMillis = DurationUtils.toMillisInt(dataTimeout);
703         if (dataConnectionMode == ACTIVE_LOCAL_DATA_CONNECTION_MODE) {
704             // if no activePortRange was set (correctly) -> getActivePort() = 0
705             // -> new ServerSocket(0) -> bind to any free local port
706             try (final ServerSocket server = _serverSocketFactory_.createServerSocket(getActivePort(), 1, getHostAddress())) {
707                 // Try EPRT only if remote server is over IPv6, if not use PORT,
708                 // because EPRT has no advantage over PORT on IPv4.
709                 // It could even have the disadvantage,
710                 // that EPRT will make the data connection fail, because
711                 // today's intelligent NAT Firewalls are able to
712                 // substitute IP addresses in the PORT command,
713                 // but might not be able to recognize the EPRT command.
714                 if (isInet6Address) {
715                     if (!FTPReply.isPositiveCompletion(eprt(getReportHostAddress(), server.getLocalPort()))) {
716                         return null;
717                     }
718                 } else if (!FTPReply.isPositiveCompletion(port(getReportHostAddress(), server.getLocalPort()))) {
719                     return null;
720                 }
721                 if (restartOffset > 0 && !restart(restartOffset)) {
722                     return null;
723                 }
724                 if (!FTPReply.isPositivePreliminary(sendCommand(command, arg))) {
725                     return null;
726                 }
727                 // For now, let's just use the data timeout value for waiting for
728                 // the data connection. It may be desirable to let this be a
729                 // separately configurable value. In any case, we really want
730                 // to allow preventing the accept from blocking indefinitely.
731                 if (soTimeoutMillis >= 0) {
732                     server.setSoTimeout(soTimeoutMillis);
733                 }
734                 socket = wrapOnDeflate(server.accept());
735                 // Ensure the timeout is set before any commands are issued on the new socket
736                 if (soTimeoutMillis >= 0) {
737                     socket.setSoTimeout(soTimeoutMillis);
738                 }
739                 if (receiveDataSocketBufferSize > 0) {
740                     socket.setReceiveBufferSize(receiveDataSocketBufferSize);
741                 }
742                 if (sendDataSocketBufferSize > 0) {
743                     socket.setSendBufferSize(sendDataSocketBufferSize);
744                 }
745             }
746         } else {
747             // We must be in PASSIVE_LOCAL_DATA_CONNECTION_MODE
748             // Try EPSV command first on IPv6 - and IPv4 if enabled.
749             // When using IPv4 with NAT it has the advantage
750             // to work with more rare configurations.
751             // E.g. if FTP server has a static PASV address (external network)
752             // and the client is coming from another internal network.
753             // In that case the data connection after PASV command would fail,
754             // while EPSV would make the client succeed by taking just the port.
755             final boolean attemptEPSV = isUseEPSVwithIPv4() || isInet6Address;
756             if (attemptEPSV && epsv() == FTPReply.ENTERING_EPSV_MODE) {
757                 _parseExtendedPassiveModeReply(_replyLines.get(0));
758             } else {
759                 if (isInet6Address) {
760                     return null; // Must use EPSV for IPV6
761                 }
762                 // If EPSV failed on IPV4, revert to PASV
763                 if (pasv() != FTPReply.ENTERING_PASSIVE_MODE) {
764                     return null;
765                 }
766                 _parsePassiveModeReply(_replyLines.get(0));
767             }
768             socket = wrapOnDeflate(_socketFactory_.createSocket());
769             if (receiveDataSocketBufferSize > 0) {
770                 socket.setReceiveBufferSize(receiveDataSocketBufferSize);
771             }
772             if (sendDataSocketBufferSize > 0) {
773                 socket.setSendBufferSize(sendDataSocketBufferSize);
774             }
775             if (passiveLocalHost != null) {
776                 socket.bind(new InetSocketAddress(passiveLocalHost, 0));
777             }
778             // For now, let's just use the data timeout value for waiting for
779             // the data connection. It may be desirable to let this be a
780             // separately configurable value. In any case, we really want
781             // to allow preventing the accept from blocking indefinitely.
782             if (soTimeoutMillis >= 0) {
783                 socket.setSoTimeout(soTimeoutMillis);
784             }
785             socket.connect(new InetSocketAddress(passiveHost, passivePort), connectTimeout);
786             if (restartOffset > 0 && !restart(restartOffset)) {
787                 socket.close();
788                 return null;
789             }
790             if (!FTPReply.isPositivePreliminary(sendCommand(command, arg))) {
791                 socket.close();
792                 return null;
793             }
794         }
795         if (remoteVerificationEnabled && !verifyRemote(socket)) {
796             // Grab the host before we close the socket to avoid NET-663
797             final InetAddress socketHost = socket.getInetAddress();
798             socket.close();
799             throw new IOException(
800                     "Host attempting data connection " + socketHost.getHostAddress() + " is not same as server " + getRemoteAddress().getHostAddress());
801         }
802         return socket;
803     }
804 
805     protected void _parseExtendedPassiveModeReply(String reply) throws MalformedServerReplyException {
806         reply = reply.substring(reply.indexOf('(') + 1, reply.indexOf(')')).trim();
807         final char delim1 = reply.charAt(0);
808         final char delim2 = reply.charAt(1);
809         final char delim3 = reply.charAt(2);
810         final char delim4 = reply.charAt(reply.length() - 1);
811         if (delim1 != delim2 || delim2 != delim3 || delim3 != delim4) {
812             throw new MalformedServerReplyException("Could not parse extended passive host information.\nServer Reply: " + reply);
813         }
814         final int port;
815         try {
816             port = Integer.parseInt(reply.substring(3, reply.length() - 1));
817         } catch (final NumberFormatException e) {
818             throw new MalformedServerReplyException("Could not parse extended passive host information.\nServer Reply: " + reply);
819         }
820         // in EPSV mode, the passive host address is implicit
821         this.passiveHost = getRemoteAddress().getHostAddress();
822         this.passivePort = port;
823     }
824 
825     /**
826      * @since 3.1
827      * @param reply the reply to parse
828      * @throws MalformedServerReplyException if the server reply does not match (n,n,n,n),(n),(n)
829      */
830     protected void _parsePassiveModeReply(final String reply) throws MalformedServerReplyException {
831         final Matcher m = PARMS_PAT.matcher(reply);
832         if (!m.find()) {
833             throw new MalformedServerReplyException("Could not parse passive host information.\nServer Reply: " + reply);
834         }
835         int pasvPort;
836         // Fix up to look like IP address
837         String pasvHost = "0,0,0,0".equals(m.group(1)) ? _socket_.getInetAddress().getHostAddress() : m.group(1).replace(',', '.');
838         try {
839             final int oct1 = Integer.parseInt(m.group(2));
840             final int oct2 = Integer.parseInt(m.group(3));
841             pasvPort = oct1 << 8 | oct2;
842         } catch (final NumberFormatException e) {
843             throw new MalformedServerReplyException("Could not parse passive port information.\nServer Reply: " + reply);
844         }
845         if (isIpAddressFromPasvResponse()) {
846             // Pre-3.9.0 behavior
847             if (passiveNatWorkaroundStrategy != null) {
848                 try {
849                     final String newPassiveHost = passiveNatWorkaroundStrategy.resolve(pasvHost);
850                     if (!pasvHost.equals(newPassiveHost)) {
851                         fireReplyReceived(0, "[Replacing PASV mode reply address " + this.passiveHost + " with " + newPassiveHost + "]\n");
852                         pasvHost = newPassiveHost;
853                     }
854                 } catch (final UnknownHostException e) { // Should not happen as we are passing in an IP address
855                     throw new MalformedServerReplyException("Could not parse passive host information.\nServer Reply: " + reply);
856                 }
857             }
858         } else if (_socket_ == null) {
859             pasvHost = null; // For unit testing.
860         } else {
861             pasvHost = _socket_.getInetAddress().getHostAddress();
862         }
863         this.passiveHost = pasvHost;
864         this.passivePort = pasvPort;
865     }
866 
867     /**
868      * @param command the command to get
869      * @param remote  the remote file name
870      * @param local   The local OutputStream to which to write the file.
871      * @return true if successful
872      * @throws IOException on error
873      * @since 3.1
874      */
875     protected boolean _retrieveFile(final String command, final String remote, final OutputStream local) throws IOException {
876         final Socket socket = _openDataConnection_(command, remote);
877         if (socket == null) {
878             return false;
879         }
880         InputStream input = null;
881         CSL csl = null;
882         try {
883             try {
884                 if (fileType == ASCII_FILE_TYPE) {
885                     input = new FromNetASCIIInputStream(getBufferedInputStream(socket.getInputStream()));
886                 } else {
887                     input = getBufferedInputStream(socket.getInputStream());
888                 }
889 
890                 if (DurationUtils.isPositive(controlKeepAliveTimeout)) {
891                     csl = new CSL(this, controlKeepAliveTimeout, controlKeepAliveReplyTimeout);
892                 }
893 
894                 // Treat everything else as binary for now
895                 Util.copyStream(input, local, getBufferSize(), CopyStreamEvent.UNKNOWN_STREAM_SIZE, mergeListeners(csl), false);
896             } finally {
897                 Util.closeQuietly(input);
898             }
899             // Get the transfer response
900             return completePendingCommand();
901         } finally {
902             Util.closeQuietly(socket);
903             if (csl != null) {
904                 cslDebug = csl.cleanUp(); // fetch any outstanding keepalive replies
905             }
906         }
907     }
908 
909     /**
910      * @param command the command to send
911      * @param remote  the remote file name
912      * @return the stream from which to read the file
913      * @throws IOException on error
914      * @since 3.1
915      */
916     protected InputStream _retrieveFileStream(final String command, final String remote) throws IOException {
917         final Socket socket = _openDataConnection_(command, remote);
918         if (socket == null) {
919             return null;
920         }
921         final InputStream input;
922         if (fileType == ASCII_FILE_TYPE) {
923             // We buffer ascii transfers because the buffering has to
924             // be interposed between FromNetASCIIOutputSream and the underlying
925             // socket input stream. We don't buffer binary transfers
926             // because we don't want to impose a buffering policy on the
927             // programmer if possible. Programmers can decide on their
928             // own if they want to wrap the SocketInputStream we return
929             // for file types other than ASCII.
930             input = new FromNetASCIIInputStream(getBufferedInputStream(socket.getInputStream()));
931         } else {
932             input = socket.getInputStream();
933         }
934         return new org.apache.commons.net.io.SocketInputStream(socket, input);
935     }
936 
937     /**
938      * @since 3.1
939      * @param command the command to send
940      * @param remote  the remote file name
941      * @param local   The local InputStream from which to read the data to be written/appended to the remote file.
942      * @return true if successful
943      * @throws IOException on error
944      */
945     protected boolean _storeFile(final String command, final String remote, final InputStream local) throws IOException {
946         final Socket socket = _openDataConnection_(command, remote);
947         if (socket == null) {
948             return false;
949         }
950         final OutputStream output;
951         if (fileType == ASCII_FILE_TYPE) {
952             output = new ToNetASCIIOutputStream(getBufferedOutputStream(socket.getOutputStream()));
953         } else {
954             output = getBufferedOutputStream(socket.getOutputStream());
955         }
956         CSL csl = null;
957         if (DurationUtils.isPositive(controlKeepAliveTimeout)) {
958             csl = new CSL(this, controlKeepAliveTimeout, controlKeepAliveReplyTimeout);
959         }
960         // Treat everything else as binary for now
961         try {
962             Util.copyStream(local, output, getBufferSize(), CopyStreamEvent.UNKNOWN_STREAM_SIZE, mergeListeners(csl), false);
963             output.close(); // ensure the file is fully written
964             socket.close(); // done writing the file
965             // Get the transfer response
966             return completePendingCommand();
967         } catch (final IOException e) {
968             Util.closeQuietly(output); // ignore close errors here
969             Util.closeQuietly(socket); // ignore close errors here
970             throw e;
971         } finally {
972             if (csl != null) {
973                 cslDebug = csl.cleanUp(); // fetch any outstanding keepalive replies
974             }
975         }
976     }
977 
978     /**
979      * @param command the command to send
980      * @param remote  the remote file name
981      * @return the output stream to write to
982      * @throws IOException on error
983      * @since 3.1
984      */
985     protected OutputStream _storeFileStream(final String command, final String remote) throws IOException {
986         final Socket socket = _openDataConnection_(command, remote);
987         if (socket == null) {
988             return null;
989         }
990         final OutputStream output;
991         if (fileType == ASCII_FILE_TYPE) {
992             // We buffer ascii transfers because the buffering has to
993             // be interposed between ToNetASCIIOutputSream and the underlying
994             // socket output stream. We don't buffer binary transfers
995             // because we don't want to impose a buffering policy on the
996             // programmer if possible. Programmers can decide on their
997             // own if they want to wrap the SocketOutputStream we return
998             // for file types other than ASCII.
999             output = new ToNetASCIIOutputStream(getBufferedOutputStream(socket.getOutputStream()));
1000         } else {
1001             output = socket.getOutputStream();
1002         }
1003         return new SocketOutputStream(socket, output);
1004     }
1005 
1006     /**
1007      * Abort a transfer in progress.
1008      *
1009      * @return True if successfully completed, false if not.
1010      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1011      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1012      *                                      independently as itself.
1013      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1014      */
1015     public boolean abort() throws IOException {
1016         return FTPReply.isPositiveCompletion(abor());
1017     }
1018 
1019     /**
1020      * Reserve a number of bytes on the server for the next file transfer.
1021      *
1022      * @param bytes The number of bytes which the server should allocate.
1023      * @return True if successfully completed, false if not.
1024      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1025      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1026      *                                      independently as itself.
1027      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1028      */
1029     public boolean allocate(final int bytes) throws IOException {
1030         return FTPReply.isPositiveCompletion(allo(bytes));
1031     }
1032 
1033     /**
1034      * Reserve space on the server for the next file transfer.
1035      *
1036      * @param bytes      The number of bytes which the server should allocate.
1037      * @param recordSize The size of a file record.
1038      * @return True if successfully completed, false if not.
1039      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1040      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1041      *                                      independently as itself.
1042      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1043      */
1044     public boolean allocate(final int bytes, final int recordSize) throws IOException {
1045         return FTPReply.isPositiveCompletion(allo(bytes, recordSize));
1046     }
1047 
1048     /**
1049      * Reserve a number of bytes on the server for the next file transfer.
1050      *
1051      * @param bytes The number of bytes which the server should allocate.
1052      * @return True if successfully completed, false if not.
1053      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1054      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1055      *                                      independently as itself.
1056      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1057      */
1058     public boolean allocate(final long bytes) throws IOException {
1059         return FTPReply.isPositiveCompletion(allo(bytes));
1060     }
1061 
1062     /**
1063      * Reserve space on the server for the next file transfer.
1064      *
1065      * @param bytes      The number of bytes which the server should allocate.
1066      * @param recordSize The size of a file record.
1067      * @return True if successfully completed, false if not.
1068      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1069      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1070      *                                      independently as itself.
1071      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1072      */
1073     public boolean allocate(final long bytes, final int recordSize) throws IOException {
1074         return FTPReply.isPositiveCompletion(allo(bytes, recordSize));
1075     }
1076 
1077     /**
1078      * Appends to a file on the server with the given name, taking input from the given InputStream. This method does NOT close the given InputStream. If the
1079      * current file type is ASCII, line separators in the file are transparently converted to the NETASCII format (i.e., you should not attempt to create a
1080      * special InputStream to do this).
1081      *
1082      * @param remote The name of the remote file.
1083      * @param local  The local InputStream from which to read the data to be appended to the remote file.
1084      * @return True if successfully completed, false if not.
1085      * @throws FTPConnectionClosedException                  If the FTP server prematurely closes the connection as a result of the client being idle or some
1086      *                                                       other reason causing the server to send FTP reply code 421. This exception may be caught either as
1087      *                                                       an IOException or independently as itself.
1088      * @throws org.apache.commons.net.io.CopyStreamException If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to
1089      *                                                       determine the number of bytes transferred and the IOException causing the error. This exception may
1090      *                                                       be caught either as an IOException or independently as itself.
1091      * @throws IOException                                   If an I/O error occurs while either sending a command to the server or receiving a reply from the
1092      *                                                       server.
1093      */
1094     public boolean appendFile(final String remote, final InputStream local) throws IOException {
1095         return storeFile(FTPCmd.APPE, remote, local);
1096     }
1097 
1098     /**
1099      * Returns an OutputStream through which data can be written to append to a file on the server with the given name. If the current file type is ASCII, the
1100      * returned OutputStream will convert line separators in the file to the NETASCII format (i.e., you should not attempt to create a special OutputStream to
1101      * do this). You must close the OutputStream when you finish writing to it. The OutputStream itself will take care of closing the parent data connection
1102      * socket upon being closed.
1103      * <p>
1104      * <b>To finalize the file transfer you must call {@link #completePendingCommand completePendingCommand } and check its return value to verify success.</b>
1105      * If this is not done, subsequent commands may behave unexpectedly.
1106      * </p>
1107      *
1108      * @param remote The name of the remote file.
1109      * @return An OutputStream through which the remote file can be appended. If the data connection cannot be opened (e.g., the file does not exist), null is
1110      *         returned (in which case you may check the reply code to determine the exact reason for failure).
1111      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1112      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1113      *                                      independently as itself.
1114      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1115      */
1116     public OutputStream appendFileStream(final String remote) throws IOException {
1117         return storeFileStream(FTPCmd.APPE, remote);
1118     }
1119 
1120     /**
1121      * Change to the parent directory of the current working directory.
1122      *
1123      * @return True if successfully completed, false if not.
1124      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1125      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1126      *                                      independently as itself.
1127      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1128      */
1129     public boolean changeToParentDirectory() throws IOException {
1130         return FTPReply.isPositiveCompletion(cdup());
1131     }
1132 
1133     /**
1134      * Change the current working directory of the FTP session.
1135      *
1136      * @param pathname The new current working directory.
1137      * @return True if successfully completed, false if not.
1138      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1139      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1140      *                                      independently as itself.
1141      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1142      */
1143     public boolean changeWorkingDirectory(final String pathname) throws IOException {
1144         return FTPReply.isPositiveCompletion(cwd(pathname));
1145     }
1146 
1147     /**
1148      * There are a few FTPClient methods that do not complete the entire sequence of FTP commands to complete a transaction. These commands require some action
1149      * by the programmer after the reception of a positive intermediate command. After the programmer's code completes its actions, it must call this method to
1150      * receive the completion reply from the server and verify the success of the entire transaction.
1151      * <p>
1152      * For example,
1153      * </p>
1154      *
1155      * <pre>
1156      * InputStream input;
1157      * OutputStream output;
1158      * input  = new FileInputStream("foobaz.txt");
1159      * output = ftp.storeFileStream("foobar.txt")
1160      * if (!FTPReply.isPositiveIntermediate(ftp.getReplyCode())) {
1161      *     input.close();
1162      *     output.close();
1163      *     ftp.logout();
1164      *     ftp.disconnect();
1165      *     System.err.println("File transfer failed.");
1166      *     System.exit(1);
1167      * }
1168      * Util.copyStream(input, output);
1169      * input.close();
1170      * output.close();
1171      * // Must call completePendingCommand() to finish command.
1172      * if (!ftp.completePendingCommand()) {
1173      *     ftp.logout();
1174      *     ftp.disconnect();
1175      *     System.err.println("File transfer failed.");
1176      *     System.exit(1);
1177      * }
1178      * </pre>
1179      *
1180      * @return True if successfully completed, false if not.
1181      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1182      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1183      *                                      independently as itself.
1184      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1185      */
1186     public boolean completePendingCommand() throws IOException {
1187         return FTPReply.isPositiveCompletion(getReply());
1188     }
1189 
1190     /**
1191      * Implements the {@link Configurable} interface. In the case of this class, configuring merely makes the config object available for
1192      * the factory methods that construct parsers.
1193      *
1194      * @param config {@link FTPClientConfig} object used to provide non-standard configurations to the parser.
1195      * @since 1.4
1196      */
1197     @Override
1198     public void configure(final FTPClientConfig config) {
1199         this.configuration = config;
1200     }
1201 
1202     // package access for test purposes
1203     void createParser(final String parserKey) throws IOException {
1204         // We cache the value to avoid creation of a new object every
1205         // time a file listing is generated.
1206         // Note: we don't check against a null parserKey (NET-544)
1207         if (entryParser == null || parserKey != null && !entryParserKey.equals(parserKey)) {
1208             if (null != parserKey) {
1209                 // if a parser key was supplied in the parameters,
1210                 // use that to create the parser
1211                 entryParser = parserFactory.createFileEntryParser(parserKey);
1212                 entryParserKey = parserKey;
1213 
1214             } else // if no parserKey was supplied, check for a configuration
1215             // in the params, and if it has a non-empty system type, use that.
1216             if (null != configuration && configuration.getServerSystemKey().length() > 0) {
1217                 entryParser = parserFactory.createFileEntryParser(configuration);
1218                 entryParserKey = configuration.getServerSystemKey();
1219             } else {
1220                 // if a parserKey hasn't been supplied, and a configuration
1221                 // hasn't been supplied, and the override property is not set
1222                 // then autodetect by calling
1223                 // the SYST command and use that to choose the parser.
1224                 String systemType = System.getProperty(FTP_SYSTEM_TYPE);
1225                 if (systemType == null) {
1226                     systemType = getSystemType(); // cannot be null
1227                     final Properties override = getOverrideProperties();
1228                     if (override != null) {
1229                         final String newType = override.getProperty(systemType);
1230                         if (newType != null) {
1231                             systemType = newType;
1232                         }
1233                     }
1234                 }
1235                 if (null != configuration) { // system type must have been empty above
1236                     entryParser = parserFactory.createFileEntryParser(new FTPClientConfig(systemType, configuration));
1237                 } else {
1238                     entryParser = parserFactory.createFileEntryParser(systemType);
1239                 }
1240                 entryParserKey = systemType;
1241             }
1242         }
1243     }
1244 
1245     /**
1246      * Deletes a file on the FTP server.
1247      *
1248      * @param pathname The pathname of the file to be deleted.
1249      * @return True if successfully completed, false if not.
1250      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1251      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1252      *                                      independently as itself.
1253      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1254      */
1255     public boolean deleteFile(final String pathname) throws IOException {
1256         return FTPReply.isPositiveCompletion(dele(pathname));
1257     }
1258 
1259     /**
1260      * Closes the connection to the FTP server and restores connection parameters to the default values.
1261      *
1262      * @throws IOException If an error occurs while disconnecting.
1263      */
1264     @Override
1265     public void disconnect() throws IOException {
1266         super.disconnect();
1267         initDefaults();
1268     }
1269 
1270     /**
1271      * Issue a command and wait for the reply.
1272      * <p>
1273      * Should only be used with commands that return replies on the command channel - do not use for LIST, NLST, MLSD etc.
1274      *
1275      * @param command The command to invoke
1276      * @param params  The parameters string, may be {@code null}
1277      * @return True if successfully completed, false if not, in which case call {@link #getReplyCode()} or {@link #getReplyString()} to get the reason.
1278      *
1279      * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1280      * @since 3.0
1281      */
1282     public boolean doCommand(final String command, final String params) throws IOException {
1283         return FTPReply.isPositiveCompletion(sendCommand(command, params));
1284     }
1285 
1286     /**
1287      * Issue a command and wait for the reply, returning it as an array of strings.
1288      * <p>
1289      * Should only be used with commands that return replies on the command channel - do not use for LIST, NLST, MLSD etc.
1290      * </p>
1291      *
1292      * @param command The command to invoke
1293      * @param params  The parameters string, may be {@code null}
1294      * @return The array of replies, or {@code null} if the command failed, in which case call {@link #getReplyCode()} or {@link #getReplyString()} to get the
1295      *         reason.
1296      *
1297      * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1298      * @since 3.0
1299      */
1300     public String[] doCommandAsStrings(final String command, final String params) throws IOException {
1301         final boolean success = FTPReply.isPositiveCompletion(sendCommand(command, params));
1302         if (success) {
1303             return getReplyStrings();
1304         }
1305         return null;
1306     }
1307 
1308     /**
1309      * Sets the current data connection mode to <code>ACTIVE_LOCAL_DATA_CONNECTION_MODE</code>. No communication with the FTP server is conducted, but this
1310      * causes all future data transfers to require the FTP server to connect to the client's data port. Additionally, to accommodate differences between socket
1311      * implementations on different platforms, this method causes the client to issue a PORT command before every data transfer.
1312      */
1313     public void enterLocalActiveMode() {
1314         dataConnectionMode = ACTIVE_LOCAL_DATA_CONNECTION_MODE;
1315         passiveHost = null;
1316         passivePort = -1;
1317     }
1318 
1319     /**
1320      * Sets the current data connection mode to <code>PASSIVE_LOCAL_DATA_CONNECTION_MODE</code>. Use this method only for data transfers between the client
1321      * and server. This method causes a PASV (or EPSV) command to be issued to the server before the opening of every data connection, telling the server to
1322      * open a data port to which the client will connect to conduct data transfers. The FTPClient will stay in <code>PASSIVE_LOCAL_DATA_CONNECTION_MODE</code>
1323      * until the mode is changed by calling some other method such as {@link #enterLocalActiveMode enterLocalActiveMode() }
1324      * <p>
1325      * <b>N.B.</b> currently calling any connect method will reset the mode to ACTIVE_LOCAL_DATA_CONNECTION_MODE.
1326      * </p>
1327      */
1328     public void enterLocalPassiveMode() {
1329         dataConnectionMode = PASSIVE_LOCAL_DATA_CONNECTION_MODE;
1330         // These will be set when just before a data connection is opened
1331         // in _openDataConnection_()
1332         passiveHost = null;
1333         passivePort = -1;
1334     }
1335 
1336     /**
1337      * Sets the current data connection mode to <code>ACTIVE_REMOTE_DATA_CONNECTION</code>. Use this method only for server to server data transfers. This
1338      * method issues a PORT command to the server, indicating the other server and port to which it should connect for data transfers. You must call this method
1339      * before EVERY server to server transfer attempt. The FTPClient will NOT automatically continue to issue PORT commands. You also must remember to call
1340      * {@link #enterLocalActiveMode enterLocalActiveMode() } if you wish to return to the normal data connection mode.
1341      *
1342      * @param host The passive mode server accepting connections for data transfers.
1343      * @param port The passive mode server's data port.
1344      * @return True if successfully completed, false if not.
1345      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1346      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1347      *                                      independently as itself.
1348      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1349      */
1350     public boolean enterRemoteActiveMode(final InetAddress host, final int port) throws IOException {
1351         if (FTPReply.isPositiveCompletion(port(host, port))) {
1352             dataConnectionMode = ACTIVE_REMOTE_DATA_CONNECTION_MODE;
1353             passiveHost = null;
1354             passivePort = -1;
1355             return true;
1356         }
1357         return false;
1358     }
1359 
1360     /**
1361      * Sets the current data connection mode to <code>PASSIVE_REMOTE_DATA_CONNECTION_MODE</code>. Use this method only for server to server data transfers.
1362      * This method issues a PASV command to the server, telling it to open a data port to which the active server will connect to conduct data transfers. You
1363      * must call this method before EVERY server to server transfer attempt. The FTPClient will NOT automatically continue to issue PASV commands. You also must
1364      * remember to call {@link #enterLocalActiveMode enterLocalActiveMode() } if you wish to return to the normal data connection mode.
1365      *
1366      * @return True if successfully completed, false if not.
1367      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1368      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1369      *                                      independently as itself.
1370      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1371      */
1372     public boolean enterRemotePassiveMode() throws IOException {
1373         if (pasv() != FTPReply.ENTERING_PASSIVE_MODE) {
1374             return false;
1375         }
1376         dataConnectionMode = PASSIVE_REMOTE_DATA_CONNECTION_MODE;
1377         _parsePassiveModeReply(_replyLines.get(0));
1378         return true;
1379     }
1380 
1381     /**
1382      * Queries the server for supported features. The server may reply with a list of server-supported extensions. For example, a typical client-server
1383      * interaction might be (from RFC 2389):
1384      *
1385      * <pre>
1386         C&gt; feat
1387         S&gt; 211-Extensions supported:
1388         S&gt;  MLST size*;create;modify*;perm;media-type
1389         S&gt;  SIZE
1390         S&gt;  COMPRESSION
1391         S&gt;  MDTM
1392         S&gt; 211 END
1393      * </pre>
1394      *
1395      * @see <a href="http://www.faqs.org/rfcs/rfc2389.html">http://www.faqs.org/rfcs/rfc2389.html</a>
1396      * @return True if successfully completed, false if not.
1397      * @throws IOException on error
1398      * @since 2.2
1399      */
1400     public boolean features() throws IOException {
1401         return FTPReply.isPositiveCompletion(feat());
1402     }
1403 
1404     /**
1405      * Queries the server for a supported feature, and returns its value (if any). Caches the parsed response to avoid resending the command repeatedly.
1406      *
1407      * @param feature the feature to check
1408      *
1409      * @return if the feature is present, returns the feature value or the empty string if the feature exists but has no value. Returns {@code null} if the
1410      *         feature is not found or the command failed. Check {@link #getReplyCode()} or {@link #getReplyString()} if so.
1411      * @throws IOException on error
1412      * @since 3.0
1413      */
1414     public String featureValue(final String feature) throws IOException {
1415         final String[] values = featureValues(feature);
1416         if (values != null) {
1417             return values[0];
1418         }
1419         return null;
1420     }
1421 
1422     /**
1423      * Queries the server for a supported feature, and returns its values (if any). Caches the parsed response to avoid resending the command repeatedly.
1424      *
1425      * @param feature the feature to check
1426      *
1427      * @return if the feature is present, returns the feature values (empty array if none) Returns {@code null} if the feature is not found or the command
1428      *         failed. Check {@link #getReplyCode()} or {@link #getReplyString()} if so.
1429      * @throws IOException on error
1430      * @since 3.0
1431      */
1432     public String[] featureValues(final String feature) throws IOException {
1433         if (!initFeatureMap()) {
1434             return null;
1435         }
1436         final Set<String> entries = featuresMap.get(feature.toUpperCase(Locale.ENGLISH));
1437         if (entries != null) {
1438             return entries.toArray(NetConstants.EMPTY_STRING_ARRAY);
1439         }
1440         return null;
1441     }
1442 
1443     /**
1444      * Gets the client port for active mode.
1445      *
1446      * @return The client port for active mode.
1447      */
1448     int getActivePort() {
1449         if (activeMinPort > 0 && activeMaxPort >= activeMinPort) {
1450             if (activeMaxPort == activeMinPort) {
1451                 return activeMaxPort;
1452             }
1453             // Get a random port between the min and max port range
1454             return random.nextInt(activeMaxPort - activeMinPort + 1) + activeMinPort;
1455         }
1456         // default port
1457         return 0;
1458     }
1459 
1460     /**
1461      * Tells if automatic server encoding detection is enabled or disabled.
1462      *
1463      * @return true, if automatic server encoding detection is enabled.
1464      */
1465     public boolean getAutodetectUTF8() {
1466         return autodetectEncoding;
1467     }
1468 
1469     private InputStream getBufferedInputStream(final InputStream inputStream) {
1470         if (bufferSize > 0) {
1471             return new BufferedInputStream(inputStream, bufferSize);
1472         }
1473         return new BufferedInputStream(inputStream);
1474     }
1475 
1476     private OutputStream getBufferedOutputStream(final OutputStream outputStream) {
1477         if (bufferSize > 0) {
1478             return new BufferedOutputStream(outputStream, bufferSize);
1479         }
1480         return new BufferedOutputStream(outputStream);
1481     }
1482 
1483     /**
1484      * Retrieve the current internal buffer size for buffered data streams.
1485      *
1486      * @return The current buffer size.
1487      */
1488     public int getBufferSize() {
1489         return bufferSize;
1490     }
1491 
1492     /**
1493      * Gets how long to wait for control keep-alive message replies.
1494      *
1495      * @deprecated Use {@link #getControlKeepAliveReplyTimeoutDuration()}.
1496      * @return wait time in milliseconds.
1497      * @since 3.0
1498      */
1499     @Deprecated
1500     public int getControlKeepAliveReplyTimeout() {
1501         return DurationUtils.toMillisInt(controlKeepAliveReplyTimeout);
1502     }
1503 
1504     /**
1505      * Gets how long to wait for control keep-alive message replies.
1506      *
1507      * @return wait time.
1508      * @since 3.9.0
1509      */
1510     public Duration getControlKeepAliveReplyTimeoutDuration() {
1511         return controlKeepAliveReplyTimeout;
1512     }
1513 
1514     /**
1515      * Gets the time to wait between sending control connection keepalive messages when processing file upload or download.
1516      * <p>
1517      * See the class Javadoc section "Control channel keep-alive feature"
1518      * </p>
1519      *
1520      * @deprecated Use {@link #getControlKeepAliveTimeoutDuration()}.
1521      * @return the number of seconds between keepalive messages.
1522      * @since 3.0
1523      */
1524     @Deprecated
1525     public long getControlKeepAliveTimeout() {
1526         return controlKeepAliveTimeout.getSeconds();
1527     }
1528 
1529     /**
1530      * Gets the time to wait between sending control connection keepalive messages when processing file upload or download.
1531      * <p>
1532      * See the class Javadoc section "Control channel keep-alive feature"
1533      * </p>
1534      *
1535      * @return the duration between keepalive messages.
1536      * @since 3.9.0
1537      */
1538     public Duration getControlKeepAliveTimeoutDuration() {
1539         return controlKeepAliveTimeout;
1540     }
1541 
1542     /**
1543      * Obtain the currently active listener.
1544      *
1545      * @return the listener, may be {@code null}
1546      * @since 3.0
1547      */
1548     public CopyStreamListener getCopyStreamListener() {
1549         return copyStreamListener;
1550     }
1551 
1552     /**
1553      * Gets the CSL debug array.
1554      * <p>
1555      * <b>For debug use only</b>
1556      * </p>
1557      * <p>
1558      * Currently, it contains:
1559      * </p>
1560      * <ul>
1561      * <li>successfully acked NOOPs at end of transfer</li>
1562      * <li>unanswered NOOPs at end of transfer</li>
1563      * <li>unanswered NOOPs after fetching additional replies</li>
1564      * <li>Number of IOErrors ignored</li>
1565      * </ul>
1566      *
1567      * @deprecated 3.7 For testing only; may be dropped or changed at any time
1568      * @return the debug array
1569      */
1570     @Deprecated // only for use in testing
1571     public int[] getCslDebug() {
1572         return cslDebug;
1573     }
1574 
1575     /**
1576      * Returns the current data connection mode (one of the <code>_DATA_CONNECTION_MODE</code> constants).
1577      *
1578      * @return The current data connection mode (one of the <code>_DATA_CONNECTION_MODE</code> constants).
1579      */
1580     public int getDataConnectionMode() {
1581         return dataConnectionMode;
1582     }
1583 
1584     /**
1585      * Gets the timeout to use when reading from the data connection. This timeout will be set immediately after opening the data connection, provided that the
1586      * value is &ge; 0.
1587      * <p>
1588      * <b>Note:</b> the timeout will also be applied when calling accept() whilst establishing an active local data connection.
1589      * </p>
1590      *
1591      * @return The default timeout used when opening a data connection socket. The value 0 means an infinite timeout.
1592      * @since 3.9.0
1593      */
1594     public Duration getDataTimeout() {
1595         return dataTimeout;
1596     }
1597 
1598     // Method for use by unit test code only
1599     FTPFileEntryParser getEntryParser() {
1600         return entryParser;
1601     }
1602 
1603     /**
1604      * Gets the host address for active mode; allows the local address to be overridden.
1605      *
1606      * @return __activeExternalHost if non-null, else getLocalAddress()
1607      * @see #setActiveExternalIPAddress(String)
1608      */
1609     InetAddress getHostAddress() {
1610         if (activeExternalHost != null) {
1611             return activeExternalHost;
1612         }
1613         // default local address
1614         return getLocalAddress();
1615     }
1616 
1617     /**
1618      * @param pathname the initial pathname
1619      * @return the adjusted string with "-a" added if necessary
1620      * @since 2.0
1621      */
1622     protected String getListArguments(final String pathname) {
1623         if (getListHiddenFiles()) {
1624             if (pathname != null) {
1625                 final StringBuilder sb = new StringBuilder(pathname.length() + 3);
1626                 sb.append("-a ");
1627                 sb.append(pathname);
1628                 return sb.toString();
1629             }
1630             return "-a";
1631         }
1632         return pathname;
1633     }
1634 
1635     /**
1636      * @see #setListHiddenFiles(boolean)
1637      * @return the current state
1638      * @since 2.0
1639      */
1640     public boolean getListHiddenFiles() {
1641         return this.listHiddenFiles;
1642     }
1643 
1644     /**
1645      * Issue the FTP MDTM command (not supported by all servers) to retrieve the last modification time of a file. The modification string should be in the ISO
1646      * 3077 form "yyyyMMDDhhmmss(.xxx)?". The timestamp represented should also be in GMT, but not all FTP servers honor this.
1647      *
1648      * @param pathname The file path to query.
1649      * @return A string representing the last file modification time in <code>yyyyMMDDhhmmss</code> format.
1650      * @throws IOException if an I/O error occurs.
1651      * @since 2.0
1652      */
1653     public String getModificationTime(final String pathname) throws IOException {
1654         if (FTPReply.isPositiveCompletion(mdtm(pathname))) {
1655             // skip the return code (e.g. 213) and the space
1656             return getReplyString(0).substring(4);
1657         }
1658         return null;
1659     }
1660 
1661     /**
1662      * Returns the hostname or IP address (in the form of a string) returned by the server when entering passive mode. If not in passive mode, returns null.
1663      * This method only returns a valid value AFTER a data connection has been opened after a call to {@link #enterLocalPassiveMode enterLocalPassiveMode()}.
1664      * This is because FTPClient sends a PASV command to the server only just before opening a data connection, and not when you call
1665      * {@link #enterLocalPassiveMode enterLocalPassiveMode()}.
1666      *
1667      * @return The passive host name if in passive mode, otherwise null.
1668      */
1669     public String getPassiveHost() {
1670         return passiveHost;
1671     }
1672 
1673     /**
1674      * Sets the local IP address in passive mode. Useful when there are multiple network cards.
1675      *
1676      * @return The local IP address in passive mode.
1677      */
1678     public InetAddress getPassiveLocalIPAddress() {
1679         return this.passiveLocalHost;
1680     }
1681 
1682     /**
1683      * If in passive mode, returns the data port of the passive host. This method only returns a valid value AFTER a data connection has been opened after a
1684      * call to {@link #enterLocalPassiveMode enterLocalPassiveMode()}. This is because FTPClient sends a PASV command to the server only just before opening a
1685      * data connection, and not when you call {@link #enterLocalPassiveMode enterLocalPassiveMode()}.
1686      *
1687      * @return The data port of the passive server. If not in passive mode, undefined.
1688      */
1689     public int getPassivePort() {
1690         return passivePort;
1691     }
1692 
1693     /**
1694      * Retrieve the value to be used for the data socket SO_RCVBUF option.
1695      *
1696      * @return The current buffer size.
1697      * @since 3.3
1698      */
1699     public int getReceiveDataSocketBufferSize() {
1700         return receiveDataSocketBufferSize;
1701     }
1702 
1703     /**
1704      * Gets the reported host address for active mode EPRT/PORT commands; allows override of {@link #getHostAddress()}.
1705      *
1706      * Useful for FTP Client behind Firewall NAT.
1707      *
1708      * @return __reportActiveExternalHost if non-null, else getHostAddress();
1709      */
1710     InetAddress getReportHostAddress() {
1711         if (reportActiveExternalHost != null) {
1712             return reportActiveExternalHost;
1713         }
1714         return getHostAddress();
1715     }
1716 
1717     /**
1718      * Fetches the restart offset.
1719      *
1720      * @return offset The offset into the remote file at which to start the next file transfer.
1721      */
1722     public long getRestartOffset() {
1723         return restartOffset;
1724     }
1725 
1726     /**
1727      * Retrieve the value to be used for the data socket SO_SNDBUF option.
1728      *
1729      * @return The current buffer size.
1730      * @since 3.3
1731      */
1732     public int getSendDataSocketBufferSize() {
1733         return sendDataSocketBufferSize;
1734     }
1735 
1736     /**
1737      * Issue the FTP SIZE command to the server for a given pathname. This should produce the size of the file.
1738      *
1739      * @param pathname the file name
1740      *
1741      * @return The size information returned by the server; {@code null} if there was an error
1742      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1743      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1744      *                                      independently as itself.
1745      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1746      * @since 3.7
1747      */
1748     public String getSize(final String pathname) throws IOException {
1749         if (FTPReply.isPositiveCompletion(size(pathname))) {
1750             return getReplyString(0).substring(4); // skip the return code (e.g. 213) and the space
1751         }
1752         return null;
1753     }
1754 
1755     /**
1756      * Issue the FTP STAT command to the server.
1757      *
1758      * @return The status information returned by the server.
1759      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1760      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1761      *                                      independently as itself.
1762      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1763      */
1764     public String getStatus() throws IOException {
1765         if (FTPReply.isPositiveCompletion(stat())) {
1766             return getReplyString();
1767         }
1768         return null;
1769     }
1770 
1771     /**
1772      * Issue the FTP STAT command to the server for a given pathname. This should produce a listing of the file or directory.
1773      *
1774      * @param pathname the file name
1775      *
1776      * @return The status information returned by the server.
1777      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1778      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1779      *                                      independently as itself.
1780      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1781      */
1782     public String getStatus(final String pathname) throws IOException {
1783         if (FTPReply.isPositiveCompletion(stat(pathname))) {
1784             return getReplyString();
1785         }
1786         return null;
1787     }
1788 
1789     /**
1790      * @deprecated use {@link #getSystemType()} instead
1791      * @return the name
1792      * @throws IOException on error
1793      */
1794     @Deprecated
1795     public String getSystemName() throws IOException {
1796         if (systemName == null && FTPReply.isPositiveCompletion(syst())) {
1797             systemName = _replyLines.get(_replyLines.size() - 1).substring(4);
1798         }
1799         return systemName;
1800     }
1801 
1802     /**
1803      * Fetches the system type from the server and returns the string. This value is cached for the duration of the connection after the first call to this
1804      * method. In other words, only the first time that you invoke this method will it issue a SYST command to the FTP server. FTPClient will remember the value
1805      * and return the cached value until a call to disconnect.
1806      * <p>
1807      * If the SYST command fails, and the system property {@link #FTP_SYSTEM_TYPE_DEFAULT} is defined, then this is used instead.
1808      * </p>
1809      *
1810      * @return The system type obtained from the server. Never null.
1811      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1812      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1813      *                                      independently as itself.
1814      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server (and the
1815      *                                      default system type property is not defined)
1816      * @since 2.2
1817      */
1818     public String getSystemType() throws IOException {
1819         // if (syst() == FTPReply.NAME_SYSTEM_TYPE)
1820         // Technically, we should expect a NAME_SYSTEM_TYPE response, but
1821         // in practice FTP servers deviate, so we soften the condition to
1822         // a positive completion.
1823         if (systemName == null) {
1824             if (FTPReply.isPositiveCompletion(syst())) {
1825                 // Assume that response is not empty here (cannot be null)
1826                 systemName = _replyLines.get(_replyLines.size() - 1).substring(4);
1827             } else {
1828                 // Check if the user has provided a default for when the SYST command fails
1829                 final String systDefault = System.getProperty(FTP_SYSTEM_TYPE_DEFAULT);
1830                 if (systDefault == null) {
1831                     throw new IOException("Unable to determine system type - response: " + getReplyString());
1832                 }
1833                 systemName = systDefault;
1834             }
1835         }
1836         return systemName;
1837     }
1838 
1839     /**
1840      * Queries the server for a supported feature. Caches the parsed response to avoid resending the command repeatedly.
1841      *
1842      * @param feature the name of the feature; it is converted to upper case.
1843      * @return {@code true} if the feature is present, {@code false} if the feature is not present or the {@link #feat()} command failed. Check
1844      *         {@link #getReplyCode()} or {@link #getReplyString()} if it is necessary to distinguish these cases.
1845      *
1846      * @throws IOException on error
1847      * @since 3.8.0
1848      */
1849     public boolean hasFeature(final FTPCmd feature) throws IOException {
1850         return hasFeature(feature.name());
1851     }
1852 
1853     /**
1854      * Queries the server for a supported feature. Caches the parsed response to avoid resending the command repeatedly.
1855      *
1856      * @param feature the name of the feature; it is converted to upper case.
1857      * @return {@code true} if the feature is present, {@code false} if the feature is not present or the {@link #feat()} command failed. Check
1858      *         {@link #getReplyCode()} or {@link #getReplyString()} if it is necessary to distinguish these cases.
1859      *
1860      * @throws IOException on error
1861      * @since 3.0
1862      */
1863     public boolean hasFeature(final String feature) throws IOException {
1864         if (!initFeatureMap()) {
1865             return false;
1866         }
1867         return featuresMap.containsKey(feature.toUpperCase(Locale.ENGLISH));
1868     }
1869 
1870     /**
1871      * Queries the server for a supported feature with particular value, for example "AUTH SSL" or "AUTH TLS". Caches the parsed response to avoid resending the
1872      * command repeatedly.
1873      *
1874      * @param feature the name of the feature; it is converted to upper case.
1875      * @param value   the value to find.
1876      *
1877      * @return {@code true} if the feature is present, {@code false} if the feature is not present or the {@link #feat()} command failed. Check
1878      *         {@link #getReplyCode()} or {@link #getReplyString()} if it is necessary to distinguish these cases.
1879      *
1880      * @throws IOException on error
1881      * @since 3.0
1882      */
1883     public boolean hasFeature(final String feature, final String value) throws IOException {
1884         if (!initFeatureMap()) {
1885             return false;
1886         }
1887         final Set<String> entries = featuresMap.get(feature.toUpperCase(Locale.ENGLISH));
1888         if (entries != null) {
1889             return entries.contains(value);
1890         }
1891         return false;
1892     }
1893 
1894     private void initDefaults() {
1895         dataConnectionMode = ACTIVE_LOCAL_DATA_CONNECTION_MODE;
1896         passiveHost = null;
1897         passivePort = -1;
1898         activeExternalHost = null;
1899         reportActiveExternalHost = null;
1900         activeMinPort = 0;
1901         activeMaxPort = 0;
1902         fileType = FTP.ASCII_FILE_TYPE;
1903         fileStructure = FTP.FILE_STRUCTURE;
1904         fileFormat = FTP.NON_PRINT_TEXT_FORMAT;
1905         fileTransferMode = FTP.STREAM_TRANSFER_MODE;
1906         restartOffset = 0;
1907         systemName = null;
1908         entryParser = null;
1909         entryParserKey = "";
1910         featuresMap = null;
1911     }
1912 
1913     /*
1914      * Create the feature map if not already created.
1915      */
1916     private boolean initFeatureMap() throws IOException {
1917         if (featuresMap == null) {
1918             // Don't create map here, because next line may throw exception
1919             final int replyCode = feat();
1920             if (replyCode == FTPReply.NOT_LOGGED_IN) { // 503
1921                 return false; // NET-518; don't create empty map
1922             }
1923             final boolean success = FTPReply.isPositiveCompletion(replyCode);
1924             // init the map here, so we don't keep trying if we know the command will fail
1925             featuresMap = new HashMap<>();
1926             if (!success) {
1927                 return false;
1928             }
1929             for (final String line : _replyLines) {
1930                 if (line.startsWith(" ")) { // it's a FEAT entry
1931                     String key;
1932                     String value = "";
1933                     final int varsep = line.indexOf(' ', 1);
1934                     if (varsep > 0) {
1935                         key = line.substring(1, varsep);
1936                         value = line.substring(varsep + 1);
1937                     } else {
1938                         key = line.substring(1);
1939                     }
1940                     key = key.toUpperCase(Locale.ENGLISH);
1941                     final Set<String> entries = featuresMap.computeIfAbsent(key, k -> new HashSet<>());
1942                     entries.add(value);
1943                 }
1944             }
1945         }
1946         return true;
1947     }
1948 
1949     /**
1950      * Using the default autodetect mechanism, initialize an FTPListParseEngine object containing a raw file information for the current working directory on
1951      * the server This information is obtained through the LIST command. This object is then capable of being iterated to return a sequence of FTPFile objects
1952      * with information filled in by the <code>FTPFileEntryParser</code> used.
1953      * <p>
1954      * This method differs from using the listFiles() methods in that expensive FTPFile objects are not created until needed which may be an advantage on large
1955      * lists.
1956      * </p>
1957      *
1958      * @return A FTPListParseEngine object that holds the raw information and is capable of providing parsed FTPFile objects, one for each file containing
1959      *         information contained in the given path in the format determined by the <code>parser</code> parameter. Null will be returned if a data
1960      *         connection cannot be opened. If the current working directory contains no files, an empty array will be the return.
1961      *
1962      * @throws FTPConnectionClosedException                                    If the FTP server prematurely closes the connection as a result of the client
1963      *                                                                         being idle or some other reason causing the server to send FTP reply code 421.
1964      *                                                                         This exception may be caught either as an IOException or independently as itself.
1965      * @throws IOException                                                     If an I/O error occurs while either sending a command to the server or receiving
1966      *                                                                         a reply from the server.
1967      * @throws org.apache.commons.net.ftp.parser.ParserInitializationException Thrown if the autodetect mechanism cannot resolve the type of system we are
1968      *                                                                         connected with.
1969      * @see FTPListParseEngine
1970      */
1971     public FTPListParseEngine initiateListParsing() throws IOException {
1972         return initiateListParsing((String) null);
1973     }
1974 
1975     /**
1976      * private method through which all listFiles() and initiateListParsing methods pass once a parser is determined.
1977      *
1978      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
1979      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
1980      *                                      independently as itself.
1981      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
1982      * @see FTPListParseEngine
1983      */
1984     private FTPListParseEngine initiateListParsing(final FTPFileEntryParser parser, final String pathname) throws IOException {
1985         final Socket socket = _openDataConnection_(FTPCmd.LIST, getListArguments(pathname));
1986         final FTPListParseEngine engine = new FTPListParseEngine(parser, configuration);
1987         if (socket == null) {
1988             return engine;
1989         }
1990         try {
1991             engine.readServerList(socket.getInputStream(), getControlEncoding());
1992         } finally {
1993             Util.closeQuietly(socket);
1994         }
1995         completePendingCommand();
1996         return engine;
1997     }
1998 
1999     /**
2000      * Using the default autodetect mechanism, initialize an FTPListParseEngine object containing a raw file information for the supplied directory. This
2001      * information is obtained through the LIST command. This object is then capable of being iterated to return a sequence of FTPFile objects with information
2002      * filled in by the <code>FTPFileEntryParser</code> used.
2003      * <p>
2004      * The server may or may not expand glob expressions. You should avoid using glob expressions because the return format for glob listings differs from
2005      * server to server and will likely cause this method to fail.
2006      * </p>
2007      * <p>
2008      * This method differs from using the listFiles() methods in that expensive FTPFile objects are not created until needed which may be an advantage on large
2009      * lists.
2010      * </p>
2011      *
2012      * <pre>
2013      * FTPClient f = FTPClient();
2014      * f.connect(server);
2015      * f.login(username, password);
2016      * FTPListParseEngine engine = f.initiateListParsing(directory);
2017      *
2018      * while (engine.hasNext()) {
2019      *     FTPFile[] files = engine.getNext(25); // "page size" you want
2020      *     // do whatever you want with these files, display them, etc.
2021      *     // expensive FTPFile objects not created until needed.
2022      * }
2023      * </pre>
2024      *
2025      * @param pathname the starting directory
2026      *
2027      * @return A FTPListParseEngine object that holds the raw information and is capable of providing parsed FTPFile objects, one for each file containing
2028      *         information contained in the given path in the format determined by the <code>parser</code> parameter. Null will be returned if a data
2029      *         connection cannot be opened. If the current working directory contains no files, an empty array will be the return.
2030      *
2031      * @throws FTPConnectionClosedException                                    If the FTP server prematurely closes the connection as a result of the client
2032      *                                                                         being idle or some other reason causing the server to send FTP reply code 421.
2033      *                                                                         This exception may be caught either as an IOException or independently as itself.
2034      * @throws IOException                                                     If an I/O error occurs while either sending a command to the server or receiving
2035      *                                                                         a reply from the server.
2036      * @throws org.apache.commons.net.ftp.parser.ParserInitializationException Thrown if the autodetect mechanism cannot resolve the type of system we are
2037      *                                                                         connected with.
2038      * @see FTPListParseEngine
2039      */
2040     public FTPListParseEngine initiateListParsing(final String pathname) throws IOException {
2041         return initiateListParsing((String) null, pathname);
2042     }
2043 
2044     /**
2045      * Using the supplied parser key, initialize an FTPListParseEngine object containing a raw file information for the supplied directory. This information is
2046      * obtained through the LIST command. This object is then capable of being iterated to return a sequence of FTPFile objects with information filled in by
2047      * the <code>FTPFileEntryParser</code> used.
2048      * <p>
2049      * The server may or may not expand glob expressions. You should avoid using glob expressions because the return format for glob listings differs from
2050      * server to server and will likely cause this method to fail.
2051      * </p>
2052      * <p>
2053      * This method differs from using the listFiles() methods in that expensive FTPFile objects are not created until needed which may be an advantage on large
2054      * lists.
2055      * </p>
2056      *
2057      * @param parserKey A string representing a designated code or fully-qualified class name of an <code>FTPFileEntryParser</code> that should be used to
2058      *                  parse each server file listing. May be {@code null}, in which case the code checks first the system property {@link #FTP_SYSTEM_TYPE},
2059      *                  and if that is not defined the SYST command is used to provide the value. To allow for arbitrary system types, the return from the SYST
2060      *                  command is used to look up an alias for the type in the {@link #SYSTEM_TYPE_PROPERTIES} properties file if it is available.
2061      * @param pathname  the starting directory
2062      *
2063      * @return A FTPListParseEngine object that holds the raw information and is capable of providing parsed FTPFile objects, one for each file containing
2064      *         information contained in the given path in the format determined by the <code>parser</code> parameter. Null will be returned if a data
2065      *         connection cannot be opened. If the current working directory contains no files, an empty array will be the return.
2066      *
2067      * @throws FTPConnectionClosedException                                    If the FTP server prematurely closes the connection as a result of the client
2068      *                                                                         being idle or some other reason causing the server to send FTP reply code 421.
2069      *                                                                         This exception may be caught either as an IOException or independently as itself.
2070      * @throws IOException                                                     If an I/O error occurs while either sending a command to the server or receiving
2071      *                                                                         a reply from the server.
2072      * @throws org.apache.commons.net.ftp.parser.ParserInitializationException Thrown if the parserKey parameter cannot be resolved by the selected parser
2073      *                                                                         factory. In the DefaultFTPEntryParserFactory, this will happen when parserKey is
2074      *                                                                         neither the fully qualified class name of a class implementing the interface
2075      *                                                                         org.apache.commons.net.ftp.FTPFileEntryParser nor a string containing one of the
2076      *                                                                         recognized keys mapping to such a parser or if class loader security issues
2077      *                                                                         prevent its being loaded.
2078      * @see FTPListParseEngine
2079      */
2080     public FTPListParseEngine initiateListParsing(final String parserKey, final String pathname) throws IOException {
2081         createParser(parserKey); // create and cache parser
2082         return initiateListParsing(entryParser, pathname);
2083     }
2084 
2085     /**
2086      * Initiate list parsing for MLSD listings in the current working directory.
2087      *
2088      * @return the engine
2089      * @throws IOException on error
2090      */
2091     public FTPListParseEngine initiateMListParsing() throws IOException {
2092         return initiateMListParsing(null);
2093     }
2094 
2095     /**
2096      * Initiate list parsing for MLSD listings.
2097      *
2098      * @param pathname the path from where to MLSD.
2099      * @return the engine.
2100      * @throws IOException on error
2101      */
2102     public FTPListParseEngine initiateMListParsing(final String pathname) throws IOException {
2103         final Socket socket = _openDataConnection_(FTPCmd.MLSD, pathname);
2104         final FTPListParseEngine engine = new FTPListParseEngine(MLSxEntryParser.getInstance(), configuration);
2105         if (socket == null) {
2106             return engine;
2107         }
2108         try {
2109             engine.readServerList(socket.getInputStream(), getControlEncoding());
2110         } finally {
2111             Util.closeQuietly(socket);
2112             completePendingCommand();
2113         }
2114         return engine;
2115     }
2116 
2117     /**
2118      * Returns, whether the IP address from the server's response should be used. Until 3.9.0, this has always been the case. Beginning with 3.9.0, that IP
2119      * address will be silently ignored, and replaced with the remote IP address of the control connection, unless this configuration option is given, which
2120      * restores the old behavior. To enable this by default, use the system property {@link FTPClient#FTP_IP_ADDRESS_FROM_PASV_RESPONSE}.
2121      *
2122      * @return True, if the IP address from the server's response will be used (pre-3.9 compatible behavior), or false (ignore that IP address).
2123      *
2124      * @see FTPClient#FTP_IP_ADDRESS_FROM_PASV_RESPONSE
2125      * @see #setIpAddressFromPasvResponse(boolean)
2126      * @since 3.9.0
2127      */
2128     public boolean isIpAddressFromPasvResponse() {
2129         return ipAddressFromPasvResponse;
2130     }
2131 
2132     /**
2133      * Return whether or not verification of the remote host participating in data connections is enabled. The default behavior is for verification to be
2134      * enabled.
2135      *
2136      * @return True if verification is enabled, false if not.
2137      */
2138     public boolean isRemoteVerificationEnabled() {
2139         return remoteVerificationEnabled;
2140     }
2141 
2142     /**
2143      * Whether to attempt using EPSV with IPv4. Default (if not set) is {@code false}
2144      *
2145      * @return true if EPSV shall be attempted with IPv4.
2146      * @since 2.2
2147      */
2148     public boolean isUseEPSVwithIPv4() {
2149         return useEPSVwithIPv4;
2150     }
2151 
2152     /**
2153      * Using the default system autodetect mechanism, obtain a list of directories contained in the current working directory.
2154      * <p>
2155      * This information is obtained through the LIST command. The contents of the returned array is determined by the<code>FTPFileEntryParser</code> used.
2156      * </p>
2157      * <p>
2158      * N.B. the LIST command does not generally return very precise timestamps. For recent files, the response usually contains hours and minutes (not seconds).
2159      * For older files, the output may only contain a date. If the server supports it, the MLSD command returns timestamps with a precision of seconds, and may
2160      * include milliseconds. See {@link #mlistDir()}
2161      * </p>
2162      *
2163      * @return The list of directories contained in the current directory in the format determined by the autodetection mechanism.
2164      * @throws FTPConnectionClosedException                                    If the FTP server prematurely closes the connection as a result of the client
2165      *                                                                         being idle or some other reason causing the server to send FTP reply code 421.
2166      *                                                                         This exception may be caught either as an IOException or independently as itself.
2167      * @throws IOException                                                     If an I/O error occurs while either sending a command to the server or receiving
2168      *                                                                         a reply from the server.
2169      * @throws org.apache.commons.net.ftp.parser.ParserInitializationException Thrown if the parserKey parameter cannot be resolved by the selected parser
2170      *                                                                         factory. In the DefaultFTPEntryParserFactory, this will happen when parserKey is
2171      *                                                                         neither the fully qualified class name of a class implementing the interface
2172      *                                                                         org.apache.commons.net.ftp.FTPFileEntryParser nor a string containing one of the
2173      *                                                                         recognized keys mapping to such a parser or if class loader security issues
2174      *                                                                         prevent its being loaded.
2175      * @see org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory
2176      * @see org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory
2177      * @see org.apache.commons.net.ftp.FTPFileEntryParser
2178      * @since 3.0
2179      */
2180     public FTPFile[] listDirectories() throws IOException {
2181         return listDirectories((String) null);
2182     }
2183 
2184     /**
2185      * Using the default system autodetect mechanism, obtain a list of directories contained in the specified directory.
2186      * <p>
2187      * This information is obtained through the LIST command. The contents of the returned array is determined by the<code>FTPFileEntryParser</code> used.
2188      * </p>
2189      * <p>
2190      * N.B. the LIST command does not generally return very precise timestamps. For recent files, the response usually contains hours and minutes (not seconds).
2191      * For older files, the output may only contain a date. If the server supports it, the MLSD command returns timestamps with a precision of seconds, and may
2192      * include milliseconds. See {@link #mlistDir()}
2193      * </p>
2194      *
2195      * @param parent the starting directory
2196      * @return The list of directories contained in the specified directory in the format determined by the autodetection mechanism.
2197      * @throws FTPConnectionClosedException                                    If the FTP server prematurely closes the connection as a result of the client
2198      *                                                                         being idle or some other reason causing the server to send FTP reply code 421.
2199      *                                                                         This exception may be caught either as an IOException or independently as itself.
2200      * @throws IOException                                                     If an I/O error occurs while either sending a command to the server or receiving
2201      *                                                                         a reply from the server.
2202      * @throws org.apache.commons.net.ftp.parser.ParserInitializationException Thrown if the parserKey parameter cannot be resolved by the selected parser
2203      *                                                                         factory. In the DefaultFTPEntryParserFactory, this will happen when parserKey is
2204      *                                                                         neither the fully qualified class name of a class implementing the interface
2205      *                                                                         org.apache.commons.net.ftp.FTPFileEntryParser nor a string containing one of the
2206      *                                                                         recognized keys mapping to such a parser or if class loader security issues
2207      *                                                                         prevent its being loaded.
2208      * @see org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory
2209      * @see org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory
2210      * @see org.apache.commons.net.ftp.FTPFileEntryParser
2211      * @since 3.0
2212      */
2213     public FTPFile[] listDirectories(final String parent) throws IOException {
2214         return listFiles(parent, FTPFileFilters.DIRECTORIES);
2215     }
2216 
2217     /**
2218      * Using the default system autodetect mechanism, obtain a list of file information for the current working directory.
2219      * <p>
2220      * This information is obtained through the LIST command. The contents of the returned array is determined by the<code>FTPFileEntryParser</code> used.
2221      * </p>
2222      * <p>
2223      * N.B. the LIST command does not generally return very precise timestamps. For recent files, the response usually contains hours and minutes (not seconds).
2224      * For older files, the output may only contain a date. If the server supports it, the MLSD command returns timestamps with a precision of seconds, and may
2225      * include milliseconds. See {@link #mlistDir()}
2226      * </p>
2227      *
2228      * @return The list of file information contained in the current directory in the format determined by the autodetection mechanism.
2229      *         <b>NOTE:</b> This array may contain null members if any of the individual file listings failed to parse. The caller should check each entry for
2230      *         null before referencing it.
2231      * @throws FTPConnectionClosedException                                    If the FTP server prematurely closes the connection as a result of the client
2232      *                                                                         being idle or some other reason causing the server to send FTP reply code 421.
2233      *                                                                         This exception may be caught either as an IOException or independently as itself.
2234      * @throws IOException                                                     If an I/O error occurs while either sending a command to the server or receiving
2235      *                                                                         a reply from the server.
2236      * @throws org.apache.commons.net.ftp.parser.ParserInitializationException Thrown if the parserKey parameter cannot be resolved by the selected parser
2237      *                                                                         factory. In the DefaultFTPEntryParserFactory, this will happen when parserKey is
2238      *                                                                         neither the fully qualified class name of a class implementing the interface
2239      *                                                                         org.apache.commons.net.ftp.FTPFileEntryParser nor a string containing one of the
2240      *                                                                         recognized keys mapping to such a parser or if class loader security issues
2241      *                                                                         prevent its being loaded.
2242      * @see org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory
2243      * @see org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory
2244      * @see org.apache.commons.net.ftp.FTPFileEntryParser
2245      */
2246     public FTPFile[] listFiles() throws IOException {
2247         return listFiles((String) null);
2248     }
2249 
2250     /**
2251      * Using the default system autodetect mechanism, obtain a list of file information for the current working directory or for just a single file.
2252      * <p>
2253      * This information is obtained through the LIST command. The contents of the returned array is determined by the<code>FTPFileEntryParser</code> used.
2254      * </p>
2255      * <p>
2256      * N.B. the LIST command does not generally return very precise timestamps. For recent files, the response usually contains hours and minutes (not seconds).
2257      * For older files, the output may only contain a date. If the server supports it, the MLSD command returns timestamps with a precision of seconds, and may
2258      * include milliseconds. See {@link #mlistDir()}
2259      * </p>
2260      *
2261      * @param pathname The file or directory to list. Since the server may or may not expand glob expressions, using them here is not recommended and may well
2262      *                 cause this method to fail. Also, some servers treat a leading '-' as being an option. To avoid this interpretation, use an absolute
2263      *                 pathname or prefix the pathname with ./ (unix style servers). Some servers may support "--" as meaning end of options, in which case "--
2264      *                 -xyz" should work.
2265      * @return The list of file information contained in the given path in the format determined by the autodetection mechanism
2266      * @throws FTPConnectionClosedException                                    If the FTP server prematurely closes the connection as a result of the client
2267      *                                                                         being idle or some other reason causing the server to send FTP reply code 421.
2268      *                                                                         This exception may be caught either as an IOException or independently as itself.
2269      * @throws IOException                                                     If an I/O error occurs while either sending a command to the server or receiving
2270      *                                                                         a reply from the server.
2271      * @throws org.apache.commons.net.ftp.parser.ParserInitializationException Thrown if the parserKey parameter cannot be resolved by the selected parser
2272      *                                                                         factory. In the DefaultFTPEntryParserFactory, this will happen when parserKey is
2273      *                                                                         neither the fully qualified class name of a class implementing the interface
2274      *                                                                         org.apache.commons.net.ftp.FTPFileEntryParser nor a string containing one of the
2275      *                                                                         recognized keys mapping to such a parser or if class loader security issues
2276      *                                                                         prevent its being loaded.
2277      * @see org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory
2278      * @see org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory
2279      * @see org.apache.commons.net.ftp.FTPFileEntryParser
2280      */
2281     public FTPFile[] listFiles(final String pathname) throws IOException {
2282         return initiateListParsing((String) null, pathname).getFiles();
2283     }
2284 
2285     /**
2286      * Version of {@link #listFiles(String)} which allows a filter to be provided. For example: <code>listFiles("site", FTPFileFilters.DIRECTORY);</code>
2287      *
2288      * @param pathname the initial path, may be null
2289      * @param filter   the filter, non-null
2290      * @return the array of FTPFile entries.
2291      * @throws IOException on error
2292      * @since 2.2
2293      */
2294     public FTPFile[] listFiles(final String pathname, final FTPFileFilter filter) throws IOException {
2295         return initiateListParsing((String) null, pathname).getFiles(filter);
2296     }
2297 
2298     /**
2299      * Fetches the system help information from the server and returns the full string.
2300      *
2301      * @return The system help string obtained from the server. null if the information could not be obtained.
2302      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2303      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2304      *                                      independently as itself.
2305      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2306      */
2307     public String listHelp() throws IOException {
2308         return FTPReply.isPositiveCompletion(help()) ? getReplyString() : null;
2309     }
2310 
2311     /**
2312      * Fetches the help information for a given command from the server and returns the full string.
2313      *
2314      * @param command The command on which to ask for help.
2315      * @return The command help string obtained from the server. null if the information could not be obtained.
2316      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2317      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2318      *                                      independently as itself.
2319      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2320      */
2321     public String listHelp(final String command) throws IOException {
2322         return FTPReply.isPositiveCompletion(help(command)) ? getReplyString() : null;
2323     }
2324 
2325     /**
2326      * Obtain a list of file names in the current working directory This information is obtained through the NLST command. If the current directory contains no
2327      * files, a zero length array is returned only if the FTP server returned a positive completion code, otherwise, null is returned (the FTP server returned a
2328      * 550 error No files found.). If the directory is not empty, an array of file names in the directory is returned.
2329      *
2330      * @return The list of file names contained in the current working directory. null if the list could not be obtained. If there are no file names in the
2331      *         directory, a zero-length array is returned.
2332      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2333      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2334      *                                      independently as itself.
2335      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2336      */
2337     public String[] listNames() throws IOException {
2338         return listNames(null);
2339     }
2340 
2341     /**
2342      * Obtain a list of file names in a directory (or just the name of a given file, which is not particularly useful). This information is obtained through the
2343      * NLST command. If the given pathname is a directory and contains no files, a zero length array is returned only if the FTP server returned a positive
2344      * completion code, otherwise null is returned (the FTP server returned a 550 error No files found.). If the directory is not empty, an array of file names
2345      * in the directory is returned. If the pathname corresponds to a file, only that file will be listed. The server may or may not expand glob expressions.
2346      *
2347      * @param pathname The file or directory to list. Warning: the server may treat a leading '-' as an option introducer. If so, try using an absolute path, or
2348      *                 prefix the path with ./ (unix style servers). Some servers may support "--" as meaning end of options, in which case "-- -xyz" should
2349      *                 work.
2350      * @return The list of file names contained in the given path. null if the list could not be obtained. If there are no file names in the directory, a
2351      *         zero-length array is returned.
2352      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2353      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2354      *                                      independently as itself.
2355      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2356      */
2357     public String[] listNames(final String pathname) throws IOException {
2358         final ArrayList<String> results = new ArrayList<>();
2359         try (final Socket socket = _openDataConnection_(FTPCmd.NLST, getListArguments(pathname))) {
2360             if (socket == null) {
2361                 return null;
2362             }
2363             try (final BufferedReader reader = new BufferedReader(new InputStreamReader(socket.getInputStream(), getControlEncoding()))) {
2364                 String line;
2365                 while ((line = reader.readLine()) != null) {
2366                     results.add(line);
2367                 }
2368             }
2369         }
2370         if (completePendingCommand()) {
2371             return results.toArray(NetConstants.EMPTY_STRING_ARRAY);
2372         }
2373         return null;
2374     }
2375 
2376     /**
2377      * Login to the FTP server using the provided user and password.
2378      *
2379      * @param user     The user name to login under.
2380      * @param password The password to use.
2381      * @return True if successfully completed, false if not.
2382      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2383      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2384      *                                      independently as itself.
2385      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2386      */
2387     public boolean login(final String user, final String password) throws IOException {
2388         user(user);
2389         if (FTPReply.isPositiveCompletion(_replyCode)) {
2390             return true;
2391         }
2392         // If we get here, we either have an error code, or an intermediate
2393         // reply requesting password.
2394         if (!FTPReply.isPositiveIntermediate(_replyCode)) {
2395             return false;
2396         }
2397         return FTPReply.isPositiveCompletion(pass(password));
2398     }
2399 
2400     /**
2401      * Login to the FTP server using the provided username, password, and account. If no account is required by the server, only the username and password, the
2402      * account information is not used.
2403      *
2404      * @param user     The user name to login under.
2405      * @param password The password to use.
2406      * @param account  The account to use.
2407      * @return True if successfully completed, false if not.
2408      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2409      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2410      *                                      independently as itself.
2411      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2412      */
2413     public boolean login(final String user, final String password, final String account) throws IOException {
2414         user(user);
2415         if (FTPReply.isPositiveCompletion(_replyCode)) {
2416             return true;
2417         }
2418         // If we get here, we either have an error code, or an intermediate
2419         // reply requesting password.
2420         if (!FTPReply.isPositiveIntermediate(_replyCode)) {
2421             return false;
2422         }
2423         pass(password);
2424         if (FTPReply.isPositiveCompletion(_replyCode)) {
2425             return true;
2426         }
2427         if (!FTPReply.isPositiveIntermediate(_replyCode)) {
2428             return false;
2429         }
2430         return FTPReply.isPositiveCompletion(acct(account));
2431     }
2432 
2433     /**
2434      * Logout of the FTP server by sending the QUIT command.
2435      *
2436      * @return True if successfully completed, false if not.
2437      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2438      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2439      *                                      independently as itself.
2440      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2441      */
2442     public boolean logout() throws IOException {
2443         return FTPReply.isPositiveCompletion(quit());
2444     }
2445 
2446     /**
2447      * Creates a new subdirectory on the FTP server in the current directory (if a relative pathname is given) or where specified (if an absolute pathname is
2448      * given).
2449      *
2450      * @param pathname The pathname of the directory to create.
2451      * @return True if successfully completed, false if not.
2452      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2453      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2454      *                                      independently as itself.
2455      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2456      */
2457     public boolean makeDirectory(final String pathname) throws IOException {
2458         return FTPReply.isPositiveCompletion(mkd(pathname));
2459     }
2460 
2461     /**
2462      * Issue the FTP MDTM command (not supported by all servers) to retrieve the last modification time of a file. The modification string should be in the ISO
2463      * 3077 form "yyyyMMDDhhmmss(.xxx)?". The timestamp represented should also be in GMT, but not all FTP servers honor this.
2464      *
2465      * @param pathname The file path to query.
2466      * @return A Calendar representing the last file modification time, may be {@code null}. The Calendar timestamp will be null if a parse error occurs.
2467      * @throws IOException if an I/O error occurs.
2468      * @since 3.8.0
2469      */
2470     public Calendar mdtmCalendar(final String pathname) throws IOException {
2471         final String modificationTime = getModificationTime(pathname);
2472         if (modificationTime != null) {
2473             return MLSxEntryParser.parseGMTdateTime(modificationTime);
2474         }
2475         return null;
2476     }
2477 
2478     /**
2479      * Issue the FTP MDTM command (not supported by all servers) to retrieve the last modification time of a file. The modification string should be in the ISO
2480      * 3077 form "yyyyMMDDhhmmss(.xxx)?". The timestamp represented should also be in GMT, but not all FTP servers honor this.
2481      *
2482      * @param pathname The file path to query.
2483      * @return A FTPFile representing the last file modification time, may be {@code null}. The FTPFile timestamp will be null if a parse error occurs.
2484      * @throws IOException if an I/O error occurs.
2485      * @since 3.4
2486      */
2487     public FTPFile mdtmFile(final String pathname) throws IOException {
2488         final String modificationTime = getModificationTime(pathname);
2489         if (modificationTime != null) {
2490             final FTPFile file = new FTPFile();
2491             file.setName(pathname);
2492             file.setRawListing(modificationTime);
2493             file.setTimestamp(MLSxEntryParser.parseGMTdateTime(modificationTime));
2494             return file;
2495         }
2496         return null;
2497     }
2498 
2499     /**
2500      * Issue the FTP MDTM command (not supported by all servers) to retrieve the last modification time of a file. The modification string should be in the ISO
2501      * 3077 form "yyyyMMDDhhmmss(.xxx)?". The timestamp represented should also be in GMT, but not all FTP servers honor this.
2502      *
2503      * @param pathname The file path to query.
2504      * @return An Instant representing the last file modification time, may be {@code null}. The Instant timestamp will be null if a parse error occurs.
2505      * @throws IOException if an I/O error occurs.
2506      * @since 3.9.0
2507      */
2508     public Instant mdtmInstant(final String pathname) throws IOException {
2509         final String modificationTime = getModificationTime(pathname);
2510         if (modificationTime != null) {
2511             return MLSxEntryParser.parseGmtInstant(modificationTime);
2512         }
2513         return null;
2514     }
2515 
2516     /**
2517      * Merge two copystream listeners, either or both of which may be null.
2518      *
2519      * @param local the listener used by this class, may be null
2520      * @return a merged listener or a single listener or null
2521      * @since 3.0
2522      */
2523     private CopyStreamListener mergeListeners(final CopyStreamListener local) {
2524         if (local == null) {
2525             return copyStreamListener;
2526         }
2527         if (copyStreamListener == null) {
2528             return local;
2529         }
2530         // Both are non-null
2531         final CopyStreamAdapter merged = new CopyStreamAdapter();
2532         merged.addCopyStreamListener(local);
2533         merged.addCopyStreamListener(copyStreamListener);
2534         return merged;
2535     }
2536 
2537     /**
2538      * Generate a directory listing for the current directory using the MLSD command.
2539      *
2540      * @return the array of file entries
2541      * @throws IOException on error
2542      * @since 3.0
2543      */
2544     public FTPFile[] mlistDir() throws IOException {
2545         return mlistDir(null);
2546     }
2547 
2548     /**
2549      * Generate a directory listing using the MLSD command.
2550      *
2551      * @param pathname the directory name, may be {@code null}
2552      * @return the array of file entries
2553      * @throws IOException on error
2554      * @since 3.0
2555      */
2556     public FTPFile[] mlistDir(final String pathname) throws IOException {
2557         return initiateMListParsing(pathname).getFiles();
2558     }
2559 
2560     /**
2561      * Generate a directory listing using the MLSD command.
2562      *
2563      * @param pathname the directory name, may be {@code null}
2564      * @param filter   the filter to apply to the responses
2565      * @return the array of file entries
2566      * @throws IOException on error
2567      * @since 3.0
2568      */
2569     public FTPFile[] mlistDir(final String pathname, final FTPFileFilter filter) throws IOException {
2570         return initiateMListParsing(pathname).getFiles(filter);
2571     }
2572 
2573     /**
2574      * Gets file details using the MLST command
2575      *
2576      * @param pathname the file or directory to list, may be {@code null}
2577      * @return the file details, may be {@code null}
2578      * @throws IOException on error
2579      * @since 3.0
2580      */
2581     public FTPFile mlistFile(final String pathname) throws IOException {
2582         final boolean success = FTPReply.isPositiveCompletion(sendCommand(FTPCmd.MLST, pathname));
2583         if (success) {
2584             String reply = getReplyString(1);
2585             // some FTP server reply not contains space before fact(s)
2586             if (reply.charAt(0) != ' ') {
2587                 reply = " " + reply;
2588             }
2589             /*
2590              * check the response makes sense. Must have space before fact(s) and between fact(s) and file name Fact(s) can be absent, so at least 3 chars are
2591              * needed.
2592              */
2593             if (reply.length() < 3) {
2594                 throw new MalformedServerReplyException("Invalid server reply (MLST): '" + reply + "'");
2595             }
2596             // some FTP server reply contains more than one space before fact(s)
2597             final String entry = reply.replaceAll("^\\s+", ""); // skip leading space for parser
2598             return MLSxEntryParser.parseEntry(entry);
2599         }
2600         return null;
2601     }
2602 
2603     /**
2604      * Returns the pathname of the current working directory.
2605      *
2606      * @return The pathname of the current working directory. If it cannot be obtained, returns null.
2607      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2608      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2609      *                                      independently as itself.
2610      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2611      */
2612     public String printWorkingDirectory() throws IOException {
2613         if (pwd() != FTPReply.PATHNAME_CREATED) {
2614             return null;
2615         }
2616         return parsePathname(_replyLines.get(_replyLines.size() - 1));
2617     }
2618 
2619     /**
2620      * Reinitialize the FTP session. Not all FTP servers support this command, which issues the FTP REIN command.
2621      *
2622      * @return True if successfully completed, false if not.
2623      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2624      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2625      *                                      independently as itself.
2626      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2627      * @since 3.4 (made public)
2628      */
2629     public boolean reinitialize() throws IOException {
2630         rein();
2631         if (FTPReply.isPositiveCompletion(_replyCode) || FTPReply.isPositivePreliminary(_replyCode) && FTPReply.isPositiveCompletion(getReply())) {
2632             initDefaults();
2633             return true;
2634         }
2635         return false;
2636     }
2637 
2638     // For server to server transfers
2639     /**
2640      * Initiate a server to server file transfer. This method tells the server to which the client is connected to append to a given file on the other server.
2641      * The other server must have had a <code>remoteRetrieve</code> issued to it by another FTPClient.
2642      *
2643      * @param fileName The name of the file to be appended to, or if the file does not exist, the name to call the file being stored.
2644      *
2645      * @return True if successfully completed, false if not.
2646      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2647      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2648      *                                      independently as itself.
2649      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2650      */
2651     public boolean remoteAppend(final String fileName) throws IOException {
2652         if (dataConnectionMode == ACTIVE_REMOTE_DATA_CONNECTION_MODE || dataConnectionMode == PASSIVE_REMOTE_DATA_CONNECTION_MODE) {
2653             return FTPReply.isPositivePreliminary(appe(fileName));
2654         }
2655         return false;
2656     }
2657 
2658     /**
2659      * Initiate a server to server file transfer. This method tells the server to which the client is connected to retrieve a given file from the other server.
2660      *
2661      * @param fileName The name of the file to retrieve.
2662      * @return True if successfully completed, false if not.
2663      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2664      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2665      *                                      independently as itself.
2666      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2667      */
2668     public boolean remoteRetrieve(final String fileName) throws IOException {
2669         if (dataConnectionMode == ACTIVE_REMOTE_DATA_CONNECTION_MODE || dataConnectionMode == PASSIVE_REMOTE_DATA_CONNECTION_MODE) {
2670             return FTPReply.isPositivePreliminary(retr(fileName));
2671         }
2672         return false;
2673     }
2674 
2675     /**
2676      * Initiate a server to server file transfer. This method tells the server to which the client is connected to store a file on the other server using the
2677      * given file name. The other server must have had a <code>remoteRetrieve</code> issued to it by another FTPClient.
2678      *
2679      * @param fileName The name to call the file that is to be stored.
2680      * @return True if successfully completed, false if not.
2681      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2682      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2683      *                                      independently as itself.
2684      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2685      */
2686     public boolean remoteStore(final String fileName) throws IOException {
2687         if (dataConnectionMode == ACTIVE_REMOTE_DATA_CONNECTION_MODE || dataConnectionMode == PASSIVE_REMOTE_DATA_CONNECTION_MODE) {
2688             return FTPReply.isPositivePreliminary(stor(fileName));
2689         }
2690         return false;
2691     }
2692 
2693     /**
2694      * Initiate a server to server file transfer. This method tells the server to which the client is connected to store a file on the other server using a
2695      * unique file name. The other server must have had a <code>remoteRetrieve</code> issued to it by another FTPClient. Many FTP servers require that a base
2696      * file name be given from which the unique file name can be derived. For those servers use the other version of <code>remoteStoreUnique</code>
2697      *
2698      * @return True if successfully completed, false if not.
2699      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2700      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2701      *                                      independently as itself.
2702      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2703      */
2704     public boolean remoteStoreUnique() throws IOException {
2705         if (dataConnectionMode == ACTIVE_REMOTE_DATA_CONNECTION_MODE || dataConnectionMode == PASSIVE_REMOTE_DATA_CONNECTION_MODE) {
2706             return FTPReply.isPositivePreliminary(stou());
2707         }
2708         return false;
2709     }
2710 
2711     /**
2712      * Initiate a server to server file transfer. This method tells the server to which the client is connected to store a file on the other server using a
2713      * unique file name based on the given file name. The other server must have had a <code>remoteRetrieve</code> issued to it by another FTPClient.
2714      *
2715      * @param fileName The name on which to base the file name of the file that is to be stored.
2716      * @return True if successfully completed, false if not.
2717      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2718      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2719      *                                      independently as itself.
2720      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2721      */
2722     public boolean remoteStoreUnique(final String fileName) throws IOException {
2723         if (dataConnectionMode == ACTIVE_REMOTE_DATA_CONNECTION_MODE || dataConnectionMode == PASSIVE_REMOTE_DATA_CONNECTION_MODE) {
2724             return FTPReply.isPositivePreliminary(stou(fileName));
2725         }
2726         return false;
2727     }
2728 
2729     /**
2730      * Removes a directory on the FTP server (if empty).
2731      *
2732      * @param pathname The pathname of the directory to remove.
2733      * @return True if successfully completed, false if not.
2734      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2735      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2736      *                                      independently as itself.
2737      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2738      */
2739     public boolean removeDirectory(final String pathname) throws IOException {
2740         return FTPReply.isPositiveCompletion(rmd(pathname));
2741     }
2742 
2743     /**
2744      * Renames a remote file.
2745      *
2746      * @param from The name of the remote file to rename.
2747      * @param to   The new name of the remote file.
2748      * @return True if successfully completed, false if not.
2749      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2750      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2751      *                                      independently as itself.
2752      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2753      */
2754     public boolean rename(final String from, final String to) throws IOException {
2755         if (!FTPReply.isPositiveIntermediate(rnfr(from))) {
2756             return false;
2757         }
2758         return FTPReply.isPositiveCompletion(rnto(to));
2759     }
2760 
2761     /**
2762      * Restart a <code>STREAM_TRANSFER_MODE</code> file transfer starting from the given offset. This will only work on FTP servers supporting the REST comand
2763      * for the stream transfer mode. However, most FTP servers support this. Any subsequent file transfer will start reading or writing the remote file from the
2764      * indicated offset.
2765      *
2766      * @param offset The offset into the remote file at which to start the next file transfer.
2767      * @return True if successfully completed, false if not.
2768      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2769      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2770      *                                      independently as itself.
2771      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2772      * @since 3.1 (changed from private to protected)
2773      */
2774     protected boolean restart(final long offset) throws IOException {
2775         restartOffset = 0;
2776         return FTPReply.isPositiveIntermediate(rest(Long.toString(offset)));
2777     }
2778 
2779     /**
2780      * Retrieves a named file from the server and writes it to the given OutputStream. This method does NOT close the given OutputStream. If the current file
2781      * type is ASCII, line separators in the file are converted to the local representation.
2782      * <p>
2783      * Note: if you have used {@link #setRestartOffset(long)}, the file data will start from the selected offset.
2784      *
2785      * @param remote The name of the remote file.
2786      * @param local  The local OutputStream to which to write the file.
2787      * @return True if successfully completed, false if not.
2788      * @throws FTPConnectionClosedException                  If the FTP server prematurely closes the connection as a result of the client being idle or some
2789      *                                                       other reason causing the server to send FTP reply code 421. This exception may be caught either as
2790      *                                                       an IOException or independently as itself.
2791      * @throws org.apache.commons.net.io.CopyStreamException If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to
2792      *                                                       determine the number of bytes transferred and the IOException causing the error. This exception may
2793      *                                                       be caught either as an IOException or independently as itself.
2794      * @throws IOException                                   If an I/O error occurs while either sending a command to the server or receiving a reply from the
2795      *                                                       server.
2796      */
2797     public boolean retrieveFile(final String remote, final OutputStream local) throws IOException {
2798         return _retrieveFile(FTPCmd.RETR.getCommand(), remote, local);
2799     }
2800 
2801     /**
2802      * Returns an InputStream from which a named file from the server can be read. If the current file type is ASCII, the returned InputStream will convert line
2803      * separators in the file to the local representation. You must close the InputStream when you finish reading from it. The InputStream itself will take care
2804      * of closing the parent data connection socket upon being closed.
2805      * <p>
2806      * <b>To finalize the file transfer you must call {@link #completePendingCommand completePendingCommand } and check its return value to verify success.</b>
2807      * If this is not done, subsequent commands may behave unexpectedly.
2808      * <p>
2809      * Note: if you have used {@link #setRestartOffset(long)}, the file data will start from the selected offset.
2810      *
2811      * @param remote The name of the remote file.
2812      * @return An InputStream from which the remote file can be read. If the data connection cannot be opened (e.g., the file does not exist), null is returned
2813      *         (in which case you may check the reply code to determine the exact reason for failure).
2814      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2815      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2816      *                                      independently as itself.
2817      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2818      */
2819     public InputStream retrieveFileStream(final String remote) throws IOException {
2820         return _retrieveFileStream(FTPCmd.RETR.getCommand(), remote);
2821     }
2822 
2823     /**
2824      * Sends a NOOP command to the FTP server. This is useful for preventing server timeouts.
2825      *
2826      * @return True if successfully completed, false if not.
2827      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2828      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2829      *                                      independently as itself.
2830      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2831      */
2832     public boolean sendNoOp() throws IOException {
2833         return FTPReply.isPositiveCompletion(noop());
2834     }
2835 
2836     /**
2837      * Send a site specific command.
2838      *
2839      * @param arguments The site specific command and arguments.
2840      * @return True if successfully completed, false if not.
2841      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2842      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2843      *                                      independently as itself.
2844      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2845      */
2846     public boolean sendSiteCommand(final String arguments) throws IOException {
2847         return FTPReply.isPositiveCompletion(site(arguments));
2848     }
2849 
2850     /**
2851      * Sets the external IP address in active mode. Useful when there are multiple network cards.
2852      *
2853      * @param ipAddress The external IP address of this machine.
2854      * @throws UnknownHostException if the ipAddress cannot be resolved
2855      * @since 2.2
2856      */
2857     public void setActiveExternalIPAddress(final String ipAddress) throws UnknownHostException {
2858         this.activeExternalHost = InetAddress.getByName(ipAddress);
2859     }
2860 
2861     /**
2862      * Sets the client side port range in active mode.
2863      *
2864      * @param minPort The lowest available port (inclusive).
2865      * @param maxPort The highest available port (inclusive).
2866      * @since 2.2
2867      */
2868     public void setActivePortRange(final int minPort, final int maxPort) {
2869         this.activeMinPort = minPort;
2870         this.activeMaxPort = maxPort;
2871     }
2872 
2873     /**
2874      * Enables or disables automatic server encoding detection (only UTF-8 supported).
2875      * <p>
2876      * Does not affect existing connections; must be invoked before a connection is established.
2877      * </p>
2878      *
2879      * @param autodetect If true, automatic server encoding detection will be enabled.
2880      */
2881     public void setAutodetectUTF8(final boolean autodetect) {
2882         autodetectEncoding = autodetect;
2883     }
2884 
2885     /**
2886      * Sets the internal buffer size for buffered data streams.
2887      *
2888      * @param bufSize The size of the buffer. Use a non-positive value to use the default.
2889      */
2890     public void setBufferSize(final int bufSize) {
2891         bufferSize = bufSize;
2892     }
2893 
2894     /**
2895      * Sets the duration to wait for control keep-alive message replies.
2896      *
2897      * @param timeout duration to wait (defaults to 1,000). Zero (or less) disables.
2898      * @since 3.0
2899      * @see #setControlKeepAliveTimeout(Duration)
2900      */
2901     public void setControlKeepAliveReplyTimeout(final Duration timeout) {
2902         controlKeepAliveReplyTimeout = DurationUtils.zeroIfNull(timeout);
2903     }
2904 
2905     /**
2906      * Sets the duration to wait for control keep-alive message replies.
2907      *
2908      * @deprecated Use {@link #setControlKeepAliveReplyTimeout(Duration)}.
2909      * @param timeoutMillis number of milliseconds to wait (defaults to 1,000).
2910      * @since 3.0
2911      * @see #setControlKeepAliveTimeout(long)
2912      */
2913     @Deprecated
2914     public void setControlKeepAliveReplyTimeout(final int timeoutMillis) {
2915         controlKeepAliveReplyTimeout = Duration.ofMillis(timeoutMillis);
2916     }
2917 
2918     /**
2919      * Sets the duration to wait between sending control connection keepalive messages when processing file upload or download.
2920      * <p>
2921      * See the class Javadoc section "Control channel keep-alive feature"
2922      * </p>
2923      *
2924      * @param controlIdle the duration to wait between keepalive messages. Zero (or less) disables.
2925      * @since 3.9.0
2926      * @see #setControlKeepAliveReplyTimeout(Duration)
2927      */
2928     public void setControlKeepAliveTimeout(final Duration controlIdle) {
2929         controlKeepAliveTimeout = DurationUtils.zeroIfNull(controlIdle);
2930     }
2931 
2932     /**
2933      * Sets the duration to wait between sending control connection keepalive messages when processing file upload or download.
2934      * <p>
2935      * See the class Javadoc section "Control channel keep-alive feature"
2936      * </p>
2937      *
2938      * @deprecated Use {@link #setControlKeepAliveTimeout(Duration)}.
2939      * @param controlIdleSeconds the wait in seconds between keepalive messages. Zero (or less) disables.
2940      * @since 3.0
2941      * @see #setControlKeepAliveReplyTimeout(int)
2942      */
2943     @Deprecated
2944     public void setControlKeepAliveTimeout(final long controlIdleSeconds) {
2945         controlKeepAliveTimeout = Duration.ofSeconds(controlIdleSeconds);
2946     }
2947 
2948     /**
2949      * Sets the listener to be used when performing store/retrieve operations. The default value (if not set) is {@code null}.
2950      *
2951      * @param listener to be used, may be {@code null} to disable
2952      * @since 3.0
2953      */
2954     public void setCopyStreamListener(final CopyStreamListener listener) {
2955         copyStreamListener = listener;
2956     }
2957 
2958     /**
2959      * Sets the timeout to use when reading from the data connection. This timeout will be set immediately after opening the data connection, provided that the
2960      * value is &ge; 0.
2961      * <p>
2962      * <b>Note:</b> the timeout will also be applied when calling accept() whilst establishing an active local data connection.
2963      * </p>
2964      *
2965      * @param timeout The default timeout that is used when opening a data connection socket. The value 0 (or null) means an infinite timeout.
2966      * @since 3.9.0
2967      */
2968     public void setDataTimeout(final Duration timeout) {
2969         dataTimeout = DurationUtils.zeroIfNull(timeout);
2970     }
2971 
2972     /**
2973      * Sets the timeout in milliseconds to use when reading from the data connection. This timeout will be set immediately after opening the data connection,
2974      * provided that the value is &ge; 0.
2975      * <p>
2976      * <b>Note:</b> the timeout will also be applied when calling accept() whilst establishing an active local data connection.
2977      * </p>
2978      *
2979      * @deprecated Use {@link #setDataTimeout(Duration)}.
2980      * @param timeoutMillis The default timeout in milliseconds that is used when opening a data connection socket. The value 0 means an infinite timeout.
2981      */
2982     @Deprecated
2983     public void setDataTimeout(final int timeoutMillis) {
2984         dataTimeout = Duration.ofMillis(timeoutMillis);
2985     }
2986 
2987     /**
2988      * Sets the file structure. The default structure is <code>FTP.FILE_STRUCTURE</code> if this method is never called or if a connect method is called.
2989      *
2990      * @param structure The structure of the file (one of the FTP class <code>_STRUCTURE</code> constants).
2991      * @return True if successfully completed, false if not.
2992      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
2993      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
2994      *                                      independently as itself.
2995      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
2996      */
2997     public boolean setFileStructure(final int structure) throws IOException {
2998         if (FTPReply.isPositiveCompletion(stru(structure))) {
2999             fileStructure = structure;
3000             return true;
3001         }
3002         return false;
3003     }
3004 
3005     /**
3006      * Sets the transfer mode. The default transfer mode <code>FTP.STREAM_TRANSFER_MODE</code> if this method is never called or if a connect method is
3007      * called.
3008      *
3009      * @param mode The new transfer mode to use (one of the FTP class <code>_TRANSFER_MODE</code> constants).
3010      * @return True if successfully completed, false if not.
3011      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
3012      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
3013      *                                      independently as itself.
3014      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
3015      */
3016     public boolean setFileTransferMode(final int mode) throws IOException {
3017         if (FTPReply.isPositiveCompletion(mode(mode))) {
3018             fileTransferMode = mode;
3019             return true;
3020         }
3021         return false;
3022     }
3023 
3024     /**
3025      * Sets the file type to be transferred. This should be one of <code>FTP.ASCII_FILE_TYPE</code>, <code>FTP.BINARY_FILE_TYPE</code>, etc. The file type
3026      * only needs to be set when you want to change the type. After changing it, the new type stays in effect until you change it again. The default file type
3027      * is <code>FTP.ASCII_FILE_TYPE</code> if this method is never called. <br>
3028      * The server default is supposed to be ASCII (see RFC 959), however many ftp servers default to BINARY. <b>To ensure correct operation with all servers,
3029      * always specify the appropriate file type after connecting to the server.</b> <br>
3030      * <p>
3031      * <b>N.B.</b> currently calling any connect method will reset the type to FTP.ASCII_FILE_TYPE.
3032      *
3033      * @param fileType The <code>_FILE_TYPE</code> constant indicating the type of file.
3034      * @return True if successfully completed, false if not.
3035      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
3036      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
3037      *                                      independently as itself.
3038      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
3039      */
3040     public boolean setFileType(final int fileType) throws IOException {
3041         if (FTPReply.isPositiveCompletion(type(fileType))) {
3042             this.fileType = fileType;
3043             this.fileFormat = FTP.NON_PRINT_TEXT_FORMAT;
3044             return true;
3045         }
3046         return false;
3047     }
3048 
3049     /**
3050      * Sets the file type to be transferred and the format. The type should be one of <code>FTP.ASCII_FILE_TYPE</code>, <code>FTP.BINARY_FILE_TYPE</code>,
3051      * etc. The file type only needs to be set when you want to change the type. After changing it, the new type stays in effect until you change it again. The
3052      * default file type is <code>FTP.ASCII_FILE_TYPE</code> if this method is never called. <br>
3053      * The server default is supposed to be ASCII (see RFC 959), however many ftp servers default to BINARY. <b>To ensure correct operation with all servers,
3054      * always specify the appropriate file type after connecting to the server.</b> <br>
3055      * The format should be one of the FTP class <code>TEXT_FORMAT</code> constants, or if the type is <code>FTP.LOCAL_FILE_TYPE</code>, the format should
3056      * be the byte size for that type. The default format is <code>FTP.NON_PRINT_TEXT_FORMAT</code> if this method is never called.
3057      * <p>
3058      * <b>N.B.</b> currently calling any connect method will reset the type to FTP.ASCII_FILE_TYPE and the formatOrByteSize to FTP.NON_PRINT_TEXT_FORMAT.
3059      * </p>
3060      *
3061      * @param fileType         The <code>_FILE_TYPE</code> constant indicating the type of file.
3062      * @param formatOrByteSize The format of the file (one of the <code>_FORMAT</code> constants). In the case of <code>LOCAL_FILE_TYPE</code>, the byte size.
3063      * @return True if successfully completed, false if not.
3064      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
3065      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
3066      *                                      independently as itself.
3067      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
3068      */
3069     public boolean setFileType(final int fileType, final int formatOrByteSize) throws IOException {
3070         if (FTPReply.isPositiveCompletion(type(fileType, formatOrByteSize))) {
3071             this.fileType = fileType;
3072             this.fileFormat = formatOrByteSize;
3073             return true;
3074         }
3075         return false;
3076     }
3077 
3078     /**
3079      * Sets whether the IP address from the server's response should be used. Until 3.9.0, this has always been the case. Beginning with 3.9.0, that IP address
3080      * will be silently ignored, and replaced with the remote IP address of the control connection, unless this configuration option is given, which restores
3081      * the old behavior. To enable this by default, use the system property {@link FTPClient#FTP_IP_ADDRESS_FROM_PASV_RESPONSE}.
3082      *
3083      * @param usingIpAddressFromPasvResponse True, if the IP address from the server's response should be used (pre-3.9.0 compatible behavior), or false (ignore
3084      *                                       that IP address).
3085      * @see FTPClient#FTP_IP_ADDRESS_FROM_PASV_RESPONSE
3086      * @see #isIpAddressFromPasvResponse
3087      * @since 3.9.0
3088      */
3089     public void setIpAddressFromPasvResponse(final boolean usingIpAddressFromPasvResponse) {
3090         this.ipAddressFromPasvResponse = usingIpAddressFromPasvResponse;
3091     }
3092 
3093     /**
3094      * You can set this to true if you would like to get hidden files when {@link #listFiles} too. A <code>LIST -a</code> will be issued to the ftp server. It
3095      * depends on your ftp server if you need to call this method, also don't expect to get rid of hidden files if you call this method with "false".
3096      *
3097      * @param listHiddenFiles true if hidden files should be listed
3098      * @since 2.0
3099      */
3100     public void setListHiddenFiles(final boolean listHiddenFiles) {
3101         this.listHiddenFiles = listHiddenFiles;
3102     }
3103 
3104     /**
3105      * Issue the FTP MFMT command (not supported by all servers) which sets the last modified time of a file.
3106      *
3107      * The timestamp should be in the form <code>yyyyMMDDhhmmss</code>. It should also be in GMT, but not all servers honor this.
3108      *
3109      * An FTP server would indicate its support of this feature by including "MFMT" in its response to the FEAT command, which may be retrieved by
3110      * FTPClient.features()
3111      *
3112      * @param pathname The file path for which last modified time is to be changed.
3113      * @param timeval  The timestamp to set to, in <code>yyyyMMDDhhmmss</code> format.
3114      * @return true if successfully set, false if not
3115      * @throws IOException if an I/O error occurs.
3116      * @since 2.2
3117      * @see <a href="https://tools.ietf.org/html/draft-somers-ftp-mfxx-04">https://tools.ietf.org/html/draft-somers-ftp-mfxx-04</a>
3118      */
3119     public boolean setModificationTime(final String pathname, final String timeval) throws IOException {
3120         return FTPReply.isPositiveCompletion(mfmt(pathname, timeval));
3121     }
3122 
3123     /**
3124      * set the factory used for parser creation to the supplied factory object.
3125      *
3126      * @param parserFactory factory object used to create FTPFileEntryParsers
3127      *
3128      * @see org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory
3129      * @see org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory
3130      */
3131     public void setParserFactory(final FTPFileEntryParserFactory parserFactory) {
3132         this.parserFactory = parserFactory;
3133     }
3134 
3135     /**
3136      * Sets the local IP address to use in passive mode. Useful when there are multiple network cards.
3137      *
3138      * @param inetAddress The local IP address of this machine.
3139      */
3140     public void setPassiveLocalIPAddress(final InetAddress inetAddress) {
3141         this.passiveLocalHost = inetAddress;
3142     }
3143 
3144     /**
3145      * Sets the local IP address to use in passive mode. Useful when there are multiple network cards.
3146      *
3147      * @param ipAddress The local IP address of this machine.
3148      * @throws UnknownHostException if the ipAddress cannot be resolved
3149      */
3150     public void setPassiveLocalIPAddress(final String ipAddress) throws UnknownHostException {
3151         this.passiveLocalHost = InetAddress.getByName(ipAddress);
3152     }
3153 
3154     /**
3155      * Enables or disables passive mode NAT workaround. If enabled, a site-local PASV mode reply address will be replaced with the remote host address to which
3156      * the PASV mode request was sent (unless that is also a site local address). This gets around the problem that some NAT boxes may change the reply.
3157      * <p>
3158      * The default is true, i.e. site-local replies are replaced.
3159      * </p>
3160      *
3161      * @deprecated (3.6) use {@link #setPassiveNatWorkaroundStrategy(HostnameResolver)} instead
3162      * @param enabled true to enable replacing internal IP's in passive mode.
3163      */
3164     @Deprecated
3165     public void setPassiveNatWorkaround(final boolean enabled) {
3166         this.passiveNatWorkaroundStrategy = enabled ? new NatServerResolverImpl(this) : null;
3167     }
3168 
3169     /**
3170      * Sets the workaround strategy to replace the PASV mode reply addresses. This gets around the problem that some NAT boxes may change the reply.
3171      *
3172      * The default implementation is {@code NatServerResolverImpl}, i.e. site-local replies are replaced.
3173      *
3174      * @param resolver strategy to replace internal IP's in passive mode or null to disable the workaround (i.e. use PASV mode reply address.)
3175      * @since 3.6
3176      */
3177     public void setPassiveNatWorkaroundStrategy(final HostnameResolver resolver) {
3178         this.passiveNatWorkaroundStrategy = resolver;
3179     }
3180 
3181     /**
3182      * Sets the value to be used for the data socket SO_RCVBUF option. If the value is positive, the option will be set when the data socket has been created.
3183      *
3184      * @param bufSize The size of the buffer, zero or negative means the value is ignored.
3185      * @since 3.3
3186      */
3187     public void setReceieveDataSocketBufferSize(final int bufSize) {
3188         receiveDataSocketBufferSize = bufSize;
3189     }
3190 
3191     /**
3192      * Enable or disable verification that the remote host taking part of a data connection is the same as the host to which the control connection is attached.
3193      * The default is for verification to be enabled. You may set this value at any time, whether the FTPClient is currently connected or not.
3194      *
3195      * @param enable True to enable verification, false to disable verification.
3196      */
3197     public void setRemoteVerificationEnabled(final boolean enable) {
3198         remoteVerificationEnabled = enable;
3199     }
3200 
3201     /**
3202      * Sets the external IP address to report in EPRT/PORT commands in active mode. Useful when there are multiple network cards.
3203      *
3204      * @param ipAddress The external IP address of this machine.
3205      * @throws UnknownHostException if the ipAddress cannot be resolved
3206      * @since 3.1
3207      * @see #getReportHostAddress()
3208      */
3209     public void setReportActiveExternalIPAddress(final String ipAddress) throws UnknownHostException {
3210         this.reportActiveExternalHost = InetAddress.getByName(ipAddress);
3211     }
3212 
3213     /**
3214      * Sets the restart offset for file transfers.
3215      * <p>
3216      * The restart command is not sent to the server immediately. It is sent when a data connection is created as part of a subsequent command. The restart
3217      * marker is reset to zero after use.
3218      * </p>
3219      * <p>
3220      * <b>Note: This method should only be invoked immediately prior to the transfer to which it applies.</b>
3221      * </p>
3222      *
3223      * @param offset The offset into the remote file at which to start the next file transfer. This must be a value greater than or equal to zero.
3224      */
3225     public void setRestartOffset(final long offset) {
3226         if (offset >= 0) {
3227             restartOffset = offset;
3228         }
3229     }
3230 
3231     /**
3232      * Sets the value to be used for the data socket SO_SNDBUF option. If the value is positive, the option will be set when the data socket has been created.
3233      *
3234      * @param bufSize The size of the buffer, zero or negative means the value is ignored.
3235      * @since 3.3
3236      */
3237     public void setSendDataSocketBufferSize(final int bufSize) {
3238         sendDataSocketBufferSize = bufSize;
3239     }
3240 
3241     /**
3242      * Sets whether to use EPSV with IPv4. Might be worth enabling in some circumstances.
3243      *
3244      * For example, when using IPv4 with NAT it may work with some rare configurations. E.g. if FTP server has a static PASV address (external network) and the
3245      * client is coming from another internal network. In that case the data connection after PASV command would fail, while EPSV would make the client succeed
3246      * by taking just the port.
3247      *
3248      * @param selected value to set.
3249      * @since 2.2
3250      */
3251     public void setUseEPSVwithIPv4(final boolean selected) {
3252         this.useEPSVwithIPv4 = selected;
3253     }
3254 
3255     private boolean storeFile(final FTPCmd command, final String remote, final InputStream local) throws IOException {
3256         return _storeFile(command.getCommand(), remote, local);
3257     }
3258 
3259     /**
3260      * Stores a file on the server using the given name and taking input from the given InputStream. This method does NOT close the given InputStream. If the
3261      * current file type is ASCII, line separators in the file are transparently converted to the NETASCII format (i.e., you should not attempt to create a
3262      * special InputStream to do this).
3263      *
3264      * @param remote The name to give the remote file.
3265      * @param local  The local InputStream from which to read the file.
3266      * @return True if successfully completed, false if not.
3267      * @throws FTPConnectionClosedException                  If the FTP server prematurely closes the connection as a result of the client being idle or some
3268      *                                                       other reason causing the server to send FTP reply code 421. This exception may be caught either as
3269      *                                                       an IOException or independently as itself.
3270      * @throws org.apache.commons.net.io.CopyStreamException If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to
3271      *                                                       determine the number of bytes transferred and the IOException causing the error. This exception may
3272      *                                                       be caught either as an IOException or independently as itself.
3273      * @throws IOException                                   If an I/O error occurs while either sending a command to the server or receiving a reply from the
3274      *                                                       server.
3275      */
3276     public boolean storeFile(final String remote, final InputStream local) throws IOException {
3277         return storeFile(FTPCmd.STOR, remote, local);
3278     }
3279 
3280     private OutputStream storeFileStream(final FTPCmd command, final String remote) throws IOException {
3281         return _storeFileStream(command.getCommand(), remote);
3282     }
3283 
3284     /**
3285      * Returns an OutputStream through which data can be written to store a file on the server using the given name. If the current file type is ASCII, the
3286      * returned OutputStream will convert line separators in the file to the NETASCII format (i.e., you should not attempt to create a special OutputStream to
3287      * do this). You must close the OutputStream when you finish writing to it. The OutputStream itself will take care of closing the parent data connection
3288      * socket upon being closed.
3289      * <p>
3290      * <b>To finalize the file transfer you must call {@link #completePendingCommand completePendingCommand } and check its return value to verify success.</b>
3291      * If this is not done, subsequent commands may behave unexpectedly.
3292      * </p>
3293      *
3294      * @param remote The name to give the remote file.
3295      * @return An OutputStream through which the remote file can be written. If the data connection cannot be opened (e.g., the file does not exist), null is
3296      *         returned (in which case you may check the reply code to determine the exact reason for failure).
3297      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
3298      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
3299      *                                      independently as itself.
3300      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
3301      */
3302     public OutputStream storeFileStream(final String remote) throws IOException {
3303         return storeFileStream(FTPCmd.STOR, remote);
3304     }
3305 
3306     /**
3307      * Stores a file on the server using a unique name assigned by the server and taking input from the given InputStream. This method does NOT close the given
3308      * InputStream. If the current file type is ASCII, line separators in the file are transparently converted to the NETASCII format (i.e., you should not
3309      * attempt to create a special InputStream to do this).
3310      *
3311      * @param local The local InputStream from which to read the file.
3312      * @return True if successfully completed, false if not.
3313      * @throws FTPConnectionClosedException                  If the FTP server prematurely closes the connection as a result of the client being idle or some
3314      *                                                       other reason causing the server to send FTP reply code 421. This exception may be caught either as
3315      *                                                       an IOException or independently as itself.
3316      * @throws org.apache.commons.net.io.CopyStreamException If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to
3317      *                                                       determine the number of bytes transferred and the IOException causing the error. This exception may
3318      *                                                       be caught either as an IOException or independently as itself.
3319      * @throws IOException                                   If an I/O error occurs while either sending a command to the server or receiving a reply from the
3320      *                                                       server.
3321      */
3322     public boolean storeUniqueFile(final InputStream local) throws IOException {
3323         return storeFile(FTPCmd.STOU, null, local);
3324     }
3325 
3326     /**
3327      * Stores a file on the server using a unique name derived from the given name and taking input from the given InputStream. This method does NOT close the
3328      * given InputStream. If the current file type is ASCII, line separators in the file are transparently converted to the NETASCII format (i.e., you should
3329      * not attempt to create a special InputStream to do this).
3330      *
3331      * @param remote The name on which to base the unique name given to the remote file.
3332      * @param local  The local InputStream from which to read the file.
3333      * @return True if successfully completed, false if not.
3334      * @throws FTPConnectionClosedException                  If the FTP server prematurely closes the connection as a result of the client being idle or some
3335      *                                                       other reason causing the server to send FTP reply code 421. This exception may be caught either as
3336      *                                                       an IOException or independently as itself.
3337      * @throws org.apache.commons.net.io.CopyStreamException If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to
3338      *                                                       determine the number of bytes transferred and the IOException causing the error. This exception may
3339      *                                                       be caught either as an IOException or independently as itself.
3340      * @throws IOException                                   If an I/O error occurs while either sending a command to the server or receiving a reply from the
3341      *                                                       server.
3342      */
3343     public boolean storeUniqueFile(final String remote, final InputStream local) throws IOException {
3344         return storeFile(FTPCmd.STOU, remote, local);
3345     }
3346 
3347     /**
3348      * Returns an OutputStream through which data can be written to store a file on the server using a unique name assigned by the server. If the current file
3349      * type is ASCII, the returned OutputStream will convert line separators in the file to the NETASCII format (i.e., you should not attempt to create a
3350      * special OutputStream to do this). You must close the OutputStream when you finish writing to it. The OutputStream itself will take care of closing the
3351      * parent data connection socket upon being closed.
3352      * <p>
3353      * <b>To finalize the file transfer you must call {@link #completePendingCommand completePendingCommand } and check its return value to verify success.</b>
3354      * If this is not done, subsequent commands may behave unexpectedly.
3355      * </p>
3356      *
3357      * @return An OutputStream through which the remote file can be written. If the data connection cannot be opened (e.g., the file does not exist), null is
3358      *         returned (in which case you may check the reply code to determine the exact reason for failure).
3359      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
3360      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
3361      *                                      independently as itself.
3362      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
3363      */
3364     public OutputStream storeUniqueFileStream() throws IOException {
3365         return storeFileStream(FTPCmd.STOU, null);
3366     }
3367 
3368     /**
3369      * Returns an OutputStream through which data can be written to store a file on the server using a unique name derived from the given name. If the current
3370      * file type is ASCII, the returned OutputStream will convert line separators in the file to the NETASCII format (i.e., you should not attempt to create a
3371      * special OutputStream to do this). You must close the OutputStream when you finish writing to it. The OutputStream itself will take care of closing the
3372      * parent data connection socket upon being closed.
3373      * <p>
3374      * <b>To finalize the file transfer you must call {@link #completePendingCommand completePendingCommand } and check its return value to verify success.</b>
3375      * If this is not done, subsequent commands may behave unexpectedly.
3376      *
3377      * @param remote The name on which to base the unique name given to the remote file.
3378      * @return An OutputStream through which the remote file can be written. If the data connection cannot be opened (e.g., the file does not exist), null is
3379      *         returned (in which case you may check the reply code to determine the exact reason for failure).
3380      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
3381      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
3382      *                                      independently as itself.
3383      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
3384      */
3385     public OutputStream storeUniqueFileStream(final String remote) throws IOException {
3386         return storeFileStream(FTPCmd.STOU, remote);
3387     }
3388 
3389     /**
3390      * Issue the FTP SMNT command.
3391      *
3392      * @param pathname The pathname to mount.
3393      * @return True if successfully completed, false if not.
3394      * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason
3395      *                                      causing the server to send FTP reply code 421. This exception may be caught either as an IOException or
3396      *                                      independently as itself.
3397      * @throws IOException                  If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
3398      */
3399     public boolean structureMount(final String pathname) throws IOException {
3400         return FTPReply.isPositiveCompletion(smnt(pathname));
3401     }
3402 
3403     private Socket wrapOnDeflate(final Socket plainSocket) {
3404         switch (fileTransferMode) {
3405         case DEFLATE_TRANSFER_MODE:
3406             return new DeflateSocket(plainSocket);
3407         // Experiment, not in an RFC?
3408         // case GZIP_TRANSFER_MODE:
3409             //return new GZIPSocket(plainSocket);
3410         default:
3411             return plainSocket;
3412         }
3413     }
3414 }