001: /**
002: *
003: * edtFTPj
004: *
005: * Copyright (C) 2000-2003 Enterprise Distributed Technologies Ltd
006: *
007: * www.enterprisedt.com
008: *
009: * This library is free software; you can redistribute it and/or
010: * modify it under the terms of the GNU Lesser General Public
011: * License as published by the Free Software Foundation; either
012: * version 2.1 of the License, or (at your option) any later version.
013: *
014: * This library is distributed in the hope that it will be useful,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017: * Lesser General Public License for more details.
018: *
019: * You should have received a copy of the GNU Lesser General Public
020: * License along with this library; if not, write to the Free Software
021: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
022: *
023: * Bug fixes, suggestions and comments should be should posted on
024: * http://www.enterprisedt.com/forums/index.php
025: *
026: * Change Log:
027: *
028: * $Log: FTPClientInterface.java,v $
029: * Revision 1.17 2007-08-07 04:45:04 bruceb
030: * added counts for transfers and deletes
031: *
032: * Revision 1.16 2007/03/19 22:06:57 bruceb
033: * add connected()
034: *
035: * Revision 1.15 2007/02/07 23:02:55 bruceb
036: * added keepAlive() & quitImmediately()
037: *
038: * Revision 1.14 2007/02/01 05:10:32 bruceb
039: * enhance comment
040: *
041: * Revision 1.13 2007/01/15 23:04:51 bruceb
042: * minor comment change
043: *
044: * Revision 1.12 2007/01/10 02:38:25 bruceb
045: * added getId() and modified gets to return filename
046: *
047: * Revision 1.11 2006/11/14 11:40:42 bruceb
048: * fix comment
049: *
050: * Revision 1.10 2006/09/11 12:34:00 bruceb
051: * added exists() method
052: *
053: * Revision 1.9 2006/02/09 09:02:15 bruceb
054: * fixed comment re dirname
055: *
056: * Revision 1.8 2005/11/15 21:02:14 bruceb
057: * augment javadoc
058: *
059: * Revision 1.7 2005/11/10 19:45:18 bruceb
060: * added resume & cancel methods
061: *
062: * Revision 1.6 2005/11/09 21:15:19 bruceb
063: * added set/get for autodetect
064: *
065: * Revision 1.5 2005/10/10 20:42:56 bruceb
066: * append now in FTPClientInterface
067: *
068: * Revision 1.4 2005/07/11 21:14:58 bruceb
069: * add set/get transfer type
070: *
071: * Revision 1.3 2005/06/16 21:41:34 hans
072: * Added RemoteHost and RemotePort accessors as well as connect() method.
073: *
074: * Revision 1.2 2005/06/03 11:26:25 bruceb
075: * comment change
076: */package com.enterprisedt.net.ftp;
077:
078: import java.io.IOException;
079: import java.io.InputStream;
080: import java.io.OutputStream;
081: import java.text.ParseException;
082: import java.util.Date;
083:
084: /**
085: * Defines operations in common with a number of FTP implementations.
086: *
087: * @author Hans Andersen
088: * @version $Revision: 1.17 $
089: */
090: public interface FTPClientInterface {
091:
092: /**
093: * Get the identifying string for this instance
094: *
095: * @return identifying string
096: */
097: public String getId();
098:
099: /**
100: * Set the identifying string for this instance
101: *
102: * @param id identifying string
103: */
104: public void setId(String id);
105:
106: /**
107: * Returns the IP address or name of the remote host.
108: *
109: * @return Returns the remote host.
110: */
111: public String getRemoteHost();
112:
113: /**
114: * Set the IP address or name of the remote host
115: *
116: * This may only be done if the client is not already connected to the server.
117: *
118: * @param remoteHost The IP address or name of the remote host
119: * @throws FTPException Thrown if the client is already connected to the server.
120: */
121: public void setRemoteHost(String remoteHost) throws IOException,
122: FTPException;
123:
124: /**
125: * Returns the port being connected to on the remote server.
126: *
127: * @return Returns the port being connected to on the remote server.
128: */
129: public int getRemotePort();
130:
131: /**
132: * Set the port to connect to on the remote server. Can only do this if
133: * not already connected.
134: *
135: * @param remotePort The port to use.
136: * @throws FTPException Thrown if the client is already connected to the server.
137: */
138: public void setRemotePort(int remotePort) throws FTPException;
139:
140: /**
141: * Get the TCP timeout on the underlying socket(s).
142: *
143: * A value of 0 (the default) means that there
144: * are no timeouts.
145: *
146: * @return timeout that is used, in milliseconds
147: */
148: public int getTimeout();
149:
150: /**
151: * Set the TCP timeout on the underlying socket(s).
152: *
153: * Timeouts should be set before connections are made.
154: * If a timeout is set, then any operation which
155: * takes longer than the timeout value will be
156: * killed with a java.io.InterruptedException.
157: * The default is 0 meaning that the connection
158: * never times out.
159: *
160: * @param millis The length of the timeout, in milliseconds
161: */
162: public void setTimeout(int millis) throws IOException, FTPException;
163:
164: /**
165: * Set a progress monitor for callbacks. The bytes transferred in
166: * between callbacks is only indicative. In many cases, the data is
167: * read in chunks, and if the interval is set to be smaller than the
168: * chunk size, the callback will occur after after chunk transfer rather
169: * than the interval. Depending on the implementation, the chunk size can
170: * be as large as 64K.
171: *
172: * @param monitor the monitor object
173: * @param interval bytes transferred in between callbacks
174: */
175: public void setProgressMonitor(FTPProgressMonitor monitor,
176: long interval);
177:
178: /**
179: * Set a progress monitor for callbacks. Uses default callback
180: * interval
181: *
182: * @param monitor the monitor object
183: */
184: public void setProgressMonitor(FTPProgressMonitor monitor);
185:
186: /**
187: * Get the bytes transferred between each callback on the
188: * progress monitor
189: *
190: * @return long bytes to be transferred before a callback
191: */
192: public long getMonitorInterval();
193:
194: /**
195: * Set autodetect of filetypes on or off. If on, the transfer mode is
196: * switched from ASCII to binary and vice versa depending on the extension
197: * of the file. After the transfer, the mode is always returned to what it
198: * was before the transfer was performed. The default is off.
199: *
200: * If the filetype is unknown, the transfer mode is unchanged
201: *
202: * @param detectTransferMode true if detecting transfer mode, false if not
203: */
204: public void setDetectTransferMode(boolean detectTransferMode);
205:
206: /**
207: * Get the detect transfer mode
208: *
209: * @return true if we are detecting binary and ASCII transfers from the file type
210: */
211: public boolean getDetectTransferMode();
212:
213: /**
214: * Connects to the server at the address and port number defined
215: * in the constructor.
216: *
217: * @throws IOException Thrown if there is a TCP/IP-related error.
218: * @throws FTPException Thrown if there is an error related to the FTP protocol.
219: */
220: public void connect() throws IOException, FTPException;
221:
222: /**
223: * Is the client currently connected?
224: *
225: * @return true if connected, false otherwise
226: */
227: public boolean connected();
228:
229: /**
230: * Get the size of a remote file. This is not a standard FTP command, it
231: * is defined in "Extensions to FTP", a draft RFC
232: * (draft-ietf-ftpext-mlst-16.txt)
233: *
234: * @param remoteFile name or path of remote file in current directory
235: * @return size of file in bytes
236: */
237: public long size(String remoteFile) throws IOException,
238: FTPException;
239:
240: /**
241: * Does the named file exist in the current server directory?
242: *
243: * @param remoteFile name of remote file
244: * @return true if exists, false otherwise
245: * @throws IOException
246: * @throws FTPException
247: */
248: public boolean exists(String remoteFile) throws IOException,
249: FTPException;
250:
251: /**
252: * Get the current transfer type
253: *
254: * @return the current type of the transfer,
255: * i.e. BINARY or ASCII
256: */
257: public FTPTransferType getType();
258:
259: /**
260: * Set the transfer type
261: *
262: * @param type the transfer type to
263: * set the server to
264: */
265: public void setType(FTPTransferType type) throws IOException,
266: FTPException;
267:
268: /**
269: * Make the next file transfer (put or get) resume. For puts(), the
270: * bytes already transferred are skipped over, while for gets(), if
271: * writing to a file, it is opened in append mode, and only the bytes
272: * required are transferred.
273: *
274: * Currently resume is only supported for BINARY transfers (which is
275: * generally what it is most useful for).
276: *
277: * @throws FTPException
278: */
279: public void resume() throws FTPException;
280:
281: /**
282: * Cancel the resume. Use this method if something goes wrong
283: * and the server is left in an inconsistent state
284: *
285: * @throws IOException
286: * @throws FTPException
287: */
288: public void cancelResume() throws IOException, FTPException;
289:
290: /**
291: * Cancels the current transfer. Generally called from a separate
292: * thread. Note that this may leave partially written files on the
293: * server or on local disk, and should not be used unless absolutely
294: * necessary. After the transfer is cancelled the connection may be in
295: * an inconsistent state, therefore it is best to quit and reconnect.
296: * It may cause exceptions to be thrown depending on the underlying protocol
297: * being used. Note that this can also be used to cancel directory listings,
298: * which can involve large amounts of data for directories containing many
299: * files.
300: */
301: public void cancelTransfer();
302:
303: /**
304: * Put a local file onto the FTP server. It
305: * is placed in the current directory. If a remote file name is supplied,
306: * it is stored as that name on the server. If null is supplied, the server
307: * will generate a unique filename (via STOU) if it supports this option.
308: *
309: * @param localPath path of the local file
310: * @param remoteFile name of remote file in
311: * current directory, or null if
312: * a unique filename is to be generated by the server
313: * @return The name of the remote file - normally the name supplied, or else
314: * the unique name generated by the server.
315: */
316: public String put(String localPath, String remoteFile)
317: throws IOException, FTPException;
318:
319: /**
320: * Put a stream of data onto the FTP server. It
321: * is placed in the current directory. If a remote file name is supplied,
322: * it is stored as that name on the server. If null is supplied, the server
323: * will generate a unique filename (via STOU) if it supports this option.
324: *
325: * @param srcStream input stream of data to put
326: * @param remoteFile name of remote file in
327: * current directory, or null if
328: * a unique filename is to be generated by the server
329: * @return The name of the remote file - normally the name supplied, or else
330: * the unique name generated by the server.
331: */
332: public String put(InputStream srcStream, String remoteFile)
333: throws IOException, FTPException;
334:
335: /**
336: * Put a stream of data onto the FTP server. It
337: * is placed in the current directory. If a remote file name is supplied,
338: * it is stored as that name on the server. If null is supplied, the server
339: * will generate a unique filename (via STOU) if it supports this option.
340: * Allows appending if current file exists.
341: *
342: * @param srcStream input stream of data to put
343: * @param remoteFile name of remote file in
344: * current directory, or null if
345: * a unique filename is to be generated by the server
346: * @param append true if appending, false otherwise
347: * @return The name of the remote file - normally the name supplied, or else
348: * the unique name generated by the server.
349: */
350: public String put(InputStream srcStream, String remoteFile,
351: boolean append) throws IOException, FTPException;
352:
353: /**
354: * Put data onto the FTP server. It
355: * is placed in the current directory. If a remote file name is supplied,
356: * it is stored as that name on the server. If null is supplied, the server
357: * will generate a unique filename (via STOU) if it supports this option.
358: *
359: * @param bytes array of bytes
360: * @param remoteFile name of remote file in
361: * current directory, or null if
362: * a unique filename is to be generated by the server
363: * @return The name of the remote file - normally the name supplied, or else
364: * the unique name generated by the server.
365: */
366: public String put(byte[] bytes, String remoteFile)
367: throws IOException, FTPException;
368:
369: /**
370: * Put data onto the FTP server. It
371: * is placed in the current directory. If a remote file name is supplied,
372: * it is stored as that name on the server. If null is supplied, the server
373: * will generate a unique filename (via STOU) if it supports this option.
374: * Allows appending if current file exists.
375: *
376: * @param bytes array of bytes
377: * @param remoteFile name of remote file in
378: * current directory, or null if
379: * a unique filename is to be generated by the server
380: * @param append true if appending, false otherwise
381: * @return The name of the remote file - normally the name supplied, or else
382: * the unique name generated by the server.
383: */
384: public String put(byte[] bytes, String remoteFile, boolean append)
385: throws IOException, FTPException;
386:
387: /**
388: * Put a local file onto the FTP server. It
389: * is placed in the current directory. If a remote file name is supplied,
390: * it is stored as that name on the server. If null is supplied, the server
391: * will generate a unique filename (via STOU) if it supports this option.
392: * Allows appending if current file exists.
393: *
394: * @param localPath path of the local file
395: * @param remoteFile name of remote file in current directory, or null if
396: * a unique filename is to be generated by the server
397: * @param append true if appending, false otherwise
398: * @return The name of the remote file - normally the name supplied, or else
399: * the unique name generated by the server.
400: */
401: public String put(String localPath, String remoteFile,
402: boolean append) throws IOException, FTPException;
403:
404: /**
405: * Get data from the FTP server. Uses the currently
406: * set transfer mode.
407: *
408: * @param localPath local file to put data in
409: * @param remoteFile name of remote file in
410: * current directory
411: */
412: public void get(String localPath, String remoteFile)
413: throws IOException, FTPException;
414:
415: /**
416: * Get data from the FTP server. Uses the currently
417: * set transfer mode.
418: *
419: * @param destStream data stream to write data to
420: * @param remoteFile name of remote file in
421: * current directory
422: */
423: public void get(OutputStream destStream, String remoteFile)
424: throws IOException, FTPException;
425:
426: /**
427: * Get data from the FTP server. Transfers in
428: * whatever mode we are in. Retrieve as a byte array. Note
429: * that we may experience memory limitations as the
430: * entire file must be held in memory at one time.
431: *
432: * @param remoteFile name of remote file in
433: * current directory
434: */
435: public byte[] get(String remoteFile) throws IOException,
436: FTPException;
437:
438: /**
439: * Get the number of files downloaded since the count was
440: * reset
441: *
442: * @return download file count
443: */
444: public int getDownloadCount();
445:
446: /**
447: * Reset the count of downloaded files to zero.
448: *
449: */
450: public void resetDownloadCount();
451:
452: /**
453: * Get the number of files uploaded since the count was
454: * reset
455: *
456: * @return upload file count
457: */
458: public int getUploadCount();
459:
460: /**
461: * Reset the count of uploaded files to zero.
462: *
463: */
464: public void resetUploadCount();
465:
466: /**
467: * Get the number of files deleted since the count was
468: * reset
469: *
470: * @return deleted file count
471: */
472: public int getDeleteCount();
473:
474: /**
475: * Reset the count of deleted files to zero.
476: *
477: */
478: public void resetDeleteCount();
479:
480: /**
481: * List a directory's contents as an array of FTPFile objects.
482: * Should work for Windows and most Unix FTP servers - let us know
483: * about unusual formats (http://www.enterprisedt.com/forums/index.php).
484: * If accurate timestamps are required (i.e. to the second), it is
485: * generally better to use @see #modtime(String).
486: *
487: * @param dirname name of directory (some servers permit a filemask)
488: * @return an array of FTPFile objects
489: */
490: public FTPFile[] dirDetails(String dirname) throws IOException,
491: FTPException, ParseException;
492:
493: /**
494: * List current directory's contents as an array of strings of
495: * filenames.
496: *
497: * @return an array of current directory listing strings
498: */
499: public String[] dir() throws IOException, FTPException;
500:
501: /**
502: * List a directory's contents as an array of strings of filenames.
503: *
504: * @param dirname name of directory OR filemask
505: * @return an array of directory listing strings
506: */
507: public String[] dir(String dirname) throws IOException,
508: FTPException;
509:
510: /**
511: * List a directory's contents as an array of strings. A detailed
512: * listing is available, otherwise just filenames are provided.
513: * The detailed listing varies in details depending on OS and
514: * FTP server. Note that a full listing can be used on a file
515: * name to obtain information about a file
516: *
517: * @param dirname name of directory OR filemask
518: * @param full true if detailed listing required
519: * false otherwise
520: * @return an array of directory listing strings
521: */
522: public String[] dir(String dirname, boolean full)
523: throws IOException, FTPException;
524:
525: /**
526: * Delete the specified remote file
527: *
528: * @param remoteFile name of remote file to
529: * delete
530: */
531: public void delete(String remoteFile) throws IOException,
532: FTPException;
533:
534: /**
535: * Rename a file or directory
536: *
537: * @param from name of file or directory to rename
538: * @param to intended name
539: */
540: public void rename(String from, String to) throws IOException,
541: FTPException;
542:
543: /**
544: * Delete the specified remote working directory
545: *
546: * @param dir name of remote directory to
547: * delete
548: */
549: public void rmdir(String dir) throws IOException, FTPException;
550:
551: /**
552: * Create the specified remote working directory
553: *
554: * @param dir name of remote directory to
555: * create
556: */
557: public void mkdir(String dir) throws IOException, FTPException;
558:
559: /**
560: * Change the remote working directory to
561: * that supplied
562: *
563: * @param dir name of remote directory to
564: * change to
565: */
566: public void chdir(String dir) throws IOException, FTPException;
567:
568: /**
569: * Change the remote working directory to
570: * the parent directory
571: */
572: public void cdup() throws IOException, FTPException;
573:
574: /**
575: * Get modification time for a remote file. For accurate
576: * modification times (e.g. to the second) this method is to
577: * be preferred over @see #dirDetails(java.lang.String) which
578: * parses a listing returned by the server. The timezone is GMT.
579: *
580: * @param remoteFile name of remote file
581: * @return modification time of file as a date
582: */
583: public Date modtime(String remoteFile) throws IOException,
584: FTPException;
585:
586: /**
587: * Get the current remote working directory
588: *
589: * @return the current working directory
590: */
591: public String pwd() throws IOException, FTPException;
592:
593: /**
594: * Tries to keep the current connection alive by
595: * some means, usually by sending an innocuous commmand.
596: */
597: public void keepAlive() throws IOException, FTPException;
598:
599: /**
600: * Quit the FTP session
601: *
602: */
603: public void quit() throws IOException, FTPException;
604:
605: /**
606: * Quit the FTP session immediately. If a transfer is underway
607: * it will be terminated.
608: *
609: */
610: public void quitImmediately() throws IOException, FTPException;
611:
612: }
|