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