1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.net.ftp; 18 19 import java.io.BufferedInputStream; 20 import java.io.BufferedOutputStream; 21 import java.io.BufferedReader; 22 import java.io.BufferedWriter; 23 import java.io.IOException; 24 import java.io.InputStream; 25 import java.io.InputStreamReader; 26 import java.io.OutputStream; 27 import java.io.OutputStreamWriter; 28 import java.io.Reader; 29 import java.net.Inet6Address; 30 import java.net.InetAddress; 31 import java.net.InetSocketAddress; 32 import java.net.ServerSocket; 33 import java.net.Socket; 34 import java.net.SocketException; 35 import java.net.SocketTimeoutException; 36 import java.net.UnknownHostException; 37 import java.time.Duration; 38 import java.time.Instant; 39 import java.util.ArrayList; 40 import java.util.Calendar; 41 import java.util.HashMap; 42 import java.util.HashSet; 43 import java.util.Locale; 44 import java.util.Properties; 45 import java.util.Random; 46 import java.util.Set; 47 import java.util.regex.Matcher; 48 49 import org.apache.commons.net.MalformedServerReplyException; 50 import org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory; 51 import org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory; 52 import org.apache.commons.net.ftp.parser.MLSxEntryParser; 53 import org.apache.commons.net.io.CRLFLineReader; 54 import org.apache.commons.net.io.CopyStreamAdapter; 55 import org.apache.commons.net.io.CopyStreamEvent; 56 import org.apache.commons.net.io.CopyStreamListener; 57 import org.apache.commons.net.io.FromNetASCIIInputStream; 58 import org.apache.commons.net.io.SocketOutputStream; 59 import org.apache.commons.net.io.ToNetASCIIOutputStream; 60 import org.apache.commons.net.io.Util; 61 import org.apache.commons.net.util.NetConstants; 62 63 /** 64 * FTPClient encapsulates all the functionality necessary to store and retrieve files from an FTP server. This class takes care of all low level details of 65 * interacting with an FTP server and provides a convenient higher level interface. As with all classes derived from 66 * {@link org.apache.commons.net.SocketClient}, you must first connect to the server with {@link org.apache.commons.net.SocketClient#connect connect } before 67 * doing anything, and finally {@link org.apache.commons.net.SocketClient#disconnect disconnect } after you're completely finished interacting with the server. 68 * Then you need to check the FTP reply code to see if the connection was successful. For example: 69 * 70 * <pre> 71 * FTPClient ftp = new FTPClient(); 72 * FTPClientConfig config = new FTPClientConfig(); 73 * config.setXXX(YYY); // change required options 74 * // for example config.setServerTimeZoneId("Pacific/Pitcairn") 75 * ftp.configure(config ); 76 * boolean error = false; 77 * try { 78 * int reply; 79 * String server = "ftp.example.com"; 80 * ftp.connect(server); 81 * System.out.println("Connected to " + server + "."); 82 * System.out.print(ftp.getReplyString()); 83 * 84 * // After connection attempt, you should check the reply code to verify 85 * // success. 86 * reply = ftp.getReplyCode(); 87 * 88 * if (!FTPReply.isPositiveCompletion(reply)) { 89 * ftp.disconnect(); 90 * System.err.println("FTP server refused connection."); 91 * System.exit(1); 92 * } 93 * ... // transfer files 94 * ftp.logout(); 95 * } catch (IOException e) { 96 * error = true; 97 * e.printStackTrace(); 98 * } finally { 99 * if (ftp.isConnected()) { 100 * try { 101 * ftp.disconnect(); 102 * } catch (IOException ioe) { 103 * // do nothing 104 * } 105 * } 106 * System.exit(error ? 1 : 0); 107 * } 108 * </pre> 109 * <p> 110 * Immediately after connecting is the only real time you need to check the reply code (because connect is of type void). The convention for all the FTP command 111 * methods in FTPClient is such that they either return a boolean value or some other value. The boolean methods return true on a successful completion reply 112 * from the FTP server and false on a reply resulting in an error condition or failure. The methods returning a value other than boolean return a value 113 * containing the higher level data produced by the FTP command, or null if a reply resulted in an error condition or failure. If you want to access the exact 114 * FTP reply code causing a success or failure, you must call {@link org.apache.commons.net.ftp.FTP#getReplyCode getReplyCode } after a success or failure. 115 * <p> 116 * The default settings for FTPClient are for it to use <code> FTP.ASCII_FILE_TYPE </code>, <code> FTP.NON_PRINT_TEXT_FORMAT </code>, 117 * <code> FTP.STREAM_TRANSFER_MODE </code>, and <code> FTP.FILE_STRUCTURE </code>. The only file types directly supported are <code> FTP.ASCII_FILE_TYPE </code> 118 * and <code> FTP.BINARY_FILE_TYPE </code>. Because there are at least 4 different EBCDIC encodings, we have opted not to provide direct support for EBCDIC. To 119 * transfer EBCDIC and other unsupported file types you must create your own filter InputStreams and OutputStreams and wrap them around the streams returned or 120 * required by the FTPClient methods. FTPClient uses the {@link ToNetASCIIOutputStream NetASCII} filter streams to provide transparent handling of ASCII files. 121 * We will consider incorporating EBCDIC support if there is enough demand. 122 * <p> 123 * <code> FTP.NON_PRINT_TEXT_FORMAT </code>, <code> FTP.STREAM_TRANSFER_MODE </code>, and <code> FTP.FILE_STRUCTURE </code> are the only supported formats, 124 * transfer modes, and file structures. 125 * <p> 126 * Because the handling of sockets on different platforms can differ significantly, the FTPClient automatically issues a new PORT (or EPRT) command prior to 127 * every transfer requiring that the server connect to the client's data port. This ensures identical problem-free behavior on Windows, Unix, and Macintosh 128 * platforms. Additionally, it relieves programmers from having to issue the PORT (or EPRT) command themselves and dealing with platform dependent issues. 129 * <p> 130 * Additionally, for security purposes, all data connections to the client are verified to ensure that they originated from the intended party (host and port). 131 * If a data connection is initiated by an unexpected party, the command will close the socket and throw an IOException. You may disable this behavior with 132 * {@link #setRemoteVerificationEnabled setRemoteVerificationEnabled()}. 133 * <p> 134 * You should keep in mind that the FTP server may choose to prematurely close a connection if the client has been idle for longer than a given time period 135 * (usually 900 seconds). The FTPClient class will detect a premature FTP server connection closing when it receives a 136 * {@link org.apache.commons.net.ftp.FTPReply#SERVICE_NOT_AVAILABLE FTPReply.SERVICE_NOT_AVAILABLE } response to a command. When that occurs, the FTP class 137 * method encountering that reply will throw an {@link org.apache.commons.net.ftp.FTPConnectionClosedException} . <code>FTPConnectionClosedException</code> is a 138 * subclass of <code> IOException </code> and therefore need not be caught separately, but if you are going to catch it separately, its catch block must appear 139 * before the more general <code> IOException </code> catch block. When you encounter an {@link org.apache.commons.net.ftp.FTPConnectionClosedException} , you 140 * must disconnect the connection with {@link #disconnect disconnect() } to properly clean up the system resources used by FTPClient. Before disconnecting, you 141 * may check the last reply code and text with {@link org.apache.commons.net.ftp.FTP#getReplyCode getReplyCode }, 142 * {@link org.apache.commons.net.ftp.FTP#getReplyString getReplyString }, and {@link org.apache.commons.net.ftp.FTP#getReplyStrings getReplyStrings}. You may 143 * avoid server disconnections while the client is idle by periodically sending NOOP commands to the server. 144 * <p> 145 * Rather than list it separately for each method, we mention here that every method communicating with the server and throwing an IOException can also throw a 146 * {@link org.apache.commons.net.MalformedServerReplyException} , which is a subclass of IOException. A MalformedServerReplyException will be thrown when the 147 * reply received from the server deviates enough from the protocol specification that it cannot be interpreted in a useful manner despite attempts to be as 148 * lenient as possible. 149 * <p> 150 * Listing API Examples Both paged and unpaged examples of directory listings are available, as follows: 151 * <p> 152 * Unpaged (whole list) access, using a parser accessible by auto-detect: 153 * 154 * <pre> 155 * FTPClient f = new FTPClient(); 156 * f.connect(server); 157 * f.login(user, password); 158 * FTPFile[] files = f.listFiles(directory); 159 * </pre> 160 * <p> 161 * Paged access, using a parser not accessible by auto-detect. The class defined in the first parameter of initateListParsing should be derived from 162 * org.apache.commons.net.FTPFileEntryParser: 163 * 164 * <pre> 165 * FTPClient f = new FTPClient(); 166 * f.connect(server); 167 * f.login(user, password); 168 * FTPListParseEngine engine = f.initiateListParsing("com.whatever.YourOwnParser", directory); 169 * 170 * while (engine.hasNext()) { 171 * FTPFile[] files = engine.getNext(25); // "page size" you want 172 * // do whatever you want with these files, display them, etc. 173 * // expensive FTPFile objects not created until needed. 174 * } 175 * </pre> 176 * <p> 177 * Paged access, using a parser accessible by auto-detect: 178 * 179 * <pre> 180 * FTPClient f = new FTPClient(); 181 * f.connect(server); 182 * f.login(user, password); 183 * FTPListParseEngine engine = f.initiateListParsing(directory); 184 * 185 * while (engine.hasNext()) { 186 * FTPFile[] files = engine.getNext(25); // "page size" you want 187 * // do whatever you want with these files, display them, etc. 188 * // expensive FTPFile objects not created until needed. 189 * } 190 * </pre> 191 * <p> 192 * For examples of using FTPClient on servers whose directory listings 193 * <ul> 194 * <li>use languages other than English</li> 195 * <li>use date formats other than the American English "standard" <code>MM d yyyy</code></li> 196 * <li>are in different time zones and you need accurate timestamps for dependency checking as in Ant</li> 197 * </ul> 198 * see {@link FTPClientConfig FTPClientConfig}. 199 * <p> 200 * <b>Control channel keep-alive feature</b>: 201 * <p> 202 * <b>Please note:</b> this does not apply to the methods where the user is responsible for writing or reading the data stream, i.e. 203 * {@link #retrieveFileStream(String)} , {@link #storeFileStream(String)} and the other xxxFileStream methods 204 * <p> 205 * During file transfers, the data connection is busy, but the control connection is idle. FTP servers know that the control connection is in use, so won't 206 * close it through lack of activity, but it's a lot harder for network routers to know that the control and data connections are associated with each other. 207 * Some routers may treat the control connection as idle, and disconnect it if the transfer over the data connection takes longer than the allowable idle time 208 * for the router. <br> 209 * One solution to this is to send a safe command (i.e. NOOP) over the control connection to reset the router's idle timer. This is enabled as follows: 210 * 211 * <pre> 212 * // Set timeout to 5 minutes 213 * ftpClient.setControlKeepAliveTimeout(Duration.ofMinutes(5)); 214 * </pre> 215 * 216 * This will cause the file upload/download methods to send a NOOP approximately every 5 minutes. The following public methods support this: 217 * <ul> 218 * <li>{@link #retrieveFile(String, OutputStream)}</li> 219 * <li>{@link #appendFile(String, InputStream)}</li> 220 * <li>{@link #storeFile(String, InputStream)}</li> 221 * <li>{@link #storeUniqueFile(InputStream)}</li> 222 * <li>{@link #storeUniqueFileStream(String)}</li> 223 * </ul> 224 * This feature does not apply to the methods where the user is responsible for writing or reading the data stream, i.e. {@link #retrieveFileStream(String)} , 225 * {@link #storeFileStream(String)} and the other xxxFileStream methods. In such cases, the user is responsible for keeping the control connection alive if 226 * necessary. 227 * <p> 228 * The implementation currently uses a {@link CopyStreamListener} which is passed to the 229 * {@link Util#copyStream(InputStream, OutputStream, int, long, CopyStreamListener, boolean)} method, so the timing is partially dependent on how long each 230 * block transfer takes. 231 * <p> 232 * <b>This keep-alive feature is optional; if it does not help or causes problems then don't use it.</b> 233 * 234 * @see #FTP_SYSTEM_TYPE 235 * @see #SYSTEM_TYPE_PROPERTIES 236 * @see FTP 237 * @see FTPConnectionClosedException 238 * @see FTPFileEntryParser 239 * @see FTPFileEntryParserFactory 240 * @see DefaultFTPFileEntryParserFactory 241 * @see FTPClientConfig 242 * @see org.apache.commons.net.MalformedServerReplyException 243 */ 244 public class FTPClient extends FTP implements Configurable { 245 246 // @since 3.0 247 private static class CSL implements CopyStreamListener { 248 249 private final FTPClient parent; 250 private final long idleMillis; 251 private final int currentSoTimeoutMillis; 252 253 private long lastIdleTimeMillis = System.currentTimeMillis(); 254 private int notAcked; 255 private int acksAcked; 256 private int ioErrors; 257 258 CSL(final FTPClient parent, final Duration idleDuration, final Duration maxWaitDuration) throws SocketException { 259 this.idleMillis = idleDuration.toMillis(); 260 this.parent = parent; 261 this.currentSoTimeoutMillis = parent.getSoTimeout(); 262 parent.setSoTimeout(DurationUtils.toMillisInt(maxWaitDuration)); 263 } 264 265 @Override 266 public void bytesTransferred(final CopyStreamEvent event) { 267 bytesTransferred(event.getTotalBytesTransferred(), event.getBytesTransferred(), event.getStreamSize()); 268 } 269 270 @Override 271 public void bytesTransferred(final long totalBytesTransferred, final int bytesTransferred, final long streamSize) { 272 final long nowMillis = System.currentTimeMillis(); 273 if (nowMillis - lastIdleTimeMillis > idleMillis) { 274 try { 275 parent.__noop(); 276 acksAcked++; 277 } catch (final SocketTimeoutException e) { 278 notAcked++; 279 } catch (final IOException e) { 280 ioErrors++; 281 // Ignored 282 } 283 lastIdleTimeMillis = nowMillis; 284 } 285 } 286 287 int[] cleanUp() throws IOException { 288 final int remain = notAcked; 289 try { 290 while (notAcked > 0) { 291 parent.getReply(); // we do want to see these 292 notAcked--; // only decrement if actually received 293 } 294 } catch (final SocketTimeoutException e) { // NET-584 295 // ignored 296 } finally { 297 parent.setSoTimeout(currentSoTimeoutMillis); 298 } 299 return new int[] { acksAcked, remain, notAcked, ioErrors }; // debug counts 300 } 301 302 } 303 304 /** 305 * Strategy interface for updating host names received from FTP server for passive NAT workaround. 306 * 307 * @since 3.6 308 */ 309 public interface HostnameResolver { 310 String resolve(String hostname) throws UnknownHostException; 311 } 312 313 /** 314 * Default strategy for passive NAT workaround (site-local replies are replaced.) 315 * 316 * @since 3.6 317 */ 318 public static class NatServerResolverImpl implements HostnameResolver { 319 private final FTPClient client; 320 321 public NatServerResolverImpl(final FTPClient client) { 322 this.client = client; 323 } 324 325 @Override 326 public String resolve(final String hostname) throws UnknownHostException { 327 String newHostname = hostname; 328 final InetAddress host = InetAddress.getByName(newHostname); 329 // reply is a local address, but target is not - assume NAT box changed the PASV reply 330 if (host.isSiteLocalAddress()) { 331 final InetAddress remote = this.client.getRemoteAddress(); 332 if (!remote.isSiteLocalAddress()) { 333 newHostname = remote.getHostAddress(); 334 } 335 } 336 return newHostname; 337 } 338 } 339 340 private static class PropertiesSingleton { 341 342 static final Properties PROPERTIES; 343 344 static { 345 final InputStream resourceAsStream = FTPClient.class.getResourceAsStream(SYSTEM_TYPE_PROPERTIES); 346 Properties p = null; 347 if (resourceAsStream != null) { 348 p = new Properties(); 349 try { 350 p.load(resourceAsStream); 351 } catch (final IOException e) { 352 // Ignored 353 } finally { 354 try { 355 resourceAsStream.close(); 356 } catch (final IOException e) { 357 // Ignored 358 } 359 } 360 } 361 PROPERTIES = p; 362 } 363 364 } 365 366 /** 367 * The system property ({@value}) which can be used to override the system type.<br> 368 * If defined, the value will be used to create any automatically created parsers. 369 * 370 * @since 3.0 371 */ 372 public static final String FTP_SYSTEM_TYPE = "org.apache.commons.net.ftp.systemType"; 373 374 /** 375 * The system property ({@value}) which can be used as the default system type.<br> 376 * If defined, the value will be used if the SYST command fails. 377 * 378 * @since 3.1 379 */ 380 public static final String FTP_SYSTEM_TYPE_DEFAULT = "org.apache.commons.net.ftp.systemType.default"; 381 382 /** 383 * The system property that defines the default for {@link #isIpAddressFromPasvResponse()}. This property, if present, configures the default for the 384 * following: If the client receives the servers response for a PASV request, then that response will contain an IP address. If this property is true, then 385 * the client will use that IP address, as requested by the server. This is compatible to version {@code 3.8.0}, and before. If this property is false, or 386 * absent, then the client will ignore that IP address, and instead use the remote address of the control connection. 387 * 388 * @see #isIpAddressFromPasvResponse() 389 * @see #setIpAddressFromPasvResponse(boolean) 390 * @since 3.9.0 391 */ 392 public static final String FTP_IP_ADDRESS_FROM_PASV_RESPONSE = "org.apache.commons.net.ftp.ipAddressFromPasvResponse"; 393 394 /** 395 * The name of an optional systemType properties file ({@value}), which is loaded using {@link Class#getResourceAsStream(String)}.<br> 396 * The entries are the systemType (as determined by {@link FTPClient#getSystemType}) and the values are the replacement type or parserClass, which is passed 397 * to {@link FTPFileEntryParserFactory#createFileEntryParser(String)}.<br> 398 * For example: 399 * 400 * <pre> 401 * Plan 9=Unix 402 * OS410=org.apache.commons.net.ftp.parser.OS400FTPEntryParser 403 * </pre> 404 * 405 * @since 3.0 406 */ 407 public static final String SYSTEM_TYPE_PROPERTIES = "/systemType.properties"; 408 409 /** 410 * A constant indicating the FTP session is expecting all transfers to occur between the client (local) and server and that the server should connect to the 411 * client's data port to initiate a data transfer. This is the default data connection mode when and FTPClient instance is created. 412 */ 413 public static final int ACTIVE_LOCAL_DATA_CONNECTION_MODE = 0; 414 415 /** 416 * A constant indicating the FTP session is expecting all transfers to occur between two remote servers and that the server the client is connected to 417 * should connect to the other server's data port to initiate a data transfer. 418 */ 419 public static final int ACTIVE_REMOTE_DATA_CONNECTION_MODE = 1; 420 421 /** 422 * A constant indicating the FTP session is expecting all transfers to occur between the client (local) and server and that the server is in passive mode, 423 * requiring the client to connect to the server's data port to initiate a transfer. 424 */ 425 public static final int PASSIVE_LOCAL_DATA_CONNECTION_MODE = 2; 426 427 /** 428 * A constant indicating the FTP session is expecting all transfers to occur between two remote servers and that the server the client is connected to is in 429 * passive mode, requiring the other server to connect to the first server's data port to initiate a data transfer. 430 */ 431 public static final int PASSIVE_REMOTE_DATA_CONNECTION_MODE = 3; 432 433 /** Pattern for PASV mode responses. Groups: (n,n,n,n),(n),(n) */ 434 private static final java.util.regex.Pattern PARMS_PAT; 435 436 static { 437 PARMS_PAT = java.util.regex.Pattern.compile("(\\d{1,3},\\d{1,3},\\d{1,3},\\d{1,3}),(\\d{1,3}),(\\d{1,3})"); 438 } 439 440 private static Properties getOverrideProperties() { 441 return PropertiesSingleton.PROPERTIES; 442 } 443 444 /** 445 * Parse the pathname from a CWD reply. 446 * <p> 447 * According to <a href="http://www.ietf.org/rfc/rfc959.txt">RFC959</a>, it should be the same as for MKD i.e. 448 * {@code 257<space>"<directory-name>"[<space>commentary]} where any double-quotes in {@code <directory-name>} are doubled. 449 * Unlike MKD, the commentary is optional. 450 * <p> 451 * However, see NET-442 for an exception. 452 * 453 * @param reply 454 * @return the pathname, without enclosing quotes, or the full string after the reply code and space if the syntax is invalid (i.e. enclosing quotes are 455 * missing or embedded quotes are not doubled) 456 */ 457 // package protected for access by test cases 458 static String parsePathname(final String reply) { 459 final String param = reply.substring(REPLY_CODE_LEN + 1); 460 if (param.startsWith("\"")) { 461 final StringBuilder sb = new StringBuilder(); 462 boolean quoteSeen = false; 463 // start after initial quote 464 for (int i = 1; i < param.length(); i++) { 465 final char ch = param.charAt(i); 466 if (ch == '"') { 467 if (quoteSeen) { 468 sb.append(ch); 469 quoteSeen = false; 470 } else { 471 // don't output yet, in case doubled 472 quoteSeen = true; 473 } 474 } else { 475 if (quoteSeen) { // found lone trailing quote within string 476 return sb.toString(); 477 } 478 sb.append(ch); // just another character 479 } 480 } 481 if (quoteSeen) { // found lone trailing quote at end of string 482 return sb.toString(); 483 } 484 } 485 // malformed reply, return all after reply code and space 486 return param; 487 } 488 489 private int dataConnectionMode; 490 private Duration dataTimeout; 491 492 private int passivePort; 493 private String passiveHost; 494 private final Random random; 495 private int activeMinPort; 496 private int activeMaxPort; 497 private InetAddress activeExternalHost; 498 499 /** overrides __activeExternalHost in EPRT/PORT commands. */ 500 private InetAddress reportActiveExternalHost; 501 502 /** The address to bind to on passive connections, if necessary. */ 503 private InetAddress passiveLocalHost; 504 private int fileType; 505 @SuppressWarnings("unused") // fields are written, but currently not read 506 private int fileFormat; 507 @SuppressWarnings("unused") // field is written, but currently not read 508 private int fileStructure; 509 @SuppressWarnings("unused") // field is written, but currently not read 510 private int fileTransferMode; 511 512 private boolean remoteVerificationEnabled; 513 514 private long restartOffset; 515 516 private FTPFileEntryParserFactory parserFactory; 517 518 private int bufferSize; // buffersize for buffered data streams 519 520 private int sendDataSocketBufferSize; 521 522 private int receiveDataSocketBufferSize; 523 524 private boolean listHiddenFiles; 525 526 private boolean useEPSVwithIPv4; // whether to attempt EPSV with an IPv4 connection 527 528 // __systemName is a cached value that should not be referenced directly 529 // except when assigned in getSystemName and __initDefaults. 530 private String systemName; 531 532 // __entryParser is a cached value that should not be referenced directly 533 // except when assigned in listFiles(String, String) and __initDefaults. 534 private FTPFileEntryParser entryParser; 535 536 // Key used to create the parser; necessary to ensure that the parser type is not ignored 537 private String entryParserKey; 538 539 private FTPClientConfig configuration; 540 541 // Listener used by store/retrieve methods to handle keepalive 542 private CopyStreamListener copyStreamListener; 543 544 // How long to wait before sending another control keep-alive message 545 private Duration controlKeepAliveTimeout = Duration.ZERO; 546 547 // How long to wait for keepalive message replies before continuing 548 // Most FTP servers don't seem to support concurrent control and data connection usage 549 private Duration controlKeepAliveReplyTimeout = Duration.ofSeconds(1); 550 551 // Debug counts for NOOP acks 552 private int[] cslDebug; 553 554 /** 555 * Enable or disable replacement of internal IP in passive mode. Default enabled using {code NatServerResolverImpl}. 556 */ 557 private HostnameResolver passiveNatWorkaroundStrategy = new NatServerResolverImpl(this); 558 559 /** Controls the automatic server encoding detection (only UTF-8 supported). */ 560 private boolean autodetectEncoding; 561 562 /** Map of FEAT responses. If null, has not been initialized. */ 563 private HashMap<String, Set<String>> featuresMap; 564 565 private boolean ipAddressFromPasvResponse = Boolean.getBoolean(FTPClient.FTP_IP_ADDRESS_FROM_PASV_RESPONSE); 566 567 /** 568 * Default FTPClient constructor. Creates a new FTPClient instance with the data connection mode set to <code> ACTIVE_LOCAL_DATA_CONNECTION_MODE </code>, 569 * the file type set to <code> FTP.ASCII_FILE_TYPE </code>, the file format set to <code> FTP.NON_PRINT_TEXT_FORMAT </code>, the file structure set to 570 * <code> FTP.FILE_STRUCTURE </code>, and the transfer mode set to <code> FTP.STREAM_TRANSFER_MODE </code>. 571 * <p> 572 * The list parsing auto-detect feature can be configured to use lenient future dates (short dates may be up to one day in the future) as follows: 573 * 574 * <pre> 575 * FTPClient ftp = new FTPClient(); 576 * FTPClientConfig config = new FTPClientConfig(); 577 * config.setLenientFutureDates(true); 578 * ftp.configure(config); 579 * </pre> 580 */ 581 public FTPClient() { 582 initDefaults(); 583 dataTimeout = Duration.ofMillis(-1); 584 remoteVerificationEnabled = true; 585 parserFactory = new DefaultFTPFileEntryParserFactory(); 586 configuration = null; 587 listHiddenFiles = false; 588 useEPSVwithIPv4 = false; 589 random = new Random(); 590 passiveLocalHost = null; 591 } 592 593 @Override 594 protected void _connectAction_() throws IOException { 595 _connectAction_(null); 596 } 597 598 /** 599 * @param socketIsReader the reader to reuse (if non-null) 600 * @throws IOException on error 601 * @since 3.4 602 */ 603 @Override 604 protected void _connectAction_(final Reader socketIsReader) throws IOException { 605 super._connectAction_(socketIsReader); // sets up _input_ and _output_ 606 initDefaults(); 607 // must be after super._connectAction_(), because otherwise we get an 608 // Exception claiming we're not connected 609 if (autodetectEncoding) { 610 final ArrayList<String> oldReplyLines = new ArrayList<>(_replyLines); 611 final int oldReplyCode = _replyCode; 612 if (hasFeature("UTF8") || hasFeature("UTF-8")) // UTF8 appears to be the default 613 { 614 setControlEncoding("UTF-8"); 615 _controlInput_ = new CRLFLineReader(new InputStreamReader(_input_, getControlEncoding())); 616 _controlOutput_ = new BufferedWriter(new OutputStreamWriter(_output_, getControlEncoding())); 617 } 618 // restore the original reply (server greeting) 619 _replyLines.clear(); 620 _replyLines.addAll(oldReplyLines); 621 _replyCode = oldReplyCode; 622 _newReplyString = true; 623 } 624 } 625 626 /** 627 * Establishes a data connection with the FTP server, returning a Socket for the connection if successful. If a restart offset has been set with 628 * {@link #setRestartOffset(long)}, a REST command is issued to the server with the offset as an argument before establishing the data connection. Active 629 * mode connections also cause a local PORT command to be issued. 630 * 631 * @param command The int representation of the FTP command to send. 632 * @param arg The arguments to the FTP command. If this parameter is set to null, then the command is sent with no argument. 633 * @return A Socket corresponding to the established data connection. Null is returned if an FTP protocol error is reported at any point during the 634 * establishment and initialization of the connection. 635 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 636 * @since 3.3 637 */ 638 protected Socket _openDataConnection_(final FTPCmd command, final String arg) throws IOException { 639 return _openDataConnection_(command.getCommand(), arg); 640 } 641 642 /** 643 * Establishes a data connection with the FTP server, returning a Socket for the connection if successful. If a restart offset has been set with 644 * {@link #setRestartOffset(long)}, a REST command is issued to the server with the offset as an argument before establishing the data connection. Active 645 * mode connections also cause a local PORT command to be issued. 646 * 647 * @deprecated (3.3) Use {@link #_openDataConnection_(FTPCmd, String)} instead 648 * @param command The int representation of the FTP command to send. 649 * @param arg The arguments to the FTP command. If this parameter is set to null, then the command is sent with no argument. 650 * @return A Socket corresponding to the established data connection. Null is returned if an FTP protocol error is reported at any point during the 651 * establishment and initialization of the connection. 652 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 653 */ 654 @Deprecated 655 protected Socket _openDataConnection_(final int command, final String arg) throws IOException { 656 return _openDataConnection_(FTPCommand.getCommand(command), arg); 657 } 658 659 /** 660 * Establishes a data connection with the FTP server, returning a Socket for the connection if successful. If a restart offset has been set with 661 * {@link #setRestartOffset(long)}, a REST command is issued to the server with the offset as an argument before establishing the data connection. Active 662 * mode connections also cause a local PORT command to be issued. 663 * 664 * @param command The text representation of the FTP command to send. 665 * @param arg The arguments to the FTP command. If this parameter is set to null, then the command is sent with no argument. 666 * @return A Socket corresponding to the established data connection. Null is returned if an FTP protocol error is reported at any point during the 667 * establishment and initialization of the connection. 668 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 669 * @since 3.1 670 */ 671 protected Socket _openDataConnection_(final String command, final String arg) throws IOException { 672 if (dataConnectionMode != ACTIVE_LOCAL_DATA_CONNECTION_MODE && dataConnectionMode != PASSIVE_LOCAL_DATA_CONNECTION_MODE) { 673 return null; 674 } 675 676 final boolean isInet6Address = getRemoteAddress() instanceof Inet6Address; 677 678 final Socket socket; 679 680 final int soTimeoutMillis = DurationUtils.toMillisInt(dataTimeout); 681 if (dataConnectionMode == ACTIVE_LOCAL_DATA_CONNECTION_MODE) { 682 // if no activePortRange was set (correctly) -> getActivePort() = 0 683 // -> new ServerSocket(0) -> bind to any free local port 684 try (final ServerSocket server = _serverSocketFactory_.createServerSocket(getActivePort(), 1, getHostAddress())) { 685 // Try EPRT only if remote server is over IPv6, if not use PORT, 686 // because EPRT has no advantage over PORT on IPv4. 687 // It could even have the disadvantage, 688 // that EPRT will make the data connection fail, because 689 // today's intelligent NAT Firewalls are able to 690 // substitute IP addresses in the PORT command, 691 // but might not be able to recognize the EPRT command. 692 if (isInet6Address) { 693 if (!FTPReply.isPositiveCompletion(eprt(getReportHostAddress(), server.getLocalPort()))) { 694 return null; 695 } 696 } else if (!FTPReply.isPositiveCompletion(port(getReportHostAddress(), server.getLocalPort()))) { 697 return null; 698 } 699 700 if (restartOffset > 0 && !restart(restartOffset)) { 701 return null; 702 } 703 704 if (!FTPReply.isPositivePreliminary(sendCommand(command, arg))) { 705 return null; 706 } 707 708 // For now, let's just use the data timeout value for waiting for 709 // the data connection. It may be desirable to let this be a 710 // separately configurable value. In any case, we really want 711 // to allow preventing the accept from blocking indefinitely. 712 if (soTimeoutMillis >= 0) { 713 server.setSoTimeout(soTimeoutMillis); 714 } 715 socket = server.accept(); 716 717 // Ensure the timeout is set before any commands are issued on the new socket 718 if (soTimeoutMillis >= 0) { 719 socket.setSoTimeout(soTimeoutMillis); 720 } 721 if (receiveDataSocketBufferSize > 0) { 722 socket.setReceiveBufferSize(receiveDataSocketBufferSize); 723 } 724 if (sendDataSocketBufferSize > 0) { 725 socket.setSendBufferSize(sendDataSocketBufferSize); 726 } 727 } 728 } else { // We must be in PASSIVE_LOCAL_DATA_CONNECTION_MODE 729 730 // Try EPSV command first on IPv6 - and IPv4 if enabled. 731 // When using IPv4 with NAT it has the advantage 732 // to work with more rare configurations. 733 // E.g. if FTP server has a static PASV address (external network) 734 // and the client is coming from another internal network. 735 // In that case the data connection after PASV command would fail, 736 // while EPSV would make the client succeed by taking just the port. 737 final boolean attemptEPSV = isUseEPSVwithIPv4() || isInet6Address; 738 if (attemptEPSV && epsv() == FTPReply.ENTERING_EPSV_MODE) { 739 _parseExtendedPassiveModeReply(_replyLines.get(0)); 740 } else { 741 if (isInet6Address) { 742 return null; // Must use EPSV for IPV6 743 } 744 // If EPSV failed on IPV4, revert to PASV 745 if (pasv() != FTPReply.ENTERING_PASSIVE_MODE) { 746 return null; 747 } 748 _parsePassiveModeReply(_replyLines.get(0)); 749 } 750 751 socket = _socketFactory_.createSocket(); 752 if (receiveDataSocketBufferSize > 0) { 753 socket.setReceiveBufferSize(receiveDataSocketBufferSize); 754 } 755 if (sendDataSocketBufferSize > 0) { 756 socket.setSendBufferSize(sendDataSocketBufferSize); 757 } 758 if (passiveLocalHost != null) { 759 socket.bind(new InetSocketAddress(passiveLocalHost, 0)); 760 } 761 762 // For now, let's just use the data timeout value for waiting for 763 // the data connection. It may be desirable to let this be a 764 // separately configurable value. In any case, we really want 765 // to allow preventing the accept from blocking indefinitely. 766 if (soTimeoutMillis >= 0) { 767 socket.setSoTimeout(soTimeoutMillis); 768 } 769 770 socket.connect(new InetSocketAddress(passiveHost, passivePort), connectTimeout); 771 if (restartOffset > 0 && !restart(restartOffset)) { 772 socket.close(); 773 return null; 774 } 775 776 if (!FTPReply.isPositivePreliminary(sendCommand(command, arg))) { 777 socket.close(); 778 return null; 779 } 780 } 781 782 if (remoteVerificationEnabled && !verifyRemote(socket)) { 783 // Grab the host before we close the socket to avoid NET-663 784 final InetAddress socketHost = socket.getInetAddress(); 785 786 socket.close(); 787 788 throw new IOException( 789 "Host attempting data connection " + socketHost.getHostAddress() + " is not same as server " + getRemoteAddress().getHostAddress()); 790 } 791 792 return socket; 793 } 794 795 protected void _parseExtendedPassiveModeReply(String reply) throws MalformedServerReplyException { 796 reply = reply.substring(reply.indexOf('(') + 1, reply.indexOf(')')).trim(); 797 798 final char delim1 = reply.charAt(0); 799 final char delim2 = reply.charAt(1); 800 final char delim3 = reply.charAt(2); 801 final char delim4 = reply.charAt(reply.length() - 1); 802 803 if (delim1 != delim2 || delim2 != delim3 || delim3 != delim4) { 804 throw new MalformedServerReplyException("Could not parse extended passive host information.\nServer Reply: " + reply); 805 } 806 807 final int port; 808 try { 809 port = Integer.parseInt(reply.substring(3, reply.length() - 1)); 810 } catch (final NumberFormatException e) { 811 throw new MalformedServerReplyException("Could not parse extended passive host information.\nServer Reply: " + reply); 812 } 813 814 // in EPSV mode, the passive host address is implicit 815 this.passiveHost = getRemoteAddress().getHostAddress(); 816 this.passivePort = port; 817 } 818 819 /** 820 * @since 3.1 821 * @param reply the reply to parse 822 * @throws MalformedServerReplyException if the server reply does not match (n,n,n,n),(n),(n) 823 */ 824 protected void _parsePassiveModeReply(final String reply) throws MalformedServerReplyException { 825 final Matcher m = PARMS_PAT.matcher(reply); 826 if (!m.find()) { 827 throw new MalformedServerReplyException("Could not parse passive host information.\nServer Reply: " + reply); 828 } 829 830 int pasvPort; 831 // Fix up to look like IP address 832 String pasvHost = "0,0,0,0".equals(m.group(1)) ? _socket_.getInetAddress().getHostAddress() : m.group(1).replace(',', '.'); 833 834 try { 835 final int oct1 = Integer.parseInt(m.group(2)); 836 final int oct2 = Integer.parseInt(m.group(3)); 837 pasvPort = oct1 << 8 | oct2; 838 } catch (final NumberFormatException e) { 839 throw new MalformedServerReplyException("Could not parse passive port information.\nServer Reply: " + reply); 840 } 841 842 if (isIpAddressFromPasvResponse()) { 843 // Pre-3.9.0 behavior 844 if (passiveNatWorkaroundStrategy != null) { 845 try { 846 final String newPassiveHost = passiveNatWorkaroundStrategy.resolve(pasvHost); 847 if (!pasvHost.equals(newPassiveHost)) { 848 fireReplyReceived(0, "[Replacing PASV mode reply address " + this.passiveHost + " with " + newPassiveHost + "]\n"); 849 pasvHost = newPassiveHost; 850 } 851 } catch (final UnknownHostException e) { // Should not happen as we are passing in an IP address 852 throw new MalformedServerReplyException("Could not parse passive host information.\nServer Reply: " + reply); 853 } 854 } 855 } else if (_socket_ == null) { 856 pasvHost = null; // For unit testing. 857 } else { 858 pasvHost = _socket_.getInetAddress().getHostAddress(); 859 } 860 this.passiveHost = pasvHost; 861 this.passivePort = pasvPort; 862 } 863 864 /** 865 * @param command the command to get 866 * @param remote the remote file name 867 * @param local The local OutputStream to which to write the file. 868 * @return true if successful 869 * @throws IOException on error 870 * @since 3.1 871 */ 872 protected boolean _retrieveFile(final String command, final String remote, final OutputStream local) throws IOException { 873 final Socket socket = _openDataConnection_(command, remote); 874 875 if (socket == null) { 876 return false; 877 } 878 879 InputStream input = null; 880 CSL csl = null; 881 try { 882 try { 883 if (fileType == ASCII_FILE_TYPE) { 884 input = new FromNetASCIIInputStream(getBufferedInputStream(socket.getInputStream())); 885 } else { 886 input = getBufferedInputStream(socket.getInputStream()); 887 } 888 889 if (DurationUtils.isPositive(controlKeepAliveTimeout)) { 890 csl = new CSL(this, controlKeepAliveTimeout, controlKeepAliveReplyTimeout); 891 } 892 893 // Treat everything else as binary for now 894 Util.copyStream(input, local, getBufferSize(), CopyStreamEvent.UNKNOWN_STREAM_SIZE, mergeListeners(csl), false); 895 } finally { 896 Util.closeQuietly(input); 897 } 898 // Get the transfer response 899 return completePendingCommand(); 900 } finally { 901 Util.closeQuietly(socket); 902 if (csl != null) { 903 cslDebug = csl.cleanUp(); // fetch any outstanding keepalive replies 904 } 905 } 906 } 907 908 /** 909 * @param command the command to send 910 * @param remote the remote file name 911 * @return the stream from which to read the file 912 * @throws IOException on error 913 * @since 3.1 914 */ 915 protected InputStream _retrieveFileStream(final String command, final String remote) throws IOException { 916 final Socket socket = _openDataConnection_(command, remote); 917 918 if (socket == null) { 919 return null; 920 } 921 922 final InputStream input; 923 if (fileType == ASCII_FILE_TYPE) { 924 // We buffer ascii transfers because the buffering has to 925 // be interposed between FromNetASCIIOutputSream and the underlying 926 // socket input stream. We don't buffer binary transfers 927 // because we don't want to impose a buffering policy on the 928 // programmer if possible. Programmers can decide on their 929 // own if they want to wrap the SocketInputStream we return 930 // for file types other than ASCII. 931 input = new FromNetASCIIInputStream(getBufferedInputStream(socket.getInputStream())); 932 } else { 933 input = socket.getInputStream(); 934 } 935 return new org.apache.commons.net.io.SocketInputStream(socket, input); 936 } 937 938 /** 939 * @since 3.1 940 * @param command the command to send 941 * @param remote the remote file name 942 * @param local The local InputStream from which to read the data to be written/appended to the remote file. 943 * @return true if successful 944 * @throws IOException on error 945 */ 946 protected boolean _storeFile(final String command, final String remote, final InputStream local) throws IOException { 947 final Socket socket = _openDataConnection_(command, remote); 948 949 if (socket == null) { 950 return false; 951 } 952 953 final OutputStream output; 954 955 if (fileType == ASCII_FILE_TYPE) { 956 output = new ToNetASCIIOutputStream(getBufferedOutputStream(socket.getOutputStream())); 957 } else { 958 output = getBufferedOutputStream(socket.getOutputStream()); 959 } 960 961 CSL csl = null; 962 if (DurationUtils.isPositive(controlKeepAliveTimeout)) { 963 csl = new CSL(this, controlKeepAliveTimeout, controlKeepAliveReplyTimeout); 964 } 965 966 // Treat everything else as binary for now 967 try { 968 Util.copyStream(local, output, getBufferSize(), CopyStreamEvent.UNKNOWN_STREAM_SIZE, mergeListeners(csl), false); 969 output.close(); // ensure the file is fully written 970 socket.close(); // done writing the file 971 972 // Get the transfer response 973 return completePendingCommand(); 974 } catch (final IOException e) { 975 Util.closeQuietly(output); // ignore close errors here 976 Util.closeQuietly(socket); // ignore close errors here 977 throw e; 978 } finally { 979 if (csl != null) { 980 cslDebug = csl.cleanUp(); // fetch any outstanding keepalive replies 981 } 982 } 983 } 984 985 /** 986 * @param command the command to send 987 * @param remote the remote file name 988 * @return the output stream to write to 989 * @throws IOException on error 990 * @since 3.1 991 */ 992 protected OutputStream _storeFileStream(final String command, final String remote) throws IOException { 993 final Socket socket = _openDataConnection_(command, remote); 994 995 if (socket == null) { 996 return null; 997 } 998 999 final OutputStream output; 1000 if (fileType == ASCII_FILE_TYPE) { 1001 // We buffer ascii transfers because the buffering has to 1002 // be interposed between ToNetASCIIOutputSream and the underlying 1003 // socket output stream. We don't buffer binary transfers 1004 // because we don't want to impose a buffering policy on the 1005 // programmer if possible. Programmers can decide on their 1006 // own if they want to wrap the SocketOutputStream we return 1007 // for file types other than ASCII. 1008 output = new ToNetASCIIOutputStream(getBufferedOutputStream(socket.getOutputStream())); 1009 } else { 1010 output = socket.getOutputStream(); 1011 } 1012 return new SocketOutputStream(socket, output); 1013 } 1014 1015 /** 1016 * Abort a transfer in progress. 1017 * 1018 * @return True if successfully completed, false if not. 1019 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1020 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1021 * independently as itself. 1022 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1023 */ 1024 public boolean abort() throws IOException { 1025 return FTPReply.isPositiveCompletion(abor()); 1026 } 1027 1028 /** 1029 * Reserve a number of bytes on the server for the next file transfer. 1030 * 1031 * @param bytes The number of bytes which the server should allocate. 1032 * @return True if successfully completed, false if not. 1033 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1034 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1035 * independently as itself. 1036 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1037 */ 1038 public boolean allocate(final int bytes) throws IOException { 1039 return FTPReply.isPositiveCompletion(allo(bytes)); 1040 } 1041 1042 /** 1043 * Reserve space on the server for the next file transfer. 1044 * 1045 * @param bytes The number of bytes which the server should allocate. 1046 * @param recordSize The size of a file record. 1047 * @return True if successfully completed, false if not. 1048 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1049 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1050 * independently as itself. 1051 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1052 */ 1053 public boolean allocate(final int bytes, final int recordSize) throws IOException { 1054 return FTPReply.isPositiveCompletion(allo(bytes, recordSize)); 1055 } 1056 1057 /** 1058 * Reserve a number of bytes on the server for the next file transfer. 1059 * 1060 * @param bytes The number of bytes which the server should allocate. 1061 * @return True if successfully completed, false if not. 1062 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1063 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1064 * independently as itself. 1065 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1066 */ 1067 public boolean allocate(final long bytes) throws IOException { 1068 return FTPReply.isPositiveCompletion(allo(bytes)); 1069 } 1070 1071 /** 1072 * Reserve space on the server for the next file transfer. 1073 * 1074 * @param bytes The number of bytes which the server should allocate. 1075 * @param recordSize The size of a file record. 1076 * @return True if successfully completed, false if not. 1077 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1078 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1079 * independently as itself. 1080 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1081 */ 1082 public boolean allocate(final long bytes, final int recordSize) throws IOException { 1083 return FTPReply.isPositiveCompletion(allo(bytes, recordSize)); 1084 } 1085 1086 /** 1087 * Appends to a file on the server with the given name, taking input from the given InputStream. This method does NOT close the given InputStream. If the 1088 * current file type is ASCII, line separators in the file are transparently converted to the NETASCII format (i.e., you should not attempt to create a 1089 * special InputStream to do this). 1090 * 1091 * @param remote The name of the remote file. 1092 * @param local The local InputStream from which to read the data to be appended to the remote file. 1093 * @return True if successfully completed, false if not. 1094 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some 1095 * other reason causing the server to send FTP reply code 421. This exception may be caught either as 1096 * an IOException or independently as itself. 1097 * @throws org.apache.commons.net.io.CopyStreamException If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to 1098 * determine the number of bytes transferred and the IOException causing the error. This exception may 1099 * be caught either as an IOException or independently as itself. 1100 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the 1101 * server. 1102 */ 1103 public boolean appendFile(final String remote, final InputStream local) throws IOException { 1104 return storeFile(FTPCmd.APPE, remote, local); 1105 } 1106 1107 /** 1108 * Returns an OutputStream through which data can be written to append to a file on the server with the given name. If the current file type is ASCII, the 1109 * returned OutputStream will convert line separators in the file to the NETASCII format (i.e., you should not attempt to create a special OutputStream to 1110 * do this). You must close the OutputStream when you finish writing to it. The OutputStream itself will take care of closing the parent data connection 1111 * socket upon being closed. 1112 * <p> 1113 * <b>To finalize the file transfer you must call {@link #completePendingCommand completePendingCommand } and check its return value to verify success.</b> 1114 * If this is not done, subsequent commands may behave unexpectedly. 1115 * 1116 * @param remote The name of the remote file. 1117 * @return An OutputStream through which the remote file can be appended. If the data connection cannot be opened (e.g., the file does not exist), null is 1118 * returned (in which case you may check the reply code to determine the exact reason for failure). 1119 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1120 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1121 * independently as itself. 1122 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1123 */ 1124 public OutputStream appendFileStream(final String remote) throws IOException { 1125 return storeFileStream(FTPCmd.APPE, remote); 1126 } 1127 1128 /** 1129 * Change to the parent directory of the current working directory. 1130 * 1131 * @return True if successfully completed, false if not. 1132 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1133 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1134 * independently as itself. 1135 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1136 */ 1137 public boolean changeToParentDirectory() throws IOException { 1138 return FTPReply.isPositiveCompletion(cdup()); 1139 } 1140 1141 /** 1142 * Change the current working directory of the FTP session. 1143 * 1144 * @param pathname The new current working directory. 1145 * @return True if successfully completed, false if not. 1146 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1147 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1148 * independently as itself. 1149 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1150 */ 1151 public boolean changeWorkingDirectory(final String pathname) throws IOException { 1152 return FTPReply.isPositiveCompletion(cwd(pathname)); 1153 } 1154 1155 /** 1156 * There are a few FTPClient methods that do not complete the entire sequence of FTP commands to complete a transaction. These commands require some action 1157 * by the programmer after the reception of a positive intermediate command. After the programmer's code completes its actions, it must call this method to 1158 * receive the completion reply from the server and verify the success of the entire transaction. 1159 * <p> 1160 * For example, 1161 * 1162 * <pre> 1163 * InputStream input; 1164 * OutputStream output; 1165 * input = new FileInputStream("foobaz.txt"); 1166 * output = ftp.storeFileStream("foobar.txt") 1167 * if (!FTPReply.isPositiveIntermediate(ftp.getReplyCode())) { 1168 * input.close(); 1169 * output.close(); 1170 * ftp.logout(); 1171 * ftp.disconnect(); 1172 * System.err.println("File transfer failed."); 1173 * System.exit(1); 1174 * } 1175 * Util.copyStream(input, output); 1176 * input.close(); 1177 * output.close(); 1178 * // Must call completePendingCommand() to finish command. 1179 * if (!ftp.completePendingCommand()) { 1180 * ftp.logout(); 1181 * ftp.disconnect(); 1182 * System.err.println("File transfer failed."); 1183 * System.exit(1); 1184 * } 1185 * </pre> 1186 * 1187 * @return True if successfully completed, false if not. 1188 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1189 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1190 * independently as itself. 1191 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1192 */ 1193 public boolean completePendingCommand() throws IOException { 1194 return FTPReply.isPositiveCompletion(getReply()); 1195 } 1196 1197 /** 1198 * Implementation of the {@link Configurable Configurable} interface. In the case of this class, configuring merely makes the config object available for 1199 * the factory methods that construct parsers. 1200 * 1201 * @param config {@link FTPClientConfig FTPClientConfig} object used to provide non-standard configurations to the parser. 1202 * @since 1.4 1203 */ 1204 @Override 1205 public void configure(final FTPClientConfig config) { 1206 this.configuration = config; 1207 } 1208 1209 // package access for test purposes 1210 void createParser(final String parserKey) throws IOException { 1211 // We cache the value to avoid creation of a new object every 1212 // time a file listing is generated. 1213 // Note: we don't check against a null parserKey (NET-544) 1214 if (entryParser == null || parserKey != null && !entryParserKey.equals(parserKey)) { 1215 if (null != parserKey) { 1216 // if a parser key was supplied in the parameters, 1217 // use that to create the parser 1218 entryParser = parserFactory.createFileEntryParser(parserKey); 1219 entryParserKey = parserKey; 1220 1221 } else // if no parserKey was supplied, check for a configuration 1222 // in the params, and if it has a non-empty system type, use that. 1223 if (null != configuration && configuration.getServerSystemKey().length() > 0) { 1224 entryParser = parserFactory.createFileEntryParser(configuration); 1225 entryParserKey = configuration.getServerSystemKey(); 1226 } else { 1227 // if a parserKey hasn't been supplied, and a configuration 1228 // hasn't been supplied, and the override property is not set 1229 // then autodetect by calling 1230 // the SYST command and use that to choose the parser. 1231 String systemType = System.getProperty(FTP_SYSTEM_TYPE); 1232 if (systemType == null) { 1233 systemType = getSystemType(); // cannot be null 1234 final Properties override = getOverrideProperties(); 1235 if (override != null) { 1236 final String newType = override.getProperty(systemType); 1237 if (newType != null) { 1238 systemType = newType; 1239 } 1240 } 1241 } 1242 if (null != configuration) { // system type must have been empty above 1243 entryParser = parserFactory.createFileEntryParser(new FTPClientConfig(systemType, configuration)); 1244 } else { 1245 entryParser = parserFactory.createFileEntryParser(systemType); 1246 } 1247 entryParserKey = systemType; 1248 } 1249 } 1250 } 1251 1252 /** 1253 * Deletes a file on the FTP server. 1254 * 1255 * @param pathname The pathname of the file to be deleted. 1256 * @return True if successfully completed, false if not. 1257 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1258 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1259 * independently as itself. 1260 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1261 */ 1262 public boolean deleteFile(final String pathname) throws IOException { 1263 return FTPReply.isPositiveCompletion(dele(pathname)); 1264 } 1265 1266 /** 1267 * Closes the connection to the FTP server and restores connection parameters to the default values. 1268 * 1269 * @throws IOException If an error occurs while disconnecting. 1270 */ 1271 @Override 1272 public void disconnect() throws IOException { 1273 super.disconnect(); 1274 initDefaults(); 1275 } 1276 1277 /** 1278 * Issue a command and wait for the reply. 1279 * <p> 1280 * Should only be used with commands that return replies on the command channel - do not use for LIST, NLST, MLSD etc. 1281 * 1282 * @param command The command to invoke 1283 * @param params The parameters string, may be {@code null} 1284 * @return True if successfully completed, false if not, in which case call {@link #getReplyCode()} or {@link #getReplyString()} to get the reason. 1285 * 1286 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1287 * @since 3.0 1288 */ 1289 public boolean doCommand(final String command, final String params) throws IOException { 1290 return FTPReply.isPositiveCompletion(sendCommand(command, params)); 1291 } 1292 1293 /** 1294 * Issue a command and wait for the reply, returning it as an array of strings. 1295 * <p> 1296 * Should only be used with commands that return replies on the command channel - do not use for LIST, NLST, MLSD etc. 1297 * 1298 * @param command The command to invoke 1299 * @param params The parameters string, may be {@code null} 1300 * @return The array of replies, or {@code null} if the command failed, in which case call {@link #getReplyCode()} or {@link #getReplyString()} to get the 1301 * reason. 1302 * 1303 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1304 * @since 3.0 1305 */ 1306 public String[] doCommandAsStrings(final String command, final String params) throws IOException { 1307 final boolean success = FTPReply.isPositiveCompletion(sendCommand(command, params)); 1308 if (success) { 1309 return getReplyStrings(); 1310 } 1311 return null; 1312 } 1313 1314 /** 1315 * Set the current data connection mode to <code>ACTIVE_LOCAL_DATA_CONNECTION_MODE</code>. No communication with the FTP server is conducted, but this 1316 * causes all future data transfers to require the FTP server to connect to the client's data port. Additionally, to accommodate differences between socket 1317 * implementations on different platforms, this method causes the client to issue a PORT command before every data transfer. 1318 */ 1319 public void enterLocalActiveMode() { 1320 dataConnectionMode = ACTIVE_LOCAL_DATA_CONNECTION_MODE; 1321 passiveHost = null; 1322 passivePort = -1; 1323 } 1324 1325 /** 1326 * Set the current data connection mode to <code> PASSIVE_LOCAL_DATA_CONNECTION_MODE </code>. Use this method only for data transfers between the client and 1327 * server. This method causes a PASV (or EPSV) command to be issued to the server before the opening of every data connection, telling the server to open a 1328 * data port to which the client will connect to conduct data transfers. The FTPClient will stay in <code> PASSIVE_LOCAL_DATA_CONNECTION_MODE </code> until 1329 * the mode is changed by calling some other method such as {@link #enterLocalActiveMode enterLocalActiveMode() } 1330 * <p> 1331 * <b>N.B.</b> currently calling any connect method will reset the mode to ACTIVE_LOCAL_DATA_CONNECTION_MODE. 1332 */ 1333 public void enterLocalPassiveMode() { 1334 dataConnectionMode = PASSIVE_LOCAL_DATA_CONNECTION_MODE; 1335 // These will be set when just before a data connection is opened 1336 // in _openDataConnection_() 1337 passiveHost = null; 1338 passivePort = -1; 1339 } 1340 1341 /** 1342 * Set the current data connection mode to <code> ACTIVE_REMOTE_DATA_CONNECTION </code>. Use this method only for server to server data transfers. This 1343 * method issues a PORT command to the server, indicating the other server and port to which it should connect for data transfers. You must call this method 1344 * before EVERY server to server transfer attempt. The FTPClient will NOT automatically continue to issue PORT commands. You also must remember to call 1345 * {@link #enterLocalActiveMode enterLocalActiveMode() } if you wish to return to the normal data connection mode. 1346 * 1347 * @param host The passive mode server accepting connections for data transfers. 1348 * @param port The passive mode server's data port. 1349 * @return True if successfully completed, false if not. 1350 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1351 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1352 * independently as itself. 1353 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1354 */ 1355 public boolean enterRemoteActiveMode(final InetAddress host, final int port) throws IOException { 1356 if (FTPReply.isPositiveCompletion(port(host, port))) { 1357 dataConnectionMode = ACTIVE_REMOTE_DATA_CONNECTION_MODE; 1358 passiveHost = null; 1359 passivePort = -1; 1360 return true; 1361 } 1362 return false; 1363 } 1364 1365 /** 1366 * Set the current data connection mode to <code> PASSIVE_REMOTE_DATA_CONNECTION_MODE </code>. Use this method only for server to server data transfers. 1367 * This method issues a PASV command to the server, telling it to open a data port to which the active server will connect to conduct data transfers. You 1368 * must call this method before EVERY server to server transfer attempt. The FTPClient will NOT automatically continue to issue PASV commands. You also must 1369 * remember to call {@link #enterLocalActiveMode enterLocalActiveMode() } if you wish to return to the normal data connection mode. 1370 * 1371 * @return True if successfully completed, false if not. 1372 * @throws FTPConnectionClosedException If the FTP server prematurely closes the connection as a result of the client being idle or some other reason 1373 * causing the server to send FTP reply code 421. This exception may be caught either as an IOException or 1374 * independently as itself. 1375 * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server. 1376 */ 1377 public boolean enterRemotePassiveMode() throws IOException { 1378 if (pasv() != FTPReply.ENTERING_PASSIVE_MODE) { 1379 return false; 1380 } 1381 1382 dataConnectionMode = PASSIVE_REMOTE_DATA_CONNECTION_MODE; 1383 _parsePassiveModeReply(_replyLines.get(0)); 1384 1385 return true; 1386 } 1387 1388 /** 1389 * Queries the server for supported features. The server may reply with a list of server-supported extensions. For example, a typical client-server 1390 * interaction might be (from RFC 2389): 1391 * 1392 * <pre> 1393 C> feat 1394 S> 211-Extensions supported: 1395 S> MLST size*;create;modify*;perm;media-type 1396 S> SIZE 1397 S> COMPRESSION 1398 S> MDTM 1399 S> 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 ≥ 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 ≥ 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 ≥ 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 }