History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/sun/net/ftp/FtpClient.java (1 of 18352 files). Show all

Unified · Split

java/pkg/sun/net/ftp/FtpClient.java+943−0
@@ -0,0 +1,943 @@
1+/*
2+ * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+package sun.net.ftp;
26+
27+import java.net.*;
28+import java.io.*;
29+import java.util.Date;
30+import java.util.List;
31+import java.util.Iterator;
32+
33+/**
34+ * A class that implements the FTP protocol according to
35+ * RFCs <A href="http://www.ietf.org/rfc/rfc0959.txt">959</A>,
36+ * <A href="http://www.ietf.org/rfc/rfc2228.txt">2228</A>,
37+ * <A href="http://www.ietf.org/rfc/rfc2389.txt">2389</A>,
38+ * <A href="http://www.ietf.org/rfc/rfc2428.txt">2428</A>,
39+ * <A href="http://www.ietf.org/rfc/rfc3659.txt">3659</A>,
40+ * <A href="http://www.ietf.org/rfc/rfc4217.txt">4217</A>.
41+ * Which includes support for FTP over SSL/TLS (aka ftps).
42+ *
43+ * {@code FtpClient} provides all the functionalities of a typical FTP
44+ * client, like storing or retrieving files, listing or creating directories.
45+ * A typical usage would consist of connecting the client to the server,
46+ * log in, issue a few commands then logout.
47+ * Here is a code example:
48+ * <pre>
49+ * FtpClient cl = FtpClient.create();
50+ * cl.connect("ftp.gnu.org").login("anonymous", "john.doe@mydomain.com".toCharArray())).changeDirectory("pub/gnu");
51+ * Iterator&lt;FtpDirEntry&gt; dir = cl.listFiles();
52+ * while (dir.hasNext()) {
53+ * FtpDirEntry f = dir.next();
54+ * System.err.println(f.getName());
55+ * }
56+ * cl.close();
57+ * }
58+ * </pre>
59+ * <p><b>Error reporting:</b> There are, mostly, two families of errors that
60+ * can occur during an FTP session. The first kind are the network related issues
61+ * like a connection reset, and they are usually fatal to the session, meaning,
62+ * in all likelyhood the connection to the server has been lost and the session
63+ * should be restarted from scratch. These errors are reported by throwing an
64+ * {@link IOException}. The second kind are the errors reported by the FTP server,
65+ * like when trying to download a non-existing file for example. These errors
66+ * are usually non fatal to the session, meaning more commands can be sent to the
67+ * server. In these cases, a {@link FtpProtocolException} is thrown.</p>
68+ * <p>
69+ * It should be noted that this is not a thread-safe API, as it wouldn't make
70+ * too much sense, due to the very sequential nature of FTP, to provide a
71+ * client able to be manipulated from multiple threads.
72+ *
73+ * @since 1.7
74+ */
75+public abstract class FtpClient implements java.io.Closeable {
76+
77+ private static final int FTP_PORT = 21;
78+
79+ public static enum TransferType {
80+
81+ ASCII, BINARY, EBCDIC
82+ };
83+
84+ /**
85+ * Returns the default FTP port number.
86+ *
87+ * @return the port number.
88+ */
89+ public static final int defaultPort() {
90+ return FTP_PORT;
91+ }
92+
93+ /**
94+ * Creates an instance of FtpClient. The client is not connected to any
95+ * server yet.
96+ *
97+ */
98+ protected FtpClient() {
99+ }
100+
101+ /**
102+ * Creates an instance of {@code FtpClient}. The client is not connected to any
103+ * server yet.
104+ *
105+ * @return the created {@code FtpClient}
106+ */
107+ public static FtpClient create() {
108+ FtpClientProvider provider = FtpClientProvider.provider();
109+ return provider.createFtpClient();
110+ }
111+
112+ /**
113+ * Creates an instance of FtpClient and connects it to the specified
114+ * address.
115+ *
116+ * @param dest the {@code InetSocketAddress} to connect to.
117+ * @return The created {@code FtpClient}
118+ * @throws IOException if the connection fails
119+ * @see #connect(java.net.SocketAddress)
120+ */
121+ public static FtpClient create(InetSocketAddress dest) throws FtpProtocolException, IOException {
122+ FtpClient client = create();
123+ if (dest != null) {
124+ client.connect(dest);
125+ }
126+ return client;
127+ }
128+
129+ /**
130+ * Creates an instance of {@code FtpClient} and connects it to the
131+ * specified host on the default FTP port.
132+ *
133+ * @param dest the {@code String} containing the name of the host
134+ * to connect to.
135+ * @return The created {@code FtpClient}
136+ * @throws IOException if the connection fails.
137+ * @throws FtpProtocolException if the server rejected the connection
138+ */
139+ public static FtpClient create(String dest) throws FtpProtocolException, IOException {
140+ return create(new InetSocketAddress(dest, FTP_PORT));
141+ }
142+
143+ /**
144+ * Enables, or disables, the use of the <I>passive</I> mode. In that mode,
145+ * data connections are established by having the client connect to the server.
146+ * This is the recommended default mode as it will work best through
147+ * firewalls and NATs. If set to {@code false} the mode is said to be
148+ * <I>active</I> which means the server will connect back to the client
149+ * after a PORT command to establish a data connection.
150+ *
151+ * <p><b>Note:</b> Since the passive mode might not be supported by all
152+ * FTP servers, enabling it means the client will try to use it. If the
153+ * server rejects it, then the client will attempt to fall back to using
154+ * the <I>active</I> mode by issuing a {@code PORT} command instead.</p>
155+ *
156+ * @param passive {@code true} to force passive mode.
157+ * @return This FtpClient
158+ * @see #isPassiveModeEnabled()
159+ */
160+ public abstract FtpClient enablePassiveMode(boolean passive);
161+
162+ /**
163+ * Tests whether passive mode is enabled.
164+ *
165+ * @return {@code true} if the passive mode has been enabled.
166+ * @see #enablePassiveMode(boolean)
167+ */
168+ public abstract boolean isPassiveModeEnabled();
169+
170+ /**
171+ * Sets the default timeout value to use when connecting to the server,
172+ *
173+ * @param timeout the timeout value, in milliseconds, to use for the connect
174+ * operation. A value of zero or less, means use the default timeout.
175+ *
176+ * @return This FtpClient
177+ */
178+ public abstract FtpClient setConnectTimeout(int timeout);
179+
180+ /**
181+ * Returns the current default connection timeout value.
182+ *
183+ * @return the value, in milliseconds, of the current connect timeout.
184+ * @see #setConnectTimeout(int)
185+ */
186+ public abstract int getConnectTimeout();
187+
188+ /**
189+ * Sets the timeout value to use when reading from the server,
190+ *
191+ * @param timeout the timeout value, in milliseconds, to use for the read
192+ * operation. A value of zero or less, means use the default timeout.
193+ * @return This FtpClient
194+ */
195+ public abstract FtpClient setReadTimeout(int timeout);
196+
197+ /**
198+ * Returns the current read timeout value.
199+ *
200+ * @return the value, in milliseconds, of the current read timeout.
201+ * @see #setReadTimeout(int)
202+ */
203+ public abstract int getReadTimeout();
204+
205+ /**
206+ * Set the {@code Proxy} to be used for the next connection.
207+ * If the client is already connected, it doesn't affect the current
208+ * connection. However it is not recommended to change this during a session.
209+ *
210+ * @param p the {@code Proxy} to use, or {@code null} for no proxy.
211+ * @return This FtpClient
212+ */
213+ public abstract FtpClient setProxy(Proxy p);
214+
215+ /**
216+ * Get the proxy of this FtpClient
217+ *
218+ * @return the {@code Proxy}, this client is using, or {@code null}
219+ * if none is used.
220+ * @see #setProxy(Proxy)
221+ */
222+ public abstract Proxy getProxy();
223+
224+ /**
225+ * Tests whether this client is connected or not to a server.
226+ *
227+ * @return {@code true} if the client is connected.
228+ */
229+ public abstract boolean isConnected();
230+
231+ /**
232+ * Connects the {@code FtpClient} to the specified destination server.
233+ *
234+ * @param dest the address of the destination server
235+ * @return this FtpClient
236+ * @throws IOException if connection failed.
237+ * @throws SecurityException if there is a SecurityManager installed and it
238+ * denied the authorization to connect to the destination.
239+ * @throws FtpProtocolException
240+ */
241+ public abstract FtpClient connect(SocketAddress dest) throws FtpProtocolException, IOException;
242+
243+ /**
244+ * Connects the FtpClient to the specified destination server.
245+ *
246+ * @param dest the address of the destination server
247+ * @param timeout the value, in milliseconds, to use as a connection timeout
248+ * @return this FtpClient
249+ * @throws IOException if connection failed.
250+ * @throws SecurityException if there is a SecurityManager installed and it
251+ * denied the authorization to connect to the destination.
252+ * @throws FtpProtocolException
253+ */
254+ public abstract FtpClient connect(SocketAddress dest, int timeout) throws FtpProtocolException, IOException;
255+
256+ /**
257+ * Retrieves the address of the FTP server this client is connected to.
258+ *
259+ * @return the {@link SocketAddress} of the server, or {@code null} if this
260+ * client is not connected yet.
261+ */
262+ public abstract SocketAddress getServerAddress();
263+
264+ /**
265+ * Attempts to log on the server with the specified user name and password.
266+ *
267+ * @param user The user name
268+ * @param password The password for that user
269+ * @return this FtpClient
270+ * @throws IOException if an error occured during the transmission
271+ * @throws FtpProtocolException if the login was refused by the server
272+ */
273+ public abstract FtpClient login(String user, char[] password) throws FtpProtocolException, IOException;
274+
275+ /**
276+ * Attempts to log on the server with the specified user name, password and
277+ * account name.
278+ *
279+ * @param user The user name
280+ * @param password The password for that user.
281+ * @param account The account name for that user.
282+ * @return this FtpClient
283+ * @throws IOException if an error occurs during the transmission.
284+ * @throws FtpProtocolException if the login was refused by the server
285+ */
286+ public abstract FtpClient login(String user, char[] password, String account) throws FtpProtocolException, IOException;
287+
288+ /**
289+ * Closes the current connection. Logs out the current user, if any, by
290+ * issuing the QUIT command to the server.
291+ * This is in effect terminates the current
292+ * session and the connection to the server will be closed.
293+ * <p>After a close, the client can then be connected to another server
294+ * to start an entirely different session.</P>
295+ *
296+ * @throws IOException if an error occurs during transmission
297+ */
298+ public abstract void close() throws IOException;
299+
300+ /**
301+ * Checks whether the client is logged in to the server or not.
302+ *
303+ * @return {@code true} if the client has already completed a login.
304+ */
305+ public abstract boolean isLoggedIn();
306+
307+ /**
308+ * Changes to a specific directory on a remote FTP server
309+ *
310+ * @param remoteDirectory path of the directory to CD to.
311+ * @return this FtpClient
312+ * @throws IOException if an error occurs during the transmission.
313+ * @throws FtpProtocolException if the command was refused by the server
314+ */
315+ public abstract FtpClient changeDirectory(String remoteDirectory) throws FtpProtocolException, IOException;
316+
317+ /**
318+ * Changes to the parent directory, sending the CDUP command to the server.
319+ *
320+ * @return this FtpClient
321+ * @throws IOException if an error occurs during the transmission.
322+ * @throws FtpProtocolException if the command was refused by the server
323+ */
324+ public abstract FtpClient changeToParentDirectory() throws FtpProtocolException, IOException;
325+
326+ /**
327+ * Retrieve the server current working directory using the PWD command.
328+ *
329+ * @return a {@code String} containing the current working directory
330+ * @throws IOException if an error occurs during transmission
331+ * @throws FtpProtocolException if the command was refused by the server,
332+ */
333+ public abstract String getWorkingDirectory() throws FtpProtocolException, IOException;
334+
335+ /**
336+ * Sets the restart offset to the specified value. That value will be
337+ * sent through a {@code REST} command to server before the next file
338+ * transfer and has the effect of resuming a file transfer from the
339+ * specified point. After the transfer the restart offset is set back to
340+ * zero.
341+ *
342+ * @param offset the offset in the remote file at which to start the next
343+ * transfer. This must be a value greater than or equal to zero.
344+ * @return this FtpClient
345+ * @throws IllegalArgumentException if the offset is negative.
346+ */
347+ public abstract FtpClient setRestartOffset(long offset);
348+
349+ /**
350+ * Retrieves a file from the ftp server and writes its content to the specified
351+ * {@code OutputStream}.
352+ * <p>If the restart offset was set, then a {@code REST} command will be
353+ * sent before the {@code RETR} in order to restart the tranfer from the specified
354+ * offset.</p>
355+ * <p>The {@code OutputStream} is not closed by this method at the end
356+ * of the transfer. </p>
357+ * <p>This method will block until the transfer is complete or an exception
358+ * is thrown.</p>
359+ *
360+ * @param name a {@code String} containing the name of the file to
361+ * retreive from the server.
362+ * @param local the {@code OutputStream} the file should be written to.
363+ * @return this FtpClient
364+ * @throws IOException if the transfer fails.
365+ * @throws FtpProtocolException if the command was refused by the server
366+ * @see #setRestartOffset(long)
367+ */
368+ public abstract FtpClient getFile(String name, OutputStream local) throws FtpProtocolException, IOException;
369+
370+ /**
371+ * Retrieves a file from the ftp server, using the {@code RETR} command, and
372+ * returns the InputStream from the established data connection.
373+ * {@link #completePending()} <b>has</b> to be called once the application
374+ * is done reading from the returned stream.
375+ * <p>If the restart offset was set, then a {@code REST} command will be
376+ * sent before the {@code RETR} in order to restart the tranfer from the specified
377+ * offset.</p>
378+ *
379+ * @param name the name of the remote file
380+ * @return the {@link java.io.InputStream} from the data connection
381+ * @throws IOException if an error occured during the transmission.
382+ * @throws FtpProtocolException if the command was refused by the server
383+ * @see #setRestartOffset(long)
384+ */
385+ public abstract InputStream getFileStream(String name) throws FtpProtocolException, IOException;
386+
387+ /**
388+ * Transfers a file from the client to the server (aka a <I>put</I>)
389+ * by sending the STOR command, and returns the {@code OutputStream}
390+ * from the established data connection.
391+ *
392+ * A new file is created at the server site if the file specified does
393+ * not already exist.
394+ *
395+ * {@link #completePending()} <b>has</b> to be called once the application
396+ * is finished writing to the returned stream.
397+ *
398+ * @param name the name of the remote file to write.
399+ * @return the {@link java.io.OutputStream} from the data connection or
400+ * {@code null} if the command was unsuccessful.
401+ * @throws IOException if an error occured during the transmission.
402+ * @throws FtpProtocolException if the command was rejected by the server
403+ */
404+ public OutputStream putFileStream(String name) throws FtpProtocolException, IOException {
405+ return putFileStream(name, false);
406+ }
407+
408+ /**
409+ * Transfers a file from the client to the server (aka a <I>put</I>)
410+ * by sending the STOR or STOU command, depending on the
411+ * {@code unique} argument, and returns the {@code OutputStream}
412+ * from the established data connection.
413+ * {@link #completePending()} <b>has</b> to be called once the application
414+ * is finished writing to the stream.
415+ *
416+ * A new file is created at the server site if the file specified does
417+ * not already exist.
418+ *
419+ * If {@code unique} is set to {@code true}, the resultant file
420+ * is to be created under a name unique to that directory, meaning
421+ * it will not overwrite an existing file, instead the server will
422+ * generate a new, unique, file name.
423+ * The name of the remote file can be retrieved, after completion of the
424+ * transfer, by calling {@link #getLastFileName()}.
425+ *
426+ * @param name the name of the remote file to write.
427+ * @param unique {@code true} if the remote files should be unique,
428+ * in which case the STOU command will be used.
429+ * @return the {@link java.io.OutputStream} from the data connection.
430+ * @throws IOException if an error occured during the transmission.
431+ * @throws FtpProtocolException if the command was rejected by the server
432+ */
433+ public abstract OutputStream putFileStream(String name, boolean unique) throws FtpProtocolException, IOException;
434+
435+ /**
436+ * Transfers a file from the client to the server (aka a <I>put</I>)
437+ * by sending the STOR or STOU command, depending on the
438+ * {@code unique} argument. The content of the {@code InputStream}
439+ * passed in argument is written into the remote file, overwriting any
440+ * existing data.
441+ *
442+ * A new file is created at the server site if the file specified does
443+ * not already exist.
444+ *
445+ * If {@code unique} is set to {@code true}, the resultant file
446+ * is to be created under a name unique to that directory, meaning
447+ * it will not overwrite an existing file, instead the server will
448+ * generate a new, unique, file name.
449+ * The name of the remote file can be retrieved, after completion of the
450+ * transfer, by calling {@link #getLastFileName()}.
451+ *
452+ * <p>This method will block until the transfer is complete or an exception
453+ * is thrown.</p>
454+ *
455+ * @param name the name of the remote file to write.
456+ * @param local the {@code InputStream} that points to the data to
457+ * transfer.
458+ * @return this FtpClient
459+ * @throws IOException if an error occured during the transmission.
460+ * @throws FtpProtocolException if the command was rejected by the server
461+ */
462+ public FtpClient putFile(String name, InputStream local) throws FtpProtocolException, IOException {
463+ return putFile(name, local, false);
464+ }
465+
466+ /**
467+ * Transfers a file from the client to the server (aka a <I>put</I>)
468+ * by sending the STOR command. The content of the {@code InputStream}
469+ * passed in argument is written into the remote file, overwriting any
470+ * existing data.
471+ *
472+ * A new file is created at the server site if the file specified does
473+ * not already exist.
474+ *
475+ * <p>This method will block until the transfer is complete or an exception
476+ * is thrown.</p>
477+ *
478+ * @param name the name of the remote file to write.
479+ * @param local the {@code InputStream} that points to the data to
480+ * transfer.
481+ * @param unique {@code true} if the remote file should be unique
482+ * (i.e. not already existing), {@code false} otherwise.
483+ * @return this FtpClient
484+ * @throws IOException if an error occured during the transmission.
485+ * @throws FtpProtocolException if the command was rejected by the server
486+ * @see #getLastFileName()
487+ */
488+ public abstract FtpClient putFile(String name, InputStream local, boolean unique) throws FtpProtocolException, IOException;
489+
490+ /**
491+ * Sends the APPE command to the server in order to transfer a data stream
492+ * passed in argument and append it to the content of the specified remote
493+ * file.
494+ *
495+ * <p>This method will block until the transfer is complete or an exception
496+ * is thrown.</p>
497+ *
498+ * @param name A {@code String} containing the name of the remote file
499+ * to append to.
500+ * @param local The {@code InputStream} providing access to the data
501+ * to be appended.
502+ * @return this FtpClient
503+ * @throws IOException if an error occured during the transmission.
504+ * @throws FtpProtocolException if the command was rejected by the server
505+ */
506+ public abstract FtpClient appendFile(String name, InputStream local) throws FtpProtocolException, IOException;
507+
508+ /**
509+ * Renames a file on the server.
510+ *
511+ * @param from the name of the file being renamed
512+ * @param to the new name for the file
513+ * @return this FtpClient
514+ * @throws IOException if an error occured during the transmission.
515+ * @throws FtpProtocolException if the command was rejected by the server
516+ */
517+ public abstract FtpClient rename(String from, String to) throws FtpProtocolException, IOException;
518+
519+ /**
520+ * Deletes a file on the server.
521+ *
522+ * @param name a {@code String} containing the name of the file
523+ * to delete.
524+ * @return this FtpClient
525+ * @throws IOException if an error occured during the exchange
526+ * @throws FtpProtocolException if the command was rejected by the server
527+ */
528+ public abstract FtpClient deleteFile(String name) throws FtpProtocolException, IOException;
529+
530+ /**
531+ * Creates a new directory on the server.
532+ *
533+ * @param name a {@code String} containing the name of the directory
534+ * to create.
535+ * @return this FtpClient
536+ * @throws IOException if an error occured during the exchange
537+ * @throws FtpProtocolException if the command was rejected by the server
538+ */
539+ public abstract FtpClient makeDirectory(String name) throws FtpProtocolException, IOException;
540+
541+ /**
542+ * Removes a directory on the server.
543+ *
544+ * @param name a {@code String} containing the name of the directory
545+ * to remove.
546+ *
547+ * @return this FtpClient
548+ * @throws IOException if an error occured during the exchange.
549+ * @throws FtpProtocolException if the command was rejected by the server
550+ */
551+ public abstract FtpClient removeDirectory(String name) throws FtpProtocolException, IOException;
552+
553+ /**
554+ * Sends a No-operation command. It's useful for testing the connection
555+ * status or as a <I>keep alive</I> mechanism.
556+ *
557+ * @return this FtpClient
558+ * @throws IOException if an error occured during the transmission.
559+ * @throws FtpProtocolException if the command was rejected by the server
560+ */
561+ public abstract FtpClient noop() throws FtpProtocolException, IOException;
562+
563+ /**
564+ * Sends the {@code STAT} command to the server.
565+ * This can be used while a data connection is open to get a status
566+ * on the current transfer, in that case the parameter should be
567+ * {@code null}.
568+ * If used between file transfers, it may have a pathname as argument
569+ * in which case it will work as the LIST command except no data
570+ * connection will be created.
571+ *
572+ * @param name an optional {@code String} containing the pathname
573+ * the STAT command should apply to.
574+ * @return the response from the server
575+ * @throws IOException if an error occured during the transmission.
576+ * @throws FtpProtocolException if the command was rejected by the server
577+ */
578+ public abstract String getStatus(String name) throws FtpProtocolException, IOException;
579+
580+ /**
581+ * Sends the {@code FEAT} command to the server and returns the list of supported
582+ * features in the form of strings.
583+ *
584+ * The features are the supported commands, like AUTH TLS, PROT or PASV.
585+ * See the RFCs for a complete list.
586+ *
587+ * Note that not all FTP servers support that command, in which case
588+ * a {@link FtpProtocolException} will be thrown.
589+ *
590+ * @return a {@code List} of {@code Strings} describing the
591+ * supported additional features
592+ * @throws IOException if an error occurs during the transmission.
593+ * @throws FtpProtocolException if the command is rejected by the server
594+ */
595+ public abstract List<String> getFeatures() throws FtpProtocolException, IOException;
596+
597+ /**
598+ * Sends the {@code ABOR} command to the server.
599+ * <p>It tells the server to stop the previous command or transfer. No action
600+ * will be taken if the previous command has already been completed.</p>
601+ * <p>This doesn't abort the current session, more commands can be issued
602+ * after an abort.</p>
603+ *
604+ * @return this FtpClient
605+ * @throws IOException if an error occured during the transmission.
606+ * @throws FtpProtocolException if the command was rejected by the server
607+ */
608+ public abstract FtpClient abort() throws FtpProtocolException, IOException;
609+
610+ /**
611+ * Some methods do not wait until completion before returning, so this
612+ * method can be called to wait until completion. This is typically the case
613+ * with commands that trigger a transfer like {@link #getFileStream(String)}.
614+ * So this method should be called before accessing information related to
615+ * such a command.
616+ * <p>This method will actually block reading on the command channel for a
617+ * notification from the server that the command is finished. Such a
618+ * notification often carries extra information concerning the completion
619+ * of the pending action (e.g. number of bytes transfered).</p>
620+ * <p>Note that this will return immediately if no command or action
621+ * is pending</p>
622+ * <p>It should be also noted that most methods issuing commands to the ftp
623+ * server will call this method if a previous command is pending.
624+ * <p>Example of use:
625+ * <pre>
626+ * InputStream in = cl.getFileStream("file");
627+ * ...
628+ * cl.completePending();
629+ * long size = cl.getLastTransferSize();
630+ * </pre>
631+ * On the other hand, it's not necessary in a case like:
632+ * <pre>
633+ * InputStream in = cl.getFileStream("file");
634+ * // read content
635+ * ...
636+ * cl.close();
637+ * </pre>
638+ * <p>Since {@link #close()} will call completePending() if necessary.</p>
639+ * @return this FtpClient
640+ * @throws IOException if an error occured during the transfer
641+ * @throws FtpProtocolException if the command didn't complete successfully
642+ */
643+ public abstract FtpClient completePending() throws FtpProtocolException, IOException;
644+
645+ /**
646+ * Reinitializes the USER parameters on the FTP server
647+ *
648+ * @return this FtpClient
649+ * @throws IOException if an error occurs during transmission
650+ * @throws FtpProtocolException if the command fails
651+ */
652+ public abstract FtpClient reInit() throws FtpProtocolException, IOException;
653+
654+ /**
655+ * Changes the transfer type (binary, ascii, ebcdic) and issue the
656+ * proper command (e.g. TYPE A) to the server.
657+ *
658+ * @param type the {@code TransferType} to use.
659+ * @return This FtpClient
660+ * @throws IOException if an error occurs during transmission.
661+ * @throws FtpProtocolException if the command was rejected by the server
662+ */
663+ public abstract FtpClient setType(TransferType type) throws FtpProtocolException, IOException;
664+
665+ /**
666+ * Changes the current transfer type to binary.
667+ * This is a convenience method that is equivalent to
668+ * {@code setType(TransferType.BINARY)}
669+ *
670+ * @return This FtpClient
671+ * @throws IOException if an error occurs during the transmission.
672+ * @throws FtpProtocolException if the command was rejected by the server
673+ * @see #setType(TransferType)
674+ */
675+ public FtpClient setBinaryType() throws FtpProtocolException, IOException {
676+ setType(TransferType.BINARY);
677+ return this;
678+ }
679+
680+ /**
681+ * Changes the current transfer type to ascii.
682+ * This is a convenience method that is equivalent to
683+ * {@code setType(TransferType.ASCII)}
684+ *
685+ * @return This FtpClient
686+ * @throws IOException if an error occurs during the transmission.
687+ * @throws FtpProtocolException if the command was rejected by the server
688+ * @see #setType(TransferType)
689+ */
690+ public FtpClient setAsciiType() throws FtpProtocolException, IOException {
691+ setType(TransferType.ASCII);
692+ return this;
693+ }
694+
695+ /**
696+ * Issues a {@code LIST} command to the server to get the current directory
697+ * listing, and returns the InputStream from the data connection.
698+ *
699+ * <p>{@link #completePending()} <b>has</b> to be called once the application
700+ * is finished reading from the stream.</p>
701+ *
702+ * @param path the pathname of the directory to list, or {@code null}
703+ * for the current working directory.
704+ * @return the {@code InputStream} from the resulting data connection
705+ * @throws IOException if an error occurs during the transmission.
706+ * @throws FtpProtocolException if the command was rejected by the server
707+ * @see #changeDirectory(String)
708+ * @see #listFiles(String)
709+ */
710+ public abstract InputStream list(String path) throws FtpProtocolException, IOException;
711+
712+ /**
713+ * Issues a {@code NLST path} command to server to get the specified directory
714+ * content. It differs from {@link #list(String)} method by the fact that
715+ * it will only list the file names which would make the parsing of the
716+ * somewhat easier.
717+ *
718+ * <p>{@link #completePending()} <b>has</b> to be called once the application
719+ * is finished reading from the stream.</p>
720+ *
721+ * @param path a {@code String} containing the pathname of the
722+ * directory to list or {@code null} for the current working directory.
723+ * @return the {@code InputStream} from the resulting data connection
724+ * @throws IOException if an error occurs during the transmission.
725+ * @throws FtpProtocolException if the command was rejected by the server
726+ */
727+ public abstract InputStream nameList(String path) throws FtpProtocolException, IOException;
728+
729+ /**
730+ * Issues the {@code SIZE [path]} command to the server to get the size of a
731+ * specific file on the server.
732+ * Note that this command may not be supported by the server. In which
733+ * case -1 will be returned.
734+ *
735+ * @param path a {@code String} containing the pathname of the
736+ * file.
737+ * @return a {@code long} containing the size of the file or -1 if
738+ * the server returned an error, which can be checked with
739+ * {@link #getLastReplyCode()}.
740+ * @throws IOException if an error occurs during the transmission.
741+ * @throws FtpProtocolException if the command was rejected by the server
742+ */
743+ public abstract long getSize(String path) throws FtpProtocolException, IOException;
744+
745+ /**
746+ * Issues the {@code MDTM [path]} command to the server to get the modification
747+ * time of a specific file on the server.
748+ * Note that this command may not be supported by the server, in which
749+ * case {@code null} will be returned.
750+ *
751+ * @param path a {@code String} containing the pathname of the file.
752+ * @return a {@code Date} representing the last modification time
753+ * or {@code null} if the server returned an error, which
754+ * can be checked with {@link #getLastReplyCode()}.
755+ * @throws IOException if an error occurs during the transmission.
756+ * @throws FtpProtocolException if the command was rejected by the server
757+ */
758+ public abstract Date getLastModified(String path) throws FtpProtocolException, IOException;
759+
760+ /**
761+ * Sets the parser used to handle the directory output to the specified
762+ * one. By default the parser is set to one that can handle most FTP
763+ * servers output (Unix base mostly). However it may be necessary for
764+ * and application to provide its own parser due to some uncommon
765+ * output format.
766+ *
767+ * @param p The {@code FtpDirParser} to use.
768+ * @return this FtpClient
769+ * @see #listFiles(String)
770+ */
771+ public abstract FtpClient setDirParser(FtpDirParser p);
772+
773+ /**
774+ * Issues a {@code MLSD} command to the server to get the specified directory
775+ * listing and applies the internal parser to create an Iterator of
776+ * {@link java.net.FtpDirEntry}. Note that the Iterator returned is also a
777+ * {@link java.io.Closeable}.
778+ * <p>If the server doesn't support the MLSD command, the LIST command is used
779+ * instead and the parser set by {@link #setDirParser(java.net.FtpDirParser) }
780+ * is used instead.</p>
781+ *
782+ * {@link #completePending()} <b>has</b> to be called once the application
783+ * is finished iterating through the files.
784+ *
785+ * @param path the pathname of the directory to list or {@code null}
786+ * for the current working directoty.
787+ * @return a {@code Iterator} of files or {@code null} if the
788+ * command failed.
789+ * @throws IOException if an error occured during the transmission
790+ * @see #setDirParser(FtpDirParser)
791+ * @see #changeDirectory(String)
792+ * @throws FtpProtocolException if the command was rejected by the server
793+ */
794+ public abstract Iterator<FtpDirEntry> listFiles(String path) throws FtpProtocolException, IOException;
795+
796+ /**
797+ * Attempts to use Kerberos GSSAPI as an authentication mechanism with the
798+ * ftp server. This will issue an {@code AUTH GSSAPI} command, and if
799+ * it is accepted by the server, will followup with {@code ADAT}
800+ * command to exchange the various tokens until authentication is
801+ * successful. This conforms to Appendix I of RFC 2228.
802+ *
803+ * @return this FtpClient
804+ * @throws IOException if an error occurs during the transmission.
805+ * @throws FtpProtocolException if the command was rejected by the server
806+ */
807+ public abstract FtpClient useKerberos() throws FtpProtocolException, IOException;
808+
809+ /**
810+ * Returns the Welcome string the server sent during initial connection.
811+ *
812+ * @return a {@code String} containing the message the server
813+ * returned during connection or {@code null}.
814+ */
815+ public abstract String getWelcomeMsg();
816+
817+ /**
818+ * Returns the last reply code sent by the server.
819+ *
820+ * @return the lastReplyCode or {@code null} if none were received yet.
821+ */
822+ public abstract FtpReplyCode getLastReplyCode();
823+
824+ /**
825+ * Returns the last response string sent by the server.
826+ *
827+ * @return the message string, which can be quite long, last returned
828+ * by the server, or {@code null} if no response were received yet.
829+ */
830+ public abstract String getLastResponseString();
831+
832+ /**
833+ * Returns, when available, the size of the latest started transfer.
834+ * This is retreived by parsing the response string received as an initial
835+ * response to a {@code RETR} or similar request.
836+ *
837+ * @return the size of the latest transfer or -1 if either there was no
838+ * transfer or the information was unavailable.
839+ */
840+ public abstract long getLastTransferSize();
841+
842+ /**
843+ * Returns, when available, the remote name of the last transfered file.
844+ * This is mainly useful for "put" operation when the unique flag was
845+ * set since it allows to recover the unique file name created on the
846+ * server which may be different from the one submitted with the command.
847+ *
848+ * @return the name the latest transfered file remote name, or
849+ * {@code null} if that information is unavailable.
850+ */
851+ public abstract String getLastFileName();
852+
853+ /**
854+ * Attempts to switch to a secure, encrypted connection. This is done by
855+ * sending the {@code AUTH TLS} command.
856+ * <p>See <a href="http://www.ietf.org/rfc/rfc4217.txt">RFC 4217</a></p>
857+ * If successful this will establish a secure command channel with the
858+ * server, it will also make it so that all other transfers (e.g. a RETR
859+ * command) will be done over an encrypted channel as well unless a
860+ * {@link #reInit()} command or a {@link #endSecureSession()} command is issued.
861+ * <p>This method should be called after a successful {@link #connect(java.net.InetSocketAddress) }
862+ * but before calling {@link #login(java.lang.String, char[]) }.</p>
863+ *
864+ * @return this FtpCLient
865+ * @throws IOException if an error occured during the transmission.
866+ * @throws FtpProtocolException if the command was rejected by the server
867+ * @see #endSecureSession()
868+ */
869+ public abstract FtpClient startSecureSession() throws FtpProtocolException, IOException;
870+
871+ /**
872+ * Sends a {@code CCC} command followed by a {@code PROT C}
873+ * command to the server terminating an encrypted session and reverting
874+ * back to a non encrypted transmission.
875+ *
876+ * @return this FtpClient
877+ * @throws IOException if an error occured during transmission.
878+ * @throws FtpProtocolException if the command was rejected by the server
879+ * @see #startSecureSession()
880+ */
881+ public abstract FtpClient endSecureSession() throws FtpProtocolException, IOException;
882+
883+ /**
884+ * Sends the "Allocate" ({@code ALLO}) command to the server telling it to
885+ * pre-allocate the specified number of bytes for the next transfer.
886+ *
887+ * @param size The number of bytes to allocate.
888+ * @return this FtpClient
889+ * @throws IOException if an error occured during the transmission.
890+ * @throws FtpProtocolException if the command was rejected by the server
891+ */
892+ public abstract FtpClient allocate(long size) throws FtpProtocolException, IOException;
893+
894+ /**
895+ * Sends the "Structure Mount" ({@code SMNT}) command to the server. This let the
896+ * user mount a different file system data structure without altering his
897+ * login or accounting information.
898+ *
899+ * @param struct a {@code String} containing the name of the
900+ * structure to mount.
901+ * @return this FtpClient
902+ * @throws IOException if an error occured during the transmission.
903+ * @throws FtpProtocolException if the command was rejected by the server
904+ */
905+ public abstract FtpClient structureMount(String struct) throws FtpProtocolException, IOException;
906+
907+ /**
908+ * Sends a System ({@code SYST}) command to the server and returns the String
909+ * sent back by the server describing the operating system at the
910+ * server.
911+ *
912+ * @return a {@code String} describing the OS, or {@code null}
913+ * if the operation was not successful.
914+ * @throws IOException if an error occured during the transmission.
915+ * @throws FtpProtocolException if the command was rejected by the server
916+ */
917+ public abstract String getSystem() throws FtpProtocolException, IOException;
918+
919+ /**
920+ * Sends the {@code HELP} command to the server, with an optional command, like
921+ * SITE, and returns the text sent back by the server.
922+ *
923+ * @param cmd the command for which the help is requested or
924+ * {@code null} for the general help
925+ * @return a {@code String} containing the text sent back by the
926+ * server, or {@code null} if the command failed.
927+ * @throws IOException if an error occured during transmission
928+ * @throws FtpProtocolException if the command was rejected by the server
929+ */
930+ public abstract String getHelp(String cmd) throws FtpProtocolException, IOException;
931+
932+ /**
933+ * Sends the {@code SITE} command to the server. This is used by the server
934+ * to provide services specific to his system that are essential
935+ * to file transfer.
936+ *
937+ * @param cmd the command to be sent.
938+ * @return this FtpClient
939+ * @throws IOException if an error occured during transmission
940+ * @throws FtpProtocolException if the command was rejected by the server
941+ */
942+ public abstract FtpClient siteCmd(String cmd) throws FtpProtocolException, IOException;
943+}