151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/* 251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. 351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is free software; you can redistribute it and/or modify it 651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * under the terms of the GNU General Public License version 2 only, as 751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * published by the Free Software Foundation. Oracle designates this 851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * particular file as subject to the "Classpath" exception as provided 951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by Oracle in the LICENSE file that accompanied this code. 1051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is distributed in the hope that it will be useful, but WITHOUT 1251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * version 2 for more details (a copy is included in the LICENSE file that 1551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * accompanied this code). 1651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * You should have received a copy of the GNU General Public License version 1851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2 along with this work; if not, write to the Free Software Foundation, 1951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or visit www.oracle.com if you need additional information or have any 2351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * questions. 2451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 2551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipackage sun.net.ftp; 2651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.net.*; 2851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.io.*; 2951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.util.Date; 3051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.util.List; 3151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.util.Iterator; 3251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 3351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/** 3451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * A class that implements the FTP protocol according to 3551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * RFCs <A href="http://www.ietf.org/rfc/rfc0959.txt">959</A>, 3651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <A href="http://www.ietf.org/rfc/rfc2228.txt">2228</A>, 3751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <A href="http://www.ietf.org/rfc/rfc2389.txt">2389</A>, 3851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <A href="http://www.ietf.org/rfc/rfc2428.txt">2428</A>, 3951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <A href="http://www.ietf.org/rfc/rfc3659.txt">3659</A>, 4051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <A href="http://www.ietf.org/rfc/rfc4217.txt">4217</A>. 4151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Which includes support for FTP over SSL/TLS (aka ftps). 4251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 4351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code FtpClient} provides all the functionalities of a typical FTP 4451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * client, like storing or retrieving files, listing or creating directories. 4551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * A typical usage would consist of connecting the client to the server, 4651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * log in, issue a few commands then logout. 4751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Here is a code example: 4851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <pre> 4951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FtpClient cl = FtpClient.create(); 5051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * cl.connect("ftp.gnu.org").login("anonymous", "john.doe@mydomain.com".toCharArray())).changeDirectory("pub/gnu"); 5151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Iterator<FtpDirEntry> dir = cl.listFiles(); 5251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * while (dir.hasNext()) { 5351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FtpDirEntry f = dir.next(); 5451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * System.err.println(f.getName()); 5551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 5651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * cl.close(); 5751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 5851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </pre> 5951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p><b>Error reporting:</b> There are, mostly, two families of errors that 6051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * can occur during an FTP session. The first kind are the network related issues 6151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * like a connection reset, and they are usually fatal to the session, meaning, 6251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * in all likelyhood the connection to the server has been lost and the session 6351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * should be restarted from scratch. These errors are reported by throwing an 6451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link IOException}. The second kind are the errors reported by the FTP server, 6551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * like when trying to download a non-existing file for example. These errors 6651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * are usually non fatal to the session, meaning more commands can be sent to the 6751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * server. In these cases, a {@link FtpProtocolException} is thrown.</p> 6851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> 6951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * It should be noted that this is not a thread-safe API, as it wouldn't make 7051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * too much sense, due to the very sequential nature of FTP, to provide a 7151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * client able to be manipulated from multiple threads. 7251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.7 7451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 7551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipublic abstract class FtpClient implements java.io.Closeable { 7651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 7751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski private static final int FTP_PORT = 21; 7851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 7951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static enum TransferType { 8051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 8151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski ASCII, BINARY, EBCDIC 8251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski }; 8351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 8451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 8551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the default FTP port number. 8651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 8751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the port number. 8851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 8951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static final int defaultPort() { 9051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return FTP_PORT; 9151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 9251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 9351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 9451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Creates an instance of FtpClient. The client is not connected to any 9551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * server yet. 9651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 9851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski protected FtpClient() { 9951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 10051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 10151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 10251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Creates an instance of {@code FtpClient}. The client is not connected to any 10351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * server yet. 10451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 10551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the created {@code FtpClient} 10651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 10751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static FtpClient create() { 10851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski FtpClientProvider provider = FtpClientProvider.provider(); 10951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return provider.createFtpClient(); 11051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 11151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 11251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 11351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Creates an instance of FtpClient and connects it to the specified 11451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * address. 11551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 11651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param dest the {@code InetSocketAddress} to connect to. 11751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return The created {@code FtpClient} 11851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if the connection fails 11951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #connect(java.net.SocketAddress) 12051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 12151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static FtpClient create(InetSocketAddress dest) throws FtpProtocolException, IOException { 12251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski FtpClient client = create(); 12351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (dest != null) { 12451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski client.connect(dest); 12551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 12651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return client; 12751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 12851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 12951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 13051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Creates an instance of {@code FtpClient} and connects it to the 13151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * specified host on the default FTP port. 13251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 13351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param dest the {@code String} containing the name of the host 13451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to connect to. 13551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return The created {@code FtpClient} 13651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if the connection fails. 13751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the server rejected the connection 13851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 13951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static FtpClient create(String dest) throws FtpProtocolException, IOException { 14051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return create(new InetSocketAddress(dest, FTP_PORT)); 14151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 14251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 14351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 14451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Enables, or disables, the use of the <I>passive</I> mode. In that mode, 14551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * data connections are established by having the client connect to the server. 14651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This is the recommended default mode as it will work best through 14751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * firewalls and NATs. If set to {@code false} the mode is said to be 14851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <I>active</I> which means the server will connect back to the client 14951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * after a PORT command to establish a data connection. 15051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 15151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p><b>Note:</b> Since the passive mode might not be supported by all 15251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FTP servers, enabling it means the client will try to use it. If the 15351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * server rejects it, then the client will attempt to fall back to using 15451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the <I>active</I> mode by issuing a {@code PORT} command instead.</p> 15551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 15651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param passive {@code true} to force passive mode. 15751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return This FtpClient 15851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #isPassiveModeEnabled() 15951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 16051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient enablePassiveMode(boolean passive); 16151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 16251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 16351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Tests whether passive mode is enabled. 16451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 16551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return {@code true} if the passive mode has been enabled. 16651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #enablePassiveMode(boolean) 16751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 16851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract boolean isPassiveModeEnabled(); 16951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 17051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 17151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets the default timeout value to use when connecting to the server, 17251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 17351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param timeout the timeout value, in milliseconds, to use for the connect 17451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operation. A value of zero or less, means use the default timeout. 17551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 17651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return This FtpClient 17751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 17851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient setConnectTimeout(int timeout); 17951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 18051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 18151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the current default connection timeout value. 18251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 18351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the value, in milliseconds, of the current connect timeout. 18451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #setConnectTimeout(int) 18551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 18651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract int getConnectTimeout(); 18751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 18851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 18951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets the timeout value to use when reading from the server, 19051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 19151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param timeout the timeout value, in milliseconds, to use for the read 19251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operation. A value of zero or less, means use the default timeout. 19351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return This FtpClient 19451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 19551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient setReadTimeout(int timeout); 19651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 19751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 19851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the current read timeout value. 19951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 20051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the value, in milliseconds, of the current read timeout. 20151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #setReadTimeout(int) 20251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 20351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract int getReadTimeout(); 20451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 20551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 20651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Set the {@code Proxy} to be used for the next connection. 20751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the client is already connected, it doesn't affect the current 20851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * connection. However it is not recommended to change this during a session. 20951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 21051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param p the {@code Proxy} to use, or {@code null} for no proxy. 21151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return This FtpClient 21251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 21351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient setProxy(Proxy p); 21451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 21551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 21651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Get the proxy of this FtpClient 21751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 21851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the {@code Proxy}, this client is using, or {@code null} 21951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * if none is used. 22051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #setProxy(Proxy) 22151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 22251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract Proxy getProxy(); 22351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 22451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 22551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Tests whether this client is connected or not to a server. 22651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 22751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return {@code true} if the client is connected. 22851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 22951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract boolean isConnected(); 23051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 23151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 23251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Connects the {@code FtpClient} to the specified destination server. 23351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 23451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param dest the address of the destination server 23551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 23651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if connection failed. 23751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws SecurityException if there is a SecurityManager installed and it 23851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * denied the authorization to connect to the destination. 23951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException 24051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 24151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient connect(SocketAddress dest) throws FtpProtocolException, IOException; 24251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 24351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 24451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Connects the FtpClient to the specified destination server. 24551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 24651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param dest the address of the destination server 24751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param timeout the value, in milliseconds, to use as a connection timeout 24851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 24951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if connection failed. 25051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws SecurityException if there is a SecurityManager installed and it 25151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * denied the authorization to connect to the destination. 25251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException 25351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 25451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient connect(SocketAddress dest, int timeout) throws FtpProtocolException, IOException; 25551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 25651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 25751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Retrieves the address of the FTP server this client is connected to. 25851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 25951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the {@link SocketAddress} of the server, or {@code null} if this 26051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * client is not connected yet. 26151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 26251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract SocketAddress getServerAddress(); 26351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 26451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 26551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Attempts to log on the server with the specified user name and password. 26651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 26751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param user The user name 26851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param password The password for that user 26951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 27051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission 27151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the login was refused by the server 27251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 27351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient login(String user, char[] password) throws FtpProtocolException, IOException; 27451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 27551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 27651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Attempts to log on the server with the specified user name, password and 27751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * account name. 27851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 27951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param user The user name 28051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param password The password for that user. 28151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param account The account name for that user. 28251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 28351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 28451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the login was refused by the server 28551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 28651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient login(String user, char[] password, String account) throws FtpProtocolException, IOException; 28751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 28851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 28951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Closes the current connection. Logs out the current user, if any, by 29051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * issuing the QUIT command to the server. 29151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This is in effect terminates the current 29251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * session and the connection to the server will be closed. 29351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>After a close, the client can then be connected to another server 29451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to start an entirely different session.</P> 29551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 29651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during transmission 29751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 29851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract void close() throws IOException; 29951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 30051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 30151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Checks whether the client is logged in to the server or not. 30251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 30351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return {@code true} if the client has already completed a login. 30451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 30551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract boolean isLoggedIn(); 30651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 30751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 30851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Changes to a specific directory on a remote FTP server 30951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 31051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param remoteDirectory path of the directory to CD to. 31151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 31251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 31351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was refused by the server 31451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 31551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient changeDirectory(String remoteDirectory) throws FtpProtocolException, IOException; 31651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 31751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 31851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Changes to the parent directory, sending the CDUP command to the server. 31951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 32051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 32151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 32251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was refused by the server 32351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 32451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient changeToParentDirectory() throws FtpProtocolException, IOException; 32551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 32651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 32751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Retrieve the server current working directory using the PWD command. 32851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 32951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a {@code String} containing the current working directory 33051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during transmission 33151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was refused by the server, 33251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 33351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract String getWorkingDirectory() throws FtpProtocolException, IOException; 33451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 33551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 33651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets the restart offset to the specified value. That value will be 33751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * sent through a {@code REST} command to server before the next file 33851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transfer and has the effect of resuming a file transfer from the 33951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * specified point. After the transfer the restart offset is set back to 34051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * zero. 34151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 34251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param offset the offset in the remote file at which to start the next 34351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transfer. This must be a value greater than or equal to zero. 34451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 34551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException if the offset is negative. 34651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 34751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient setRestartOffset(long offset); 34851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 34951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 35051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Retrieves a file from the ftp server and writes its content to the specified 35151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code OutputStream}. 35251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>If the restart offset was set, then a {@code REST} command will be 35351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * sent before the {@code RETR} in order to restart the tranfer from the specified 35451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * offset.</p> 35551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>The {@code OutputStream} is not closed by this method at the end 35651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * of the transfer. </p> 35751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>This method will block until the transfer is complete or an exception 35851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is thrown.</p> 35951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 36051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name a {@code String} containing the name of the file to 36151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * retreive from the server. 36251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param local the {@code OutputStream} the file should be written to. 36351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 36451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if the transfer fails. 36551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was refused by the server 36651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #setRestartOffset(long) 36751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 36851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient getFile(String name, OutputStream local) throws FtpProtocolException, IOException; 36951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 37051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 37151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Retrieves a file from the ftp server, using the {@code RETR} command, and 37251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * returns the InputStream from the established data connection. 37351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #completePending()} <b>has</b> to be called once the application 37451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is done reading from the returned stream. 37551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>If the restart offset was set, then a {@code REST} command will be 37651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * sent before the {@code RETR} in order to restart the tranfer from the specified 37751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * offset.</p> 37851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 37951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name the name of the remote file 38051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the {@link java.io.InputStream} from the data connection 38151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 38251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was refused by the server 38351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #setRestartOffset(long) 38451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 38551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract InputStream getFileStream(String name) throws FtpProtocolException, IOException; 38651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 38751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 38851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Transfers a file from the client to the server (aka a <I>put</I>) 38951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by sending the STOR command, and returns the {@code OutputStream} 39051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * from the established data connection. 39151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 39251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * A new file is created at the server site if the file specified does 39351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * not already exist. 39451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 39551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #completePending()} <b>has</b> to be called once the application 39651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is finished writing to the returned stream. 39751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 39851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name the name of the remote file to write. 39951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the {@link java.io.OutputStream} from the data connection or 40051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code null} if the command was unsuccessful. 40151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 40251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 40351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 40451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public OutputStream putFileStream(String name) throws FtpProtocolException, IOException { 40551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return putFileStream(name, false); 40651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 40751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 40851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 40951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Transfers a file from the client to the server (aka a <I>put</I>) 41051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by sending the STOR or STOU command, depending on the 41151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code unique} argument, and returns the {@code OutputStream} 41251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * from the established data connection. 41351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #completePending()} <b>has</b> to be called once the application 41451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is finished writing to the stream. 41551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 41651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * A new file is created at the server site if the file specified does 41751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * not already exist. 41851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 41951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If {@code unique} is set to {@code true}, the resultant file 42051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is to be created under a name unique to that directory, meaning 42151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * it will not overwrite an existing file, instead the server will 42251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * generate a new, unique, file name. 42351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The name of the remote file can be retrieved, after completion of the 42451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transfer, by calling {@link #getLastFileName()}. 42551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 42651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name the name of the remote file to write. 42751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param unique {@code true} if the remote files should be unique, 42851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * in which case the STOU command will be used. 42951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the {@link java.io.OutputStream} from the data connection. 43051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 43151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 43251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 43351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract OutputStream putFileStream(String name, boolean unique) throws FtpProtocolException, IOException; 43451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 43551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 43651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Transfers a file from the client to the server (aka a <I>put</I>) 43751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by sending the STOR or STOU command, depending on the 43851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code unique} argument. The content of the {@code InputStream} 43951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * passed in argument is written into the remote file, overwriting any 44051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * existing data. 44151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 44251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * A new file is created at the server site if the file specified does 44351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * not already exist. 44451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 44551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If {@code unique} is set to {@code true}, the resultant file 44651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is to be created under a name unique to that directory, meaning 44751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * it will not overwrite an existing file, instead the server will 44851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * generate a new, unique, file name. 44951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The name of the remote file can be retrieved, after completion of the 45051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transfer, by calling {@link #getLastFileName()}. 45151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 45251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>This method will block until the transfer is complete or an exception 45351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is thrown.</p> 45451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 45551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name the name of the remote file to write. 45651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param local the {@code InputStream} that points to the data to 45751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transfer. 45851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 45951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 46051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 46151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 46251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public FtpClient putFile(String name, InputStream local) throws FtpProtocolException, IOException { 46351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return putFile(name, local, false); 46451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 46551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 46651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 46751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Transfers a file from the client to the server (aka a <I>put</I>) 46851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by sending the STOR command. The content of the {@code InputStream} 46951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * passed in argument is written into the remote file, overwriting any 47051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * existing data. 47151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 47251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * A new file is created at the server site if the file specified does 47351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * not already exist. 47451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 47551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>This method will block until the transfer is complete or an exception 47651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is thrown.</p> 47751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 47851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name the name of the remote file to write. 47951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param local the {@code InputStream} that points to the data to 48051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transfer. 48151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param unique {@code true} if the remote file should be unique 48251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * (i.e. not already existing), {@code false} otherwise. 48351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 48451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 48551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 48651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #getLastFileName() 48751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 48851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient putFile(String name, InputStream local, boolean unique) throws FtpProtocolException, IOException; 48951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 49051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 49151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends the APPE command to the server in order to transfer a data stream 49251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * passed in argument and append it to the content of the specified remote 49351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * file. 49451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 49551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>This method will block until the transfer is complete or an exception 49651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is thrown.</p> 49751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 49851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name A {@code String} containing the name of the remote file 49951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to append to. 50051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param local The {@code InputStream} providing access to the data 50151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to be appended. 50251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 50351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 50451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 50551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 50651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient appendFile(String name, InputStream local) throws FtpProtocolException, IOException; 50751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 50851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 50951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Renames a file on the server. 51051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 51151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param from the name of the file being renamed 51251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param to the new name for the file 51351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 51451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 51551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 51651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 51751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient rename(String from, String to) throws FtpProtocolException, IOException; 51851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 51951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 52051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Deletes a file on the server. 52151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 52251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name a {@code String} containing the name of the file 52351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to delete. 52451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 52551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the exchange 52651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 52751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 52851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient deleteFile(String name) throws FtpProtocolException, IOException; 52951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 53051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 53151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Creates a new directory on the server. 53251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 53351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name a {@code String} containing the name of the directory 53451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to create. 53551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 53651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the exchange 53751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 53851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 53951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient makeDirectory(String name) throws FtpProtocolException, IOException; 54051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 54151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 54251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Removes a directory on the server. 54351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 54451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name a {@code String} containing the name of the directory 54551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to remove. 54651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 54751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 54851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the exchange. 54951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 55051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 55151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient removeDirectory(String name) throws FtpProtocolException, IOException; 55251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 55351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 55451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends a No-operation command. It's useful for testing the connection 55551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * status or as a <I>keep alive</I> mechanism. 55651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 55751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 55851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 55951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 56051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 56151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient noop() throws FtpProtocolException, IOException; 56251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 56351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 56451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends the {@code STAT} command to the server. 56551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This can be used while a data connection is open to get a status 56651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * on the current transfer, in that case the parameter should be 56751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code null}. 56851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If used between file transfers, it may have a pathname as argument 56951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * in which case it will work as the LIST command except no data 57051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * connection will be created. 57151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 57251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param name an optional {@code String} containing the pathname 57351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the STAT command should apply to. 57451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the response from the server 57551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 57651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 57751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 57851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract String getStatus(String name) throws FtpProtocolException, IOException; 57951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 58051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 58151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends the {@code FEAT} command to the server and returns the list of supported 58251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * features in the form of strings. 58351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 58451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The features are the supported commands, like AUTH TLS, PROT or PASV. 58551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * See the RFCs for a complete list. 58651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 58751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Note that not all FTP servers support that command, in which case 58851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * a {@link FtpProtocolException} will be thrown. 58951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 59051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a {@code List} of {@code Strings} describing the 59151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * supported additional features 59251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 59351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command is rejected by the server 59451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 59551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract List<String> getFeatures() throws FtpProtocolException, IOException; 59651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 59751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 59851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends the {@code ABOR} command to the server. 59951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>It tells the server to stop the previous command or transfer. No action 60051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * will be taken if the previous command has already been completed.</p> 60151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>This doesn't abort the current session, more commands can be issued 60251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * after an abort.</p> 60351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 60451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 60551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 60651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 60751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 60851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient abort() throws FtpProtocolException, IOException; 60951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 61051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 61151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Some methods do not wait until completion before returning, so this 61251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * method can be called to wait until completion. This is typically the case 61351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * with commands that trigger a transfer like {@link #getFileStream(String)}. 61451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * So this method should be called before accessing information related to 61551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * such a command. 61651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>This method will actually block reading on the command channel for a 61751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * notification from the server that the command is finished. Such a 61851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * notification often carries extra information concerning the completion 61951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * of the pending action (e.g. number of bytes transfered).</p> 62051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>Note that this will return immediately if no command or action 62151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is pending</p> 62251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>It should be also noted that most methods issuing commands to the ftp 62351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * server will call this method if a previous command is pending. 62451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>Example of use: 62551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <pre> 62651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * InputStream in = cl.getFileStream("file"); 62751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ... 62851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * cl.completePending(); 62951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * long size = cl.getLastTransferSize(); 63051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </pre> 63151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * On the other hand, it's not necessary in a case like: 63251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <pre> 63351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * InputStream in = cl.getFileStream("file"); 63451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * // read content 63551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ... 63651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * cl.close(); 63751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </pre> 63851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>Since {@link #close()} will call completePending() if necessary.</p> 63951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 64051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transfer 64151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command didn't complete successfully 64251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 64351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient completePending() throws FtpProtocolException, IOException; 64451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 64551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 64651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Reinitializes the USER parameters on the FTP server 64751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 64851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 64951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during transmission 65051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command fails 65151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 65251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient reInit() throws FtpProtocolException, IOException; 65351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 65451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 65551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Changes the transfer type (binary, ascii, ebcdic) and issue the 65651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * proper command (e.g. TYPE A) to the server. 65751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 65851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param type the {@code TransferType} to use. 65951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return This FtpClient 66051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during transmission. 66151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 66251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 66351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient setType(TransferType type) throws FtpProtocolException, IOException; 66451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 66551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 66651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Changes the current transfer type to binary. 66751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This is a convenience method that is equivalent to 66851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code setType(TransferType.BINARY)} 66951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 67051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return This FtpClient 67151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 67251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 67351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #setType(TransferType) 67451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 67551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public FtpClient setBinaryType() throws FtpProtocolException, IOException { 67651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski setType(TransferType.BINARY); 67751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return this; 67851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 67951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 68051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 68151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Changes the current transfer type to ascii. 68251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This is a convenience method that is equivalent to 68351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code setType(TransferType.ASCII)} 68451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 68551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return This FtpClient 68651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 68751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 68851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #setType(TransferType) 68951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 69051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public FtpClient setAsciiType() throws FtpProtocolException, IOException { 69151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski setType(TransferType.ASCII); 69251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return this; 69351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 69451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 69551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 69651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Issues a {@code LIST} command to the server to get the current directory 69751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * listing, and returns the InputStream from the data connection. 69851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 69951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>{@link #completePending()} <b>has</b> to be called once the application 70051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is finished reading from the stream.</p> 70151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 70251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param path the pathname of the directory to list, or {@code null} 70351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * for the current working directory. 70451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the {@code InputStream} from the resulting data connection 70551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 70651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 70751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #changeDirectory(String) 70851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #listFiles(String) 70951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 71051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract InputStream list(String path) throws FtpProtocolException, IOException; 71151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 71251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 71351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Issues a {@code NLST path} command to server to get the specified directory 71451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * content. It differs from {@link #list(String)} method by the fact that 71551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * it will only list the file names which would make the parsing of the 71651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * somewhat easier. 71751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 71851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>{@link #completePending()} <b>has</b> to be called once the application 71951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is finished reading from the stream.</p> 72051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 72151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param path a {@code String} containing the pathname of the 72251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * directory to list or {@code null} for the current working directory. 72351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the {@code InputStream} from the resulting data connection 72451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 72551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 72651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 72751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract InputStream nameList(String path) throws FtpProtocolException, IOException; 72851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 72951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 73051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Issues the {@code SIZE [path]} command to the server to get the size of a 73151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * specific file on the server. 73251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Note that this command may not be supported by the server. In which 73351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * case -1 will be returned. 73451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 73551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param path a {@code String} containing the pathname of the 73651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * file. 73751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a {@code long} containing the size of the file or -1 if 73851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the server returned an error, which can be checked with 73951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #getLastReplyCode()}. 74051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 74151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 74251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 74351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract long getSize(String path) throws FtpProtocolException, IOException; 74451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 74551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 74651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Issues the {@code MDTM [path]} command to the server to get the modification 74751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * time of a specific file on the server. 74851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Note that this command may not be supported by the server, in which 74951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * case {@code null} will be returned. 75051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 75151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param path a {@code String} containing the pathname of the file. 75251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a {@code Date} representing the last modification time 75351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or {@code null} if the server returned an error, which 75451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * can be checked with {@link #getLastReplyCode()}. 75551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 75651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 75751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 75851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract Date getLastModified(String path) throws FtpProtocolException, IOException; 75951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 76051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 76151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets the parser used to handle the directory output to the specified 76251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * one. By default the parser is set to one that can handle most FTP 76351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * servers output (Unix base mostly). However it may be necessary for 76451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and application to provide its own parser due to some uncommon 76551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * output format. 76651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 76751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param p The {@code FtpDirParser} to use. 76851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 76951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #listFiles(String) 77051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 77151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient setDirParser(FtpDirParser p); 77251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 77351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 77451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Issues a {@code MLSD} command to the server to get the specified directory 77551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * listing and applies the internal parser to create an Iterator of 77651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link java.net.FtpDirEntry}. Note that the Iterator returned is also a 77751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link java.io.Closeable}. 77851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>If the server doesn't support the MLSD command, the LIST command is used 77951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * instead and the parser set by {@link #setDirParser(java.net.FtpDirParser) } 78051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is used instead.</p> 78151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 78251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #completePending()} <b>has</b> to be called once the application 78351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is finished iterating through the files. 78451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 78551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param path the pathname of the directory to list or {@code null} 78651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * for the current working directoty. 78751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a {@code Iterator} of files or {@code null} if the 78851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * command failed. 78951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission 79051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #setDirParser(FtpDirParser) 79151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #changeDirectory(String) 79251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 79351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 79451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract Iterator<FtpDirEntry> listFiles(String path) throws FtpProtocolException, IOException; 79551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 79651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 79751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Attempts to use Kerberos GSSAPI as an authentication mechanism with the 79851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ftp server. This will issue an {@code AUTH GSSAPI} command, and if 79951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * it is accepted by the server, will followup with {@code ADAT} 80051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * command to exchange the various tokens until authentication is 80151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * successful. This conforms to Appendix I of RFC 2228. 80251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 80351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 80451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occurs during the transmission. 80551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 80651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 80751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient useKerberos() throws FtpProtocolException, IOException; 80851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 80951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 81051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the Welcome string the server sent during initial connection. 81151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 81251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a {@code String} containing the message the server 81351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * returned during connection or {@code null}. 81451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 81551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract String getWelcomeMsg(); 81651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 81751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 81851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the last reply code sent by the server. 81951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 82051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the lastReplyCode or {@code null} if none were received yet. 82151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 82251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpReplyCode getLastReplyCode(); 82351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 82451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 82551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the last response string sent by the server. 82651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 82751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the message string, which can be quite long, last returned 82851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by the server, or {@code null} if no response were received yet. 82951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 83051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract String getLastResponseString(); 83151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 83251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 83351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns, when available, the size of the latest started transfer. 83451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This is retreived by parsing the response string received as an initial 83551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * response to a {@code RETR} or similar request. 83651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 83751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the size of the latest transfer or -1 if either there was no 83851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transfer or the information was unavailable. 83951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 84051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract long getLastTransferSize(); 84151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 84251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 84351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns, when available, the remote name of the last transfered file. 84451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This is mainly useful for "put" operation when the unique flag was 84551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * set since it allows to recover the unique file name created on the 84651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * server which may be different from the one submitted with the command. 84751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 84851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the name the latest transfered file remote name, or 84951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code null} if that information is unavailable. 85051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 85151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract String getLastFileName(); 85251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 85351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 85451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Attempts to switch to a secure, encrypted connection. This is done by 85551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * sending the {@code AUTH TLS} command. 85651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>See <a href="http://www.ietf.org/rfc/rfc4217.txt">RFC 4217</a></p> 85751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If successful this will establish a secure command channel with the 85851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * server, it will also make it so that all other transfers (e.g. a RETR 85951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * command) will be done over an encrypted channel as well unless a 86051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #reInit()} command or a {@link #endSecureSession()} command is issued. 86151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>This method should be called after a successful {@link #connect(java.net.InetSocketAddress) } 86251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * but before calling {@link #login(java.lang.String, char[]) }.</p> 86351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 86451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpCLient 86551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 86651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 86751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #endSecureSession() 86851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 86951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient startSecureSession() throws FtpProtocolException, IOException; 87051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 87151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 87251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends a {@code CCC} command followed by a {@code PROT C} 87351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * command to the server terminating an encrypted session and reverting 87451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * back to a non encrypted transmission. 87551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 87651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 87751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during transmission. 87851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 87951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #startSecureSession() 88051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 88151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient endSecureSession() throws FtpProtocolException, IOException; 88251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 88351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 88451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends the "Allocate" ({@code ALLO}) command to the server telling it to 88551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * pre-allocate the specified number of bytes for the next transfer. 88651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 88751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param size The number of bytes to allocate. 88851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 88951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 89051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 89151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 89251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient allocate(long size) throws FtpProtocolException, IOException; 89351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 89451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 89551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends the "Structure Mount" ({@code SMNT}) command to the server. This let the 89651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * user mount a different file system data structure without altering his 89751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * login or accounting information. 89851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 89951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param struct a {@code String} containing the name of the 90051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * structure to mount. 90151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 90251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 90351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 90451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 90551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient structureMount(String struct) throws FtpProtocolException, IOException; 90651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 90751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 90851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends a System ({@code SYST}) command to the server and returns the String 90951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * sent back by the server describing the operating system at the 91051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * server. 91151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 91251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a {@code String} describing the OS, or {@code null} 91351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * if the operation was not successful. 91451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during the transmission. 91551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 91651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 91751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract String getSystem() throws FtpProtocolException, IOException; 91851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 91951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 92051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends the {@code HELP} command to the server, with an optional command, like 92151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * SITE, and returns the text sent back by the server. 92251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 92351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param cmd the command for which the help is requested or 92451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code null} for the general help 92551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a {@code String} containing the text sent back by the 92651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * server, or {@code null} if the command failed. 92751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during transmission 92851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 92951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 93051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract String getHelp(String cmd) throws FtpProtocolException, IOException; 93151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 93251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 93351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sends the {@code SITE} command to the server. This is used by the server 93451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to provide services specific to his system that are essential 93551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to file transfer. 93651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 93751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param cmd the command to be sent. 93851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return this FtpClient 93951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException if an error occured during transmission 94051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FtpProtocolException if the command was rejected by the server 94151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 94251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FtpClient siteCmd(String cmd) throws FtpProtocolException, IOException; 94351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski} 944