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