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