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