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