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